Diagnose the failure

Lesson 5 of 5 in Tools and Tool Use: The Contract Between Model and World.

Tool-design failures never announce themselves as tool-design failures. They surface as model behaviour — wrong choices, invented arguments, premature apologies — and the untrained response is to blame the model, swap it for a bigger one, or pile instructions into the system prompt. The trained response runs the diagnosis backwards: from the symptom in the trace, to the contract that caused it.

Four causes cover most of what you will ever see: a name or description that fails to route, parameters loose enough to invite guessing, results the model cannot act on, and a toolbox whose contracts overlap. Sort the symptoms below into those four bins — this mapping is the skill you will use weekly as an agent builder.

Interactive sorting exercise: Match each failure symptom to the tool-design cause behind it.

Interactive flashcard deck.

Tool: Agent Loop Lab — Watch contracts do their work live: run the loop, inspect each tool call’s name and arguments, and see how a result steers — or strands — the next step.