🔧 Tools and the Tool Contract
Listing the tools isn’t enough. Your AI will call the wrong tool, ignore dependencies, or make ten calls in a row when one batched call would do. The solution is the Tool Contract: for each tool, specify when call, what comes first, what never to use, and how to group. You leave here with six clauses ready to paste.
Detailed content
Usage trigger: when to call
In the library module, you saw the block tools to say what exists. That's only half. The other half — the part that makes the AI stop groping around — is the usage trigger: the clear condition that says when that tool comes in. "You have a web search" is a capability. "Use web search when you need a fact that came after your knowledge cutoff" is a contract. The difference is night and day.
🎯 The idea in one sentence
The Tool Contract says when and in what order call each tool — not just what exists. Listing is the Capabilities Declaration; contracting is the next step, and it’s what separates an agent that executes with discipline from one that calls the wrong thing at the wrong time.
The heart of each clause is the trigger: "use when {condition}". Without it, the model guesses — and guesses badly: it calls search for things it already knows, or fails to call it when it really needed to.
What the trigger is
A sentence that ties the tool to a observable situation: "use the calculator when a calculation takes more than one step", "use search when the user asks for something current", "use the file reader when you need the contents, not the name". The trigger answers the only question that matters when taking action: does this apply now?
Why the trigger changes everything
Because without a trigger condition, the tool becomes a temptation. The model either overuses it (calls it for everything, wasting time and tokens) or ignores it (answers from memory when it should have searched). The trigger turns "you can" into "you must, right here"—and it’s the part of the contract that most reduces incorrect calls.
Prerequisite: the required step beforehand
Some tools have a sacred order: before doing X, do Y. The classic example, which appears literally in the rules for real tools, is read before editing: you can't edit a file you haven't read — because if you haven't seen its current contents, the edit is a guess. The prerequisite is the clause that makes this dependency explicit.
You MUST use the Read tool at least once before editing.
One sentence. Capitalization in MUST, the explicit order ("at least once before editing"). It's not a suggestion — it's the door that needs to be opened before the next step.
🔗 Why declaring the order matters
- ① AI doesn't infer the dependency on its own. For it, editing and reading are two separate tools. You need to tie them together.
- ② Skipping the step causes silent damage. Editing without reading overwrites what you haven't seen—and the error only shows up later, when it's too late.
- ③ The rule is short and costs little. One line in the contract prevents an entire class of failures. Extremely high ROI.
The prerequisite template
Prerequisite: before {action}, {required step}. Examples: "before editing, read the file"; "before sending the email, show the draft"; "before running the deploy, run the tests." Always before + the door that needs to be open.
Exclusion: use X, never Y
When two tools seem serve the same case, the AI chooses — and sometimes it chooses the worst one. The clause of exclusion takes the choice out of her hands: "for this case, use X, never Y". The example that sets the standard comes from Cursor: use the dedicated file tool, never the terminal.
Use specialized tools instead of terminal commands when possible… don't use cat/head/tail to read files, don't use sed/awk to edit files… Reserve terminal commands exclusively for actual system commands.
Notice the form: it says what use (the dedicated tool), what don’t use (cat, head, tail, sed, awk) and reserve the terminal for what is actually a system command. Choice eliminated.
✓ Exclusion that works
- ✓"To read a file, use the reader — never the terminal"
- ✓Name both the winner and the prohibited option unambiguously
- ✓Applies only to the specific case (“for this”), not everything
- ✓Solve a real mix-up you’ve seen happen
✗ Exclusion that gets in the way
- ✗"Don’t use the terminal" — without saying what to use instead
- ✗Forbids without a use case ("never, ever"), blocking legitimate uses
- ✗Create exclusivity between tools that don't overlap
- ✗Invents a rule for a conflict that never occurred
<ferramentas> Para ler/editar arquivos, use a ferramenta dedicada — nunca o terminal. Reserve o terminal só para comandos de sistema de verdade (git, mkdir, mover). </ferramentas>
Batching and parallelism
This is where a huge speed gain that almost nobody writes into the prompt lies: when you need several things that don’t depend on one another, ask for all of them at a time, in the same block — in parallel. Reading three different files? Looking up two different things? There’s no reason to do them in sequence. Claude Code’s parallelism rule says so directly.
If you intend to call multiple tools and there are no dependencies between the calls, make all of the independent calls in the same block.
The condition is “no dependencies between the calls"; the action is "make all of the independent calls in the same block". Independent → together. Dependent → no (that's the next topic).
Without a contract: waiting in line for no reason
AI reads file A, waits, reads B, waits, reads C. Three round trips.
Nothing there depended on anything else — A, B, and C are independent. But without the rule, the model serializes them out of habit. The user waits three times longer than necessary, and the task slows down for no reason.
With a contract: all in the same block
AI runs all three readings together and reads the three responses that come back.
One round trip. The batching contract says: independent calls → in the same block, in parallel. The result is the same, but it arrives in a fraction of the time. Free speed.
The independence test
Before grouping, ask: "Does call B need the result from A?" If the answer is no for all of them, run them all together. If one is needed, leave it out of the batch and wait. Batching only works for things that are genuinely independent—don’t force parallelism where there’s a dependency.
Don’t mention the tool by name to the user
A small etiquette clause, with a big effect on the experience: when speaking with the user, describe the action in natural language — don’t recite the tool’s internal name. The user wants to know "I'm looking that up for you," not "I'm going to invoke the function web_search with the parameter query". The tool's name is backstage business.
✓ Say it like this (natural language)
- ✓"Let me look that up for you…"
- ✓"I’ll read the file to see what’s in it"
- ✓"I calculated it, and the total is R$ 1.240"
- ✓Describe the intent, not the mechanism
✗ Don’t say it this way (it reveals behind-the-scenes details)
- ✗"Calling the tool search_web…"
- ✗"Running read_file(path=…)"
- ✗"I’ll use the function calculator now"
- ✗Exposes internal names that mean nothing to the user
Não cite o nome da ferramenta ao falar com o usuário; diga em linguagem natural o que está fazendo.
Why this really matters
The tool’s name is an implementation detail. Mentioning it clutters the conversation, confuses nontechnical readers, and ties your prompt to names that may change. The rule keeps the AI speaking of results, not plumbing — and the experience stays clean.
Chaining: use the previous result
The opposite of batching: sometimes call B only makes sense in light of what A returned. Then you can't parallelize — it has to be done in sequence, and B needs to consume A’s exact output. This is the chaining: the contract that says "take this field from the previous result and pass it to the next one." Without it, the AI invents the link—and breaks the pipeline.
A — search: "find the order ID using the customer’s email"
returns: pedido_id = 8842
B — elaborate: "open the request details {request_id}"
contract: use exactly the pedido_id that A returned — don’t guess a number.
Notice the pattern: the chaining clause names which field leave A and to where goes in B. The more exact the declared format ("the pedido_id in numeric format"), the less the AI improvises. It's the sibling of exclusion: one says which tool, the other says with which piece of data.
⚠️ The three chaining errors
When the pipeline breaks, it’s almost always one of these:
- 1.Parallelize dependent work. B runs alongside A and uses a value that doesn’t exist yet → error or junk.
- 2.Invent the link. AI doesn't pick the actual field from A; it guesses a plausible value and moves on → wrong result, no warning.
- 3.Imprecise format. The contract doesn’t say which field or in what format → the AI grabs the wrong part of the output.
🛠️ Hands-on: your deliverable
Take an AI of yours that uses tools and write their contract. In 15 minutes, you’ll complete all six clauses.
- 1 List the tools your AI actually has. For each one, write the trigger: "use when {condição}".
- 2 Mark the prerequisites (does any need a step beforehand? e.g., read before editing) and the exclusions (do the two get confused? “use X, never Y”).
- 3 Write the rule for batching ("independent → in the same block") and mark the chains (Which field does B need from A?).
- 4 Add the label line (“don’t mention the tool’s name to the user”). Paste everything into the block <ferramentas>, run a real task and see whether the AI chooses and groups them correctly.
📝 Module Summary
- ✓O Tool Contract says when and in what order call — not just what exists
- ✓Trigger: tie the tool to an observable condition — "use when {condition}"
- ✓Prerequisite: the required step beforehand—e.g., read before editing
- ✓Exclusion: "use X, never Y" for the case—eliminating the wrong choice
- ✓Batching: independent calls → in the same block, in parallel; dependent ones → chained in series
- ✓Label: tell the user the action in natural language — don’t name the tool
➡️ Next Module
2.5 — 🔁 The operational loop. You hired the tools; now let’s give AI the work cycle that uses those contracts with discipline: ground, reason, act, observe, verify, narrate—the agent’s brain.