Tool Contracts, Errors, and Progressive Discovery
The model chooses from the interface you describe. Ambiguous tools create ambiguous behavior. Write tool names, descriptions, and schemas with non-overlapping boundaries. Design structured tool and MCP errors that guide safe recovery. Use tool choice and narrow tool distribution deliberately. Scope MCP configuration and secrets for user and project use. Apply progressive discovery to large tool catalogs without losing authorization. An agent sees three tools: search. find. lookup. Their descriptions all say "find information." One searches public web pages, one queries internal customer records, and one retrieves approved policy. The schemas accept a single string. Errors return arbitrary text. The model chooses inconsistently. A public research task queries private data. A policy question searches the web. When a tool returns "failed," the agent retries until its budget expires. The model is not confused by tool use. The interface erased the distinctions it needed to choose safely. A strong tool contract states: one action and object. when to use it. when not to use it. authoritative data boundary. required identity or approval. argument meaning and constraints. result and error shape. side effects and reversibility. Compare: with: The second interface supplies the selection boundary and a result promise. The service must still validate identity and region at execution. Two tools overlap when the model cannot infer which one owns a request. Repair…
Tool Contracts, Errors, and Progressive Discovery: The model chooses from the interface you describe. Ambiguous tools create ambiguous behavior.
This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.
Browse the complete course catalog or open this lesson on GitHub.