The Endpoint-to-Tool Mapping Trap
TRIGGER
When exposing existing APIs to AI agents, teams default to 1:1 mappings—each API endpoint becomes one tool. But agents work through multi-turn conversations, not single HTTP calls, leading to high token consumption and awkward interaction patterns when working with hierarchical data structures like nested JSON blocks.
APPROACH
Notion's team built their hosted MCP server with two categories of tools: (1) AI-first rewrites like `create-pages` and `update-page` designed ground-up for agent conversation flow rather than traditional API patterns, and (2) wrapped existing v1 APIs with AI-friendly descriptions for functionality coverage. Input: natural language requests through MCP client. Output: Notion workspace changes via optimized tool calls. They replaced hierarchical JSON block representation with 'Notion-flavored Markdown' that provides higher content density per token, requiring fewer tool interactions. The hosted OAuth approach replaced the previous downloadable package that required manual API key configuration.
PATTERN
“Five tool calls where one should do, token costs ballooning, awkward interaction patterns—the 1:1 endpoint-to-tool trap. Agents work in dialogue turns where each call costs context tokens and disrupts flow. Design tools around common workflows, not API structure.”
✓ WORKS WHEN
- Your existing API uses deeply nested or hierarchical data structures (JSON trees, block children)
- Typical agent workflows require 3+ sequential API calls that could be collapsed into one purpose-built tool
- Token cost matters—your data representation is verbose in structured formats but compressible to text/markdown
- You control both the API and the agent-facing layer, allowing you to ship 'private' functionality slices
- Users interact through general-purpose MCP clients (Cursor, Claude Desktop) rather than custom agent implementations
✗ FAILS WHEN
- Your API already returns flat, self-contained responses that don't benefit from restructuring
- Agent use cases mirror programmatic use cases—deterministic backend integrations needing structured JSON
- You lack resources to maintain two interface layers (traditional API + agent-optimized tools)
- Your data has no natural text representation—binary data, complex relational structures requiring joins
- Precision matters more than conversational flow—financial transactions, audit-logged operations