A pattern that keeps showing up in agent threads and harness writeups: the model picks the wrong tool, or says "I don't have access to X" while X is sitting in the catalog, and the model gets blamed. More often it's the harness: every turn stuffed with every schema from every server. That's thousands of tokens before the user types a word, similar tools colliding (book vs reschedule), and if you just hide tools to save context, the agent finds step 1 and dead-ends because it never learned step 2 existed. The fix that's converging is progressive discovery: give the model a small search tool plus a list of deferred tool names, then load full schemas only when the conversation needs them. Append what gets discovered rather than reordering the tool list, otherwise you bust provider prompt caches. Claude Code's MCP Tool Search ships this in-product (on by default, loads up to five tools per search), and OpenAI's tool search with deferred loading is the same idea. Anthropic's docs put the saving at over 85% of tool-definition overhead, and their engineering post gives an example of roughly 77K tokens dropping to about 8.7K before any work starts. Selection accuracy also drops once you push past roughly 30–50 available tools. Measuring it is cheap: count tokens once with your tool definitions and once without. The difference is the per-session tax, and it's usually concentrated in one or two tools with big nested schemas. Fix those descriptions before adding more infrastructure. Two gotchas worth knowing in Claude Code specifically. Tool search turns itself off when ANTHROPIC_BASE_URL points at a non-first-party proxy (most don't forward the tool_reference blocks), so people behind a gateway quietly get everything upfront. And in sessions with the HIPAA configuration it's hard-off, and ENABLE_TOOL_SEARCH won't turn it back on, so plan allowlists there, not search. Open question: how are you keeping MCP tool surface small without the agent inventing "I don't have that tool"? Tool search, skills-as-gates, per-subagent allowlists, something else?
TDQS scores MCP tool descriptions across six dimensions to help agents pick tools more reliably. It provides a CLI, API, and playground to lint definitions, with 97% of scored registry tools found to carry at least one defect.