Your agents aren't broken. Your tools are.
An AI tool is not a function. It is a strict contract.
Most teams debug the agent when the real fault is the tool. An AI tool is a contract the model has to trust: atomic (one verb), honest on failure (semantic errors, never null), and typed and token-efficient (a schema, never raw DB rows). Three questions to ask before you build one. A one-glance visual companion to the long-form post on the tool contract.
Tags#ToolDesign#AITools#AgenticAI#Pydantic#JSONSchema#ToolContracts#AIAgents
Key takeaways
- 1When an agent misbehaves, the instinct is to fix the prompt or the model. More often the fault is the tool. An AI tool is not a function, it is a contract the model has to trust.
- 2Question one: is it atomic? One tool equals one verb. If a tool does two things, the model has to reason about which half it wants and it gets that reasoning wrong. Split it immediately.
- 3Question two: what happens on failure? Return a semantic error the model can read and recover from, like order_id_not_found. Never return null. Null tells the model nothing and it will hallucinate a reason.
- 4Question three: is it typed and token-efficient? Define the input and output with Pydantic or JSON Schema. Never dump raw database rows into the context. Half the columns are noise and every one of them costs tokens.
- 5A good tool is atomic, honest on failure, and typed. Get those three right and the agent that was failing yesterday starts working without touching the model at all.
- 6The golden rule: build tools your agent can actually trust. Stop debugging agents and start building better tools. Fix the tool, fix the agent.
