Agent tool catalogues: keeping an MCP tool catalog small.

Tools arrive one at a time. A team ships create_ticket, then create_ticket_v2 for a new field, then create_internal_ticket because support needed a variant, then open_case because another team used a different word. Each step was reasonable, and yet the MCP tool catalogue now offers an agent four ways to do roughly one thing, separated by details that live in somebody’s head.

Why does a larger catalogue get harder to choose from?

The clearest evidence is indirect: it comes from what researchers had to build once tool inventories got big. ToolLLM (Qin et al., ICLR 2024) assembled 16,464 real APIs and did not hand them to a model directly: it trained a neural API retriever to narrow the field first. Gorilla (Patil et al., NeurIPS 2024) pairs a document retriever with fine-tuning for the same structural reason. ToolkenGPT (Hao et al., NeurIPS 2023) represents each tool as a learned token specifically because injecting every tool into context stops scaling. Nobody in that literature assumes a model can read a thousand descriptions and pick well.

Recent work keeps treating selection as the hard part. Fang and Glass (2026) reframe tool retrieval as iterative query planning rather than one-shot matching, because underspecified requests do not resolve in a single lookup. Guo et al. (2026) study rewriting descriptions to improve selection in large candidate sets. And Healy et al. (2026), on detecting tool-calling errors, names the recurring failure classes plainly: wrong-tool choice, malformed arguments, and tool bypass.

Together they support a design conclusion, though not a measurement. Retrieval exists because a catalogue is too large to present whole, and the failure modes it guards against are the ones ambiguity produces. Making the catalogue smaller and its seams sharper removes that component instead of tuning it.

Three moves that shrink a catalogue

Pruning moves a distinction somewhere else without deleting capability.

Retire what nothing calls. A tool kept in case someone needs it taxes every decision anyone else makes. Record which tools real workflows invoke, and treat a long silence as evidence. Removing an unused tool costs a deprecation note. Keeping it costs a wrong choice somewhere you will not notice.

Merge near-duplicates behind a closed set. When two tools differ only by a value, the value belongs in the schema. Five tools called export_csv, export_json, export_xlsx and so on become one export_report with a format enum, and the agent can no longer invent a sixth. Here JSON Schema does real work: enum plus additionalProperties: false can be checked by a machine, and a paragraph cannot.

Defer the long tail. Not everything has to be visible at step one. The MCP specification defines a paginated tools listing and a list-changed notification, so a server can legitimately present a working set and expand it. Agent Skills take the same approach from a different direction, loading a name and description first and the full instructions only when the skill is activated, a pattern OpenAI’s skills documentation describes as progressive disclosure.

A fourth move runs the other way, so do not mistake it for pruning: splitting a broad tool into narrower ones. A single manage_account that branches internally on a mode parameter hides exactly the choices a person reviewing an approval would want to see. Split when the branches differ in consequence, authority or failure mode; merge when they differ only in a value.

Naming so that neighbours separate

Most catalogue confusion that looks like a counting problem is really a naming problem.

Four rules do most of the work. Name the job rather than the endpoint: find_customer instead of get_v2_cust. Keep one verb per concept across the whole catalogue, so get, fetch, read and load do not all appear meaning the same thing. Put the object second and keep it consistent, so a reader can scan the list by noun. And write each description against its nearest neighbour by name. That sentence is the most valuable one in most tool definitions.

That last rule has a test attached. If it takes a paragraph to tell two tools apart, the boundary is in your head and not in the product, and the fix is a rename or a merge. The MCP tool-description test-case fixture is a public worked example of the shape: a target intent, its nearest competing tool, valid and schema-invalid inputs, the result shape, and a recovery path. It tests a documented distinction. It does not certify a catalogue.

A worked example: the five tools this site publishes

This site runs a public, read-only MCP server at https://agentexperience.tech/api/mcp, and its catalogue is deliberately small. Four reference tools are defined in api/_lib/tools.ts, alongside one bounded diagnostic:

Four properties of that catalogue are worth copying into your own. Every description names the tool it is most likely to be confused with, and says what it is not for. The slug parameter of get_guide is an enum generated from the published guide list, so an invalid slug is a schema error rather than an empty result. Every schema sets additionalProperties: false. And the file carries a dated line recording when the descriptions were last reviewed against the content, because nobody can verify an undated description.

One consistency rule sits behind that: the tool names are also published in the capabilities array of /.well-known/ard.json, and a unit test fails if the two drift. A catalogue that describes itself differently in two places will mislead somebody sooner or later, which is why agent instructions need a check against production too.

What the MCP specification gives you, and what it does not

The MCP tools specification defines the parts of a tool definition that a client can rely on: a name, a description, an input schema, and optional annotations including read-only, destructive, idempotent and open-world hints. Those annotations are useful to a client deciding how to present a tool or whether to prompt before calling it.

They do not enforce anything. The specification says plainly that annotations are untrusted unless they come from a trusted server, and that the client and server must still validate and authorise. In practice the model reasons over metadata and the harness enforces execution. In our own case the point is slightly academic, because every one of those four functions is a pure read over a build-time constant and there is no write path to guard, but the rule holds wherever there is one.

When a bigger catalogue is the right answer

Small is a default, and there are cases where it does not fit. A general assistant over a thousand internal services cannot pretend to be small, and there the design problem changes shape without going away: you need a retrieval layer, a way to check that it returns the right candidates, and a way to keep descriptions current as services come and go. That is the world StableToolBench (ACL 2024 Findings) was built for, with simulated APIs and caching because real ones drift, and the one Wu et al. (ACL 2026 Findings) address by adapting documentation continually. Budget for that machinery deliberately, and do not arrive there by accident, one reasonable addition at a time. If your product really does have thousands of operations, seven patterns for exposing a large API to agents show how to keep them out of the context until one is needed.

A catalogue checklist

Before shipping a catalogue change, go through this working list.

1. Can you state, in one sentence each, what every tool is for and which tool it is not?
2. Does each description name its nearest neighbour explicitly?
3. Is every closed set of values an enum in the schema rather than a sentence in the prose?
4. Does every schema set additionalProperties: false, so a hallucinated field fails loudly?
5. Has anything been added in the last quarter that no workflow has called?
6. Do two tools produce the same outcome by different routes? If so, one of them is a trap.
7. Is the date of the last description review recorded somewhere a reviewer will see it?
8. Would someone outside your team choose correctly from the catalogue alone?

The last question matters most, and Run an Agent Experience review puts it in a wider frame. If the answer is no, the fix is almost never another tool.

Frequently asked questions

What is an agent tool catalogue? It is the set of callable actions an agent can see at the moment it decides what to do, along with each one’s name, description and input schema. In an MCP deployment it is what a server returns from a tools listing. The catalogue is a product decision rather than an inventory, because every entry in it competes for context and for the agent’s attention.

How many tools should an MCP server expose? There is no correct number, and the useful question is how many plausible-looking neighbours any single request has. Ten tools that each answer a different question are easier to choose between than five that overlap. If you cannot state the boundary between two tools in one sentence, the count is not your problem.

Is it better to have one flexible tool or several specific ones? Prefer one tool with a closed enum when the variants differ only by a parameter, and separate tools when the variants differ in consequence, authority or failure mode. A single tool that silently does five different things hides the choices a person would want to review. JSON Schema can carry a distinction more reliably than five prose descriptions can.

Do MCP tool annotations reduce the need to prune? No. Annotations such as read-only, destructive and open-world hints help a client sort and present tools, but the MCP specification (2026-07-28) treats them as untrusted unless the server itself is trusted, and enforcement stays with the server. They make a large catalogue easier to display; they do not make it easier to choose from.

A catalogue is done when a reader who has never seen your product can say what each tool is for and why it is not one of the others.