The model was fine. The tool spec was the bug.

An eval on a production-shaped agent showed a tool-skip rate north of 20 percent. The agent had the right tool available, needed it, and silently did not call it. The instinct in the room was to upgrade the model.

We rewrote the tool descriptions instead. Skip rate collapsed.

That finding turned into a habit and then into tooling. A tool spec is a contract between a deterministic system and a probabilistic caller, and most specs are written for the wrong reader: they describe the implementation for a developer instead of the decision for a model. “Queries the internal pricing service v2” tells an agent nothing. “Use this when the user asks what something costs; do not use it for historical prices” changes behavior you can measure.

Because the failure is textual, it is lintable. That became Tool Credit Score, a deterministic linter that grades MCP tool specs 0 to 100 for agent-readiness and auto-fixes the common failures. Deterministic on purpose: spec review belongs in CI, and CI should not need an LLM to tell you a description is three words long.

The full method, including the failure taxonomy (skip, wrong tool, malformed arguments, hallucinated arguments, premature answer) and the before/after examples, is in the tool contracts field guide.