‍

‍

Introduction: APIs Are Built for Humans, Not AI

APIs were never meant for artificial intelligence. They were built for developers: people who can reason, experiment, and piece together multiple endpoints into a workflow.

But with the rise of AI agents—powered by large language models (LLMs)—that old model is breaking. AI agents don’t explore like humans. They follow reasoning chains, working step by step toward a goal. And when we hand them APIs designed for people, they stumble.

The result? Confused agents, wasted tokens, unnecessary API calls, and poor performance.

The good news is that we don’t have to reinvent the wheel—we just need to rethink how we expose APIs to agents through the Model Context Protocol (MCP).

Why Human-Centric APIs Break for AI

A developer expects an API to have many small, composable endpoints. That flexibility is powerful for humans who know what to use and when. But for AI agents, it’s overwhelming.

Common Pitfalls When Converting APIs to MCP:

• Too many options → Agents don’t know which call to choose.
• Unclear purposes → Human-friendly descriptions don’t map to machine reasoning.
• Extra steps → Agents need multiple calls for tasks a person does in one mental step.

The outcome is predictable: agents either fail outright or take long, inefficient paths to solve simple tasks.

Example: Flight Booking API Gone Wrong

Imagine converting a flight booking system’s REST APIs into MCP tools. If a user asks an agent:
"Find me the cheapest direct flight to Paris in June."

The workflow might look like this:

GET /airports/search?query=paris  
GET /airlines/list  
GET /flights/search?origin=JFK&destination=CDG&departure_date=2024-06-01  
GET /flights/search?origin=JFK&destination=CDG&departure_date=2024-06-02  
... repeated for every day in June ...  
GET /flights/{id}/details  
GET /flights/filter?direct_only=true  
GET /flights/sort?by=price&order=asc  
GET /pricing/calculate?flight_id=123&passengers=1  


For a developer, this makes sense: lots of modular calls to stitch together. For an agent, it’s chaos.

The Solution: Think Like an Agent, Not a Human

To fix this, we must stop exposing APIs 1:1 and instead design for the way agents reason. Agents don’t want endless options—they need clear, goal-oriented tools.

Design Principles for Agent-Friendly MCP Tools:

1. Group related actions: Combine steps into higher-level functions.
2. Think in flows: Represent the end-to-end sequence for a goal.
3. Tell a story: Define tools in terms of agent stories and user scenarios.
4. Simplify decisions: Remove branches where the agent might guess wrong.

Using Agent Stories

Netlify’s CEO, Mathias Biilmann, recently introduced the concept of Agent Experience (AX): designing APIs with the agent as a primary persona, just like we design user interfaces for humans.

One way to design better MCP tools is through agent stories: short narratives describing how an agent completes a task with your tools.

Old Flow (Too Complex)

Dozens of individual calls to search, filter, sort, and calculate flight prices.

New Flow (Agent-Friendly)

‍

searchFlights(destination="Paris", month="June", departure_city="New York")  
selectBestFlight(criteria="cheapest")  
findCheapestDirectFlights(destination="Paris", month="June", departure_city="New York", limit=3)  

This reframing reduces cognitive load for agents and makes them far more reliable.

Designing MCP Flows Instead of Endpoints

The difference between endpoints and flows is critical:

• Endpoints: Atomic functions (search, filter, sort) meant for humans.
• Flows: Goal-oriented sequences designed for agents.

Tips for Designing Flows:

• Group actions that belong together (e.g., search + filter + sort).
• Provide descriptive tool names like findCheapestDirectFlights instead of flights/search.
• Use tool descriptions as hints that guide reasoning (“This tool returns top 5 cheapest flights for a given city and month”).
• Remove redundant or unused options.

By optimizing for flows, you eliminate wasted steps and reduce error rates.

Benefits of Agent-Optimized MCP Tools

1. Faster execution: Fewer calls mean lower latency and less token usage.
2. Reduced errors: Clear flows make it harder for agents to get stuck.
3. Better reliability: Predictable reasoning chains reduce unpredictable outputs.
4. Improved scalability: Complex tasks scale across more use cases.

For example, in testing, teams that consolidated APIs into higher-level flows reported:

• 50% fewer failed tasks.
• 30–40% lower query costs due to reduced token usage.
• Significantly improved task completion rates in complex domains like travel and e-commerce.

Building an Agent-First API Strategy

Step 1: Audit Your Current APIs

Identify areas where agents need multiple calls to achieve a simple goal.

Step 2: Rewrite Endpoints as Flows

Combine small actions into higher-level agent tools.

Step 3: Test with Agent Stories

Write scenarios of how an agent would use your tools. Validate whether they’re intuitive.

Step 4: Optimize Descriptions

Use plain, goal-driven language in tool descriptions.

Step 5: Monitor and Iterate

Track success rates, failures, and agent reasoning logs. Improve where agents struggle.

Conclusion: API Design for the Agent Era

Converting APIs for MCP isn’t about copy-pasting existing endpoints into a new format. It’s about rethinking design for a new user persona: AI agents.

By shifting from human-centric endpoints to agent-friendly flows, you unlock faster, cheaper, and more reliable automation.

The companies that adapt now will lead the next wave of intelligent, agent-driven applications. Those that don’t will watch their agents get stuck—while their competitors scale effortlessly.

• AI agent API design
• Model Context Protocol (MCP)
• agent workflows vs APIs
• MCP best practices
• agent experience (AX)
• BigQuery for AI agents (secondary context tie-in)
• agent-friendly tools design

‍

‍