AI agents need fewer tools, not more. But grouping endpoints together creates a hidden trap, and the fix is simpler than you'd think.
AI agents need fewer tools, not more. But grouping endpoints together creates a hidden trap, and the fix is simpler than you'd think.
If you've connected a real REST API to an AI agent, you've hit the tool-bloat problem. A typical SaaS API has 30-200 endpoints. Map them 1:1 to MCP tools and your agent is swimming in a flat list. Latency goes up, accuracy goes down, and half the tool calls are the agent picking the wrong one.
The obvious fix is grouping. Merge related endpoints into a single tool with an action field:
customers (tool)
├─ action: find
├─ action: search
├─ action: create
├─ action: update
└─ action: deleteClean. The agent sees 5 tools instead of 50. Everyone wins.
Until you hit the fan-out problem.
Take a real-world API — say a CRM or an e-commerce backend. The "customers" resource is massive. It touches everything. If you naively group every endpoint that relates to customers under one tool, you get:
customers (tool)
├─ action: find
├─ action: search
├─ action: create
├─ action: update
├─ action: delete
├─ action: list_orders
├─ action: list_invoices
├─ action: merge_duplicates
├─ action: archive
├─ action: export
├─ action: import
├─ action: add_note
├─ action: assign_agent
├─ action: update_subscription
├─ action: send_email
├─ action: get_activity_log
├─ action: ... (you get the point)Fan-out is the number of actions stuffed under one parent tool. And when that number gets high, you've recreated the original problem one level deeper. The agent is now scanning a giant action enum instead of a giant tool list. Same confusion, different shelf.
The grouping win disappears.
This isn't arbitrary. LLMs read tool schemas linearly. Name, description, parameter list, action enum. When the action list is short (3-5 items), the agent scans it in one glance and picks the right action. When it's long (15+ items), the agent does what it does with the flat tool list. It guesses, sometimes wrong.
We landed on a maximum of 8 actions per grouped tool. Here's the reasoning:
customers tool, you get:
customers (tool) — core CRUD + search
customer_billing (tool) — invoices, subscriptions, payment methods
customer_engagement (tool) — notes, emails, activity log
customer_admin (tool) — merge, archive, export, importEach tool is focused. Each action list is short. The agent knows exactly which tool to pick, then exactly which action. Two decisions, both easy.
customer_billing is a better tool name than customers with 8 unrelated billing actions buried inside it.The LLM that generates these optimized tools gets a constraint: MAX_ACTIONS_PER_GROUP = 8. If a resource has more than 8 operations, split it. Find meaningful boundaries.
In practice, this produces groupings that make intuitive sense to humans AND to agents. A Stripe API goes from 200 endpoints to ~25 focused tools, each with 2-7 actions. The agent never sees an action list longer than it can scan.
The constraint is the feature. Without it, the LLM defaults to dumping everything into the biggest bucket. With it, the LLM does the design work that a human would do. It asks "what actually belongs together?" rather than "which URL prefix do these share?"
Tool grouping is the design-time layer. We pair it with semantic naming (tools named for what they accomplish, not their REST path) and editorial filtering (not every endpoint deserves to be a tool). Together, they take an API that an agent would drown in and turn it into an MCP it can actually use.
But design-time optimization alone isn't enough. The fan-out cap reduces what the agent sees at tool definition time. There's also the runtime layer: lazy tool discovery. Keep all 200 tools defined, but surface only the ones relevant to the agent's current task. The agent calls list_tools(area=billing), gets back 3 billing tools, and that's what hits the context window.
The two layers are complementary. The fan-out cap makes each tool well-named and focused. Lazy loading makes sure the agent only sees the tools it needs per turn. Design time and runtime. Structure and context. Without both, you're solving half the problem.
If you're building MCP servers or exposing APIs to agents, check your tool schemas. Count the actions under your biggest tool. If it's above 10, you've got a fan-out problem, and the fix is a one-line constant.