Designing MCP Tools an AI Agent Can Actually Use

Your AI agent isn't failing because the model is weak. It's failing because your tool descriptions are ambiguous, your schemas are sloppy, and your error messages tell it nothing useful. In 2026, Model Context Protocol (MCP) tool design has quietly become the hidden discipline separating reliable agents from expensive disappointments. The model can only see what you show it — and if what you show it is vague, bloated, or contradictory, no amount of parameter tuning will save you.

The Hidden UI: Why Tool Metadata Is Everything

When an agent decides which tool to call, it isn't consulting your internal documentation, your API reference, or the Slack thread where you debated naming conventions. It sees three things: a name, a description, and a schema. That's it. As Ginger Labs puts it, these fields are the only information an AI agent has when deciding which tool to call and how to construct its input. Treat them as a user interface for LLMs, because that is precisely what they are. Every ambiguous phrase, every loosely typed parameter, every silent failure is a UX bug — one that compounds across every call your agent makes.

The Anatomy of an MCP Tool Definition

The MCP spec, explained by apxml and Merge, requires three things for every tool: a unique name (like `get_user`), a plain-text description of what it does, and an input schema — a JSON object listing the required and optional parameters. That's all the model gets. There's no hidden context and no secret behavior it can guess from your code. If you don't spell out a capability in one of those three fields, the agent won't know it exists.

The Token Cost Nobody Talks About

Here's the number that should worry you: a single tool definition consumes between 100 and 500 tokens. According to the MCP Tool Schema Design Guide, a 58-tool, five-server setup can burn around 55,000 tokens before the agent does a single useful thing. Jira's MCP integration alone accounts for roughly 17,000 tokens. That's context budget you're paying for on every turn, whether the agent uses those tools or not. Bloated inventories don't just cost money — they degrade selection accuracy by drowning the relevant tool in noise. Aggressive tool count management isn't optimisation; it's hygiene.

Descriptions: Your Agent's Primary Decision Signal

Multiple sources converge on the same point: descriptions are the primary mechanism LLMs use to select tools. Merge recommends keeping them to one or two sentences that clearly state what the tool does and when to call it. That second half — when to call it — is where most teams fail. A description that says "Fetches user data" tells the model nothing about how it differs from the three other tools that also touch user data. A description that says "Fetches a single user's profile by ID; use when you have a specific user ID and need account details" gives the model a decision boundary. Operational details like authentication, pagination, and filtering belong in the schema, not the description. Keep the description focused on selection, not implementation.

Naming Conventions and Affordances

Names hint at what you can do with something. Alive MCP says to stay consistent across your server. If half your tools start with `get_` and the rest use `fetch_`, the model has to guess which one fits where.

The Prompt Bench points out an important difference: tools are actions the model runs, while resources are data the model reads. Mix them up and your agent will try to "call" plain data or "read" something that actually changes stuff.

So pick one verb style, stick with it, and name things by what they do — not by how they work under the hood.

Schema Design That Prevents Hallucinated Inputs

Loose schemas invite hallucinated inputs. A parameter typed as a bare `string` with no description is an open invitation for the model to invent something plausible-looking and wrong. Best practice, drawn from QubitTool and others, includes: mark required versus optional parameters explicitly, use tight types (enums, formatted strings, constrained numbers), include examples in parameter descriptions, and add schema annotations that guide construction. If a parameter accepts an ISO 8601 date, say so and show one. If it accepts one of five status values, use an enum. Every constraint you encode is a hallucination you prevent.

Error Messages Belong Inside Tool Results

This is the rule that most teams get wrong. The Prompt Bench is emphatic: errors should be returned inside tool results, not raised as protocol-level exceptions. Why? Because an exception is opaque — the agent sees a crash and has no context to reason about. An error returned as a tool result is an affordance: the agent can read it, understand what went wrong, and either retry with different inputs or select a different tool. "User not found: no account exists with ID 12345. Try searching by email using find_user_by_email" is infinitely more useful than a 404. Treat errors as teaching moments for the agent, not failure signals for your logs.

Common Anti-Patterns to Avoid

Production deployments keep hitting the same problems, as AWS and others have shown. Watch out for vague or overlapping descriptions that make it hard to pick the right tool, huge tool lists that clog the context window, missing hints about when to use each tool, badly typed parameters that lead to broken calls, and error messages that don't help you recover.

Another common trap is the mega-tool — one giant function with fifteen optional parameters that tries to do everything. Small, focused tools almost always beat these sprawling ones. If you need the word "and" to describe your tool, it should probably be two tools.

Practical Takeaways for Reliable Tool Design

Here's how to check and clean up your tool inventory:

• Keep each description to one or two sentences, and clearly say when the tool should be called.

• Use the same naming style across the whole server.

• Make parameter types as strict as possible, and add examples.

• Return errors as structured results so the agent can actually understand them.

• Delete or combine tools you don't need, since every extra tool wastes tokens and adds confusion.

• Most importantly, test it for real.

Schema validation only proves your JSON is formatted correctly. It does not prove the agent will pick the right tool. So run real agents against real prompts, measure how often they choose correctly, and keep tweaking the metadata until the behaviour is reliable.

Conclusion

Designing MCP tools is basically UI design for LLMs. Every name works like a label, every description like a tooltip, every schema like a form, and every error message like user feedback. Teams building reliable agents in 2026 get this. The ones still dealing with misrouted requests and hallucinated calls usually don't.

So here's a question worth thinking about: if you gave your current set of tools to a brand new agent tomorrow, with no context or coaching, would it pick the right tool for the job — or would it fail in the same predictable ways your users are already complaining about?