Your agents aren't broken. Your tools are.

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.