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

Vinny Barreca — Tue, 15 Sep 2026 18:56:49 +0000

A $4 experiment rewrote three strings per MCP tool and moved SQLite success from 34% to 100%. The model never changed.

The failure was never the model.

SQLite strict success rate: 34%. That is a failing grade on a benchmark nobody was running.

Toolmetry, an open-source project that measures how well agents use MCP tools, took existing MCP server tool descriptions and had an LLM rewrite them. The strings that tell an agent what each tool does and how to call it. That was the entire change.

The model did not change. The harness did not change. Only the descriptions changed.

After the rewrite, SQLite hit 100%. Total API spend for the whole experiment was $4.

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

The three failure archetypes

Toolmetry found three patterns that were killing agent success rates before the rewrite.

Wrong tool confusion. Two tools in the same MCP server have overlapping descriptions, so the agent picks Tool A when it needs Tool. B. It looks like a bug. It is bad documentation.
Ritual extra calls. The agent makes a call it believes is a prerequisite, burning tokens and latency for nothing.
Deprecated parameter patterns. The description references parameters or usage patterns that no longer work. The agent follows the instructions faithfully and produces errors.

Each one is fixable with better words. Not better models. Better words.

Wrong tool confusion in practice

Before the rewrite, the SQLite server's read and write query tools were described almost identically. Most failures were the agent calling a read tool when it needed a write tool.

Two tools that sound similar to a human sound identical to an agent. After the rewrite, the query tool description stated explicitly what it could and could not do. Success jumped to 100%.

If two tools could be confused by a smart human, they will be confused by your agent.

Ritual extra calls and the implied prerequisite

Agents were calling a list_tables function before every query because the query tool's description said "first enumerate available tables." Implied, not required.

Before:

Tool: query

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

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

After:

Tool: query

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

The ritual calls stopped immediately. The table list was right there in the description. No extra round trips, no wasted tokens.

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

Deprecated parameters

The git server had deprecated parameter references baked into its descriptions. Agents were passing old parameter names and getting failures. The documentation was lying about how the API worked.

After the rewrite, all parameters matched 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. A stale description is worse than no description.

With no description, the agent guesses. With a stale description, the agent confidently does the wrong thing.

The before and after numbers

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

$4 of API spend for the entire run.

Now compare that against upgrading to a frontier model. 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.

Audit your MCP server in under an hour.

This costs less than $5 in API spend and takes about an hour.

List every tool in your MCP server and print each description.

Read pairs of descriptions side by side. If two could be confused by a smart human, they will be confused by the agent.

Check for implied prerequisites. Does any description say "first do X" when X is not actually required?

Check for deprecated parameters. Diff your current API against the description text.

Rewrite the descriptions with an LLM. Feed it the tool name, the current description, and the real API signature. Ask for a clear, non-overlapping description.

Re-run your agent test suite and compare success rates.

Toolmetry ships three commands to automate the loop: measure, optimize, and proxy. The proxy rewrites descriptions on the fly, so you can test improvements before committing anything.

Why this matters more than model selection

This is the fourth data point in a pattern that keeps repeating. Three separate papers already showed orchestration design beating model selection by 10x on token cost.

Structural scaffolding reduces failure rates under a fixed model. Graph-structured context beats flat text. And now tool descriptions alone move a server from 34% to 100%.

How you structure the agent's control flow, context, and tool interfaces matters more than which model you use. That is a direct challenge to the scaling; all you need is orthodoxy.

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.

The bottom line:

Your tool descriptions are three strings per tool. They cost nothing to write and everything to get wrong.

Wrong tool confusion, extra ritual calls, and deprecated parameter patterns exist in every MCP server that has never been audited. They exist in yours.

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

Originally published at articles.phantom-byte.com.

PhantomByte teaches you to build real AI infrastructure: local AI stacks, autonomous agents, multi-agent orchestration, and custom tools. Step-by-step tutorials you download, follow, and deploy.

The $750 Copilot: Why Your AI Dependency Just Got a Price Tag

Vinny Barreca — Mon, 01 Jun 2026 07:44:18 +0000

Your GitHub Copilot bill just went from $29 to $750/month.

Microsoft taught developers to "vibe code" (write less and let AI do the work).

Build entire workflows around that subsidy.

Then they installed a toll booth.

This is not a pricing change. It is a dependency trap snapping shut.

The $750 Copilot: the first honest price tag in a subsidized industry. Full breakdown and the local-first alternative

DEV Community: Vinny Barreca

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

The $750 Copilot: Why Your AI Dependency Just Got a Price Tag