Your Agent's Tool Descriptions Are Costing You 66% Accuracy

Toolmetry ran a systematic experiment. They rewrote MCP server tool descriptions with an LLM, and agent success rates jumped from 34% to 100% on the SQLite server, from 61.8% to 96.4% on the memory server, and from 75% to 96.7% on the git server. Total API spend for the entire experiment: $4. Your agent's interface to the world is three strings, and you have been writing them wrong.

In this article:

• The Toolmetry Experiment: What Happened When They Rewrote Three Strings
• The Three Failure Archetypes Killing Your Agent's Success Rate
• Wrong-Tool Confusion: When Your Agent Picks the Wrong Hammer
• Ritual Extra Calls: Your Agent Is Doing Unnecessary Work Every Time
• Deprecated Parameter Patterns: Your Tool Docs Are Lying About How Things Work
• The Before/After Numbers: SQLite, Memory, and Git Server Results
• How to Audit Your Own MCP Server Descriptions in Under an Hour
• Why This Matters More Than Model Selection
• The Bottom Line: Small Levers, Massive Impact

The Toolmetry Experiment: What Happened

Toolmetry is an open-source project that measures how well agents use MCP tools, then rewrites the descriptions to fix what breaks. They took existing MCP server tool descriptions, the strings that tell an agent what each tool does and how to call it, and had an LLM rewrite them. The model did not change. The harness did not change. Only the descriptions changed. The results were dramatic.

This is not a model problem. This is an interface problem. Tool descriptions are the contract between your agent and the outside world. When the contract is ambiguous, the agent breaks the terms. Every time.

The Three Failure Archetypes

Toolmetry identified three specific failure patterns that caused agents to fail before the description rewrite.

1. Wrong-tool confusion. Two tools in the same MCP server have overlapping descriptions. The agent picks Tool A when it needed Tool B. It looks like a bug. It is actually bad documentation.

2. Ritual extra calls. The agent makes a call it thinks is a prerequisite, wasting tokens and time, and sometimes introducing errors. Your agent is doing busywork because you told it to.

3. Deprecated parameter patterns. The description references old parameters or usage patterns that no longer work. The agent faithfully follows instructions that produce errors. Your docs are lying to your agent.

Each of these is fixable with better words. Not better models. Better words.

This connects directly to what we covered in Your Agent Needs a Preflight Check — preflight checks prevent the exact failure patterns described here.

Wrong-Tool Confusion

Before the rewrite, the SQLite server had 34% strict success. That is a failing grade. Most of those failures were the agent calling a read-only query tool when it needed a write tool, because the descriptions were nearly identical. Two tools that sounded similar to a human sounded identical to the agent.

The fix was differentiation. After the rewrite, the query tool description explicitly stated what it could and could not do. The agent stopped confusing read with write. Success jumped to 100%.

If two tools could be confused by a smart human, they will be confused by the agent. Audit your descriptions for overlap.

The Shepherd pattern shows how structured orchestration prevents tool confusion by giving each sub-agent clear boundaries.

Ritual Extra Calls

Agents were calling a "list tables" function before every query because the description of the query tool said "first enumerate available tables." This was implied. It was not required. After rewrite, the query tool description included the table list inline. No more ritual calls.

Here is exactly what that looked like:

Before (broken description):

Tool: query
Description: Execute a SQL query against the database. First enumerate available tables using list_tables, then construct your query against those tables.

The agent dutifully called list_tables before every single query — even when it already knew the schema from the previous call. Two extra API calls per interaction, doubled latency, and zero benefit.

After (fixed description):

Tool: query
Description: Execute a SQL query against the database. Available tables: users, orders, products, invoices, audit_log. Use standard SQL syntax. This tool handles both reads and writes — no need to call list_tables first.

The agent stopped making the ritual call immediately. The table list was right there in the description. No extra round trips. No wasted tokens.

This pattern is everywhere. Your agent is doing unnecessary work every time because your description implies a step that does not exist. It costs tokens. It costs latency. It costs accuracy. And it is entirely your fault.

Remove implied prerequisites from your tool descriptions. If a step is not required, do not imply it is.

Memory latency is a parallel problem — as we covered in Your Agent's Memory Is Too Slow to Think, unnecessary calls waste both tokens and time.

Deprecated Parameter Patterns

The git server had deprecated parameter references in its descriptions.

Agents were passing old parameter names and getting failures. The descriptions were lying about how things worked.

After rewrite, all parameters were updated to current names. Success went from 75% to 96.7%.

Version your tool descriptions. When you change an API, update the description in the same commit. Stale descriptions are worse than no description. At least with no description, the agent guesses. With a stale description, the agent confidently does the wrong thing.

The Before/After Numbers

Here is the full picture from the Toolmetry experiment:

Server	Before	After	Improvement
SQLite	34.0%	100%	+66.0 points
Memory	61.8%	96.4%	+34.5 points
Git	75.0%	96.7%	+21.7 points
Filesystem	74.4%	84.4%	+10.0 points

Total API spend for the entire experiment: $4.

Compare that to the cost of upgrading to a frontier model. Even hypothetical future models like a "GPT-5.6 Sol" or "Claude Fable 5" at scale would cost orders of magnitude more, and would not fix the interface problem. A cheaper model with broken descriptions still fails. An expensive model with broken descriptions still fails. The model is not the bottleneck. The interface is.

You are paying thousands for a model that cannot work because you gave it bad instructions. That is not a model problem. That is a you problem.

How to Audit Your Own MCP Server Descriptions

This takes under an hour. It costs under $5 in API spend. If you cannot find an hour to fix something that could double your agent's success rate, you are in the wrong business.

1. List every tool in your MCP server. Print the description for each one.
2. Read pairs of descriptions side by side. If two tools could be confused by a smart human, they will be confused by the agent.
3. Check for implied prerequisites. Does any description say "first do X" when X is not actually required?
4. Check for deprecated parameters. Diff your current API against the description text.
5. Rewrite the descriptions using an LLM. Feed it the tool name, current description, and actual API signature. Ask it to produce a clear, non-overlapping description.
6. Re-run your agent test suite. Compare success rates.

Toolmetry provides three commands to automate this: measure, optimize, and proxy. You can run the full loop without forking your server. The proxy rewrites descriptions on the fly, so you can test improvements before committing them.

This audit workflow extends the MCP sessions and tool operation concepts from Your Agent Is the Tool Operator Now.

Why This Matters More Than Model Selection

This connects directly to a thesis PhantomByte has been building for months. In Note 124, "Your Agent's Harness Is Your Real Model," I showed that three papers proved orchestration design beats model selection by 10x in token cost.

Toolmetry is the fourth data point. The TensorFeed report identifies this as Theme 1: "Agent Reliability Through Architecture, Not Scale." CogniConsole proves that structural scaffolding reduces failure rates under fixed models. GATS achieves 100% planning success with zero LLM calls. GRACE shows graph-structured context beats flat text by 3.5x. And now Toolmetry shows that tool descriptions alone can boost success from 34% to 100%.

The common thread is clear. How you structure the agent's control flow, context, and tool interfaces matters more than which model you use. This is a direct challenge to the scaling-is-all-you-need orthodoxy that has dominated AI discourse for years.

The competitive advantage is shifting from model ownership to orchestration design. The people who understand that will win. The people who keep throwing bigger models at broken interfaces will keep getting 34% success rates and wondering why.

This connects to the sovereign AI context from The Pipeline That Trained the Machines Is Closing — local models need good tool descriptions even more. And as Seven Weeks at the Top, Then Irrelevant showed, model churn reinforces why the interface (tool descriptions) is more durable than the model.

The Bottom Line

Your agent's tool descriptions are three strings per tool. They cost nothing to write and everything to get wrong. A $4 experiment produced bigger reliability gains than a model upgrade that would cost thousands.

The three failure archetypes — wrong-tool confusion, ritual extra calls, and deprecated parameter patterns — are universal. They exist in every MCP server that has not been audited. They exist in yours.

Audit your descriptions today. It takes an hour. It costs $4. It might double your agent's success rate.

Because in AI, tool descriptions are engineering. And engineering is the only thing that actually works.