Why Human APIs fail as MCP tools (and how to fix them)

The Model Context Protocol (MCP) is a powerful way to expose your systems to AI agents. But a common mistake teams make is to take an API built for humans, auto-convert it to MCP tools, and expect agents to use it effectively.

APIs designed for human developers follow a very different set of rules than APIs/Tools that serve AI agents in agentic workflows. What’s intuitive for a person is often overwhelming, inefficient, and error-prone for an LLM. If we want our agents to succeed, we need to design for them from the ground up—not just repurpose what we already have.

Setting the stage:

Imagine you want to enable agents to use your flight booking system by converting the current APIs you have, and you ask your agent to find the cheapest direct flight to Paris in June, This is roughly the api calls your agent should make:

jsx GET /airports/search?query=paris - Find Paris airport codes 

GET /airlines/list - Get all available airlines 

GET /flights/search?origin=JFK&destination=CDG&departure_date=2024-06-01 - Search flights for June 1st

GET /flights/search?origin=JFK&destination=CDG&departure_date=2024-06-02 - Search flights for June 2nd GET /flights/search?origin=JFK&destination=CDG&departure_date=2024-06-03 - Search flights for June 3rd

(Continue for each day in June...) 

GET /flights/123/details - Get detailed info for each flight

GET /flights/456/details - Get detailed info for another flight

GET /flights/789/details - Get detailed info for another flight

GET /flights/filter?direct_only=true - Filter for direct flights only

GET /flights/sort?by=price&order=asc - Sort by price ascending 

GET /pricing/calculate?flight_id=123&passengers=1 - Calculate total price with fees 

GET /pricing/calculate?flight_id=456&passengers=1 - Calculate total price with fees

The Problem: Human APIs Don’t Fit Well with Agent Workflows

Developers want lots of small, composable endpoints they can stitch together in whatever way makes sense for their application. They often have many endpoints, parameters, and options so a developer can decide what to use and how to combine calls.

Converting each of these APIs 1:1 to an MCP tool will create friction:

• Too many options → harder for the agent to decide which call is correct.
• Unclear purposes → descriptions meant for humans don’t map cleanly to the agent’s decision process.
• Extra steps → an agent may need multiple calls to complete something a human would do in one mental step.

The result is an MCP tool that works in theory, but slows down or confuses the agent in practice.

The Solution: Think Like an Agent

Agents don’t explore the way humans do. They work toward goals by following reasoning chains. When deciding how to turn an API into MCP tools, imagine you’re telling the agent a story about what it can do and how it can act.

Instead of exposing every possible endpoint, focus on clear, goal-oriented actions. Each tool should represent something the agent can immediately understand and execute — like “find a product by name” or “book a meeting” — not just a low-level function.

Using Agent Stories

Netlify’s CEO, Mathias Biilmann, recently highlighted in his talk and article “Introducing AX: Why Agent Experience Matters” that agents are becoming one of the core “personas” they design for. Just as we think about user experience (UX) for humans, we should think about agent experience (AX) when building MCP tools.

One way to guide design is to write agent stories: short scenarios showing how the agent might solve a problem using your MCP tools.

Example:

“A user asks the agent to find the cheapest direct flight to Paris in June. The agent uses the searchFlights tool with the destination and month, then picks the best flight with selectBestFlight tool based on the criteria it has (in this case lowest price).”

By imagining these flows, you’ll see where you can simplify steps, combine related actions, or rename tools so their purpose is obvious. Now the new flow our agent will follow immediately is:

jsx searchFlights(destination="Paris", month="June", departure_city="New York") - Returns top 5-10 cheapest direct flight options with key details 

selectBestFlight(criteria="cheapest") - Picks the lowest priced option from the previous search results

# Or even all in one tool call

findCheapestDirectFlights(destination="Paris", month="June", departure_city="New York", limit=3) 

Designing Flows for Agents

When building MCP tools, think in terms of flows rather than just endpoints. A flow represents the sequence of actions an agent will take from start to finish for a given task.

You can help the agent succeed by:

• Grouping actions that naturally belong together.
• Removing unnecessary branching that would force the agent to guess.
• Providing hints in tool descriptions about what comes next or what other options are possible.

This doesn’t just make the agent faster — it makes it more reliable and less likely to get stuck.

Conclusion

Converting a human API into MCP tools is more than just an automated format change. By designing with agents in mind, using stories, flows, and goal-oriented thinking, you can create tools that work seamlessly in an agent’s reasoning process.