MCP for agents

Developer-oriented MCP servers often fail agents: 1:1 REST-to-tool mappings that force multi-step orchestration, vague descriptions that cause wrong tool selection, nested parameter objects that invite hallucination, and raw API passthrough that exhausts the context window. Design for the agent's constraints, not the developer's convenience.

Outcomes over operations

The agent decides when to call; the server decides how. Combine backend operations server-side so the agent makes one call, not three.

Bad: Expose get_user_by_email, list_orders, get_order_status separately -- agent chains three calls. Good: Expose track_latest_order(email) -- server handles the lookup internally, returns what the agent needs.

A tool that maps 1:1 to a REST endpoint is almost always wrong. Ask: "What outcome does the agent want?" and build the tool around that.

Flat, constrained parameters

Agents hallucinate missing keys in nested objects. Flatten parameters to top-level primitives, constrain with enums, and add sensible defaults so the agent makes fewer decisions.

Bad: