Connected Patterns: Turning Tool Calls Into Reliable Systems
“A tool contract is the difference between an agent that guesses and an agent that can be trusted.”
Agents do not fail only because they “reason badly.” They fail because the world around them is not shaped for their use.
Popular Streaming Pick4K Streaming Stick with Wi-Fi 6Amazon Fire TV Stick 4K Plus Streaming Device
Amazon Fire TV Stick 4K Plus Streaming Device
A mainstream streaming-stick pick for entertainment pages, TV guides, living-room roundups, and simple streaming setup recommendations.
- Advanced 4K streaming
- Wi-Fi 6 support
- Dolby Vision, HDR10+, and Dolby Atmos
- Alexa voice search
- Cloud gaming support with Xbox Game Pass
Why it stands out
- Broad consumer appeal
- Easy fit for streaming and TV pages
- Good entry point for smart-TV upgrades
Things to know
- Exact offer pricing can change often
- App and ecosystem preference varies by buyer
A human can look at a tool response that is half broken, oddly formatted, or missing a field and still recover. A human can notice that a date looks wrong, that a table column shifted, that a value is in the wrong units, and still make a good decision.
An agent often cannot. If you hand an agent a fragile tool, you will get fragile behavior.
This is why tool contracts matter. A contract is a promise the tool makes to the agent about what the tool does, what it will return, how errors will be expressed, and what side effects are allowed. Once you have contracts, you can validate, recover, and route safely. Without contracts, you are relying on luck, and your “agent” is just a prompt that sometimes gets away with it.
The Problem You Are Actually Solving
A tool contract is not documentation for humans. It is an operational boundary for an automated system.
The contract exists to make these things true:
- The agent can predict the shape of outputs even when the tool fails.
- The agent can validate results quickly and detect partial or unsafe outcomes.
- Side effects are explicit and can be blocked behind approvals.
- Retries are safe because the tool supports idempotency.
- The system can evolve without breaking older runs because versions are controlled.
When those properties hold, you can build routing and verification policies that are calm and boring. Calm and boring is the point.
What a Tool Contract Contains
A good contract fits on one page, even if the tool is complex. It is specific enough for an agent to follow, and strict enough for engineers to test.
A practical contract includes:
- Purpose and scope, stated in one sentence.
- Inputs with types, required fields, and allowed ranges.
- Defaults and assumptions the tool will apply when inputs are missing.
- Side effects, including what can be modified and what will never be modified.
- Output schema, including required fields and “may be missing” fields.
- Error schema that is always returned on failure in the same predictable shape.
- Idempotency behavior, including the key or token that makes repeats safe.
- Time, cost, and rate limits expressed as explicit budgets.
- Security boundaries, including what the tool is forbidden to access or reveal.
- Examples of both success and failure responses.
If you build these into the tool output itself, the agent can keep itself honest without extra prompt tricks.
The Single Most Important Rule
Tools must return a structured envelope even when they fail.
If a tool returns a blank string, a random stack trace, or an HTML error page, your agent has no reliable way to recover. It will either hallucinate a result or retry until the run dies.
A contract envelope looks like this conceptually:
- status: success or error
- data: the normal output payload if successful
- error: a typed error object if failure
- warnings: non-fatal issues that the agent should surface
- metadata: latency, cost estimate, version, and idempotency information
When every tool response fits this shape, you can write simple validation and routing rules that work across the whole system.
Contracts Turn “Edge Cases” Into Normal Cases
If you do not use contracts, your system has infinite edge cases. Every tool failure becomes a new prompt band-aid.
If you do use contracts, most edge cases collapse into a small set of typed outcomes:
- Validation failed because inputs were malformed.
- Permission denied because the action is restricted.
- Transient failure because the network or provider is down.
- Partial result because the tool hit a budget.
- Conflict because the requested change would overwrite something.
Each of those outcomes can map to a calm policy. Calm policies are what keep agent systems from becoming incidents.
| Failure you will see | Contract clause that prevents chaos | What the agent can do safely |
|---|---|---|
| Output missing fields | Required fields with validation errors | Ask for missing inputs or re-run with corrected params |
| Tool returns unstructured errors | Always-return error envelope | Classify, backoff, and report without guessing |
| Retry causes duplicate side effects | Idempotency key requirement | Retry safely without creating duplicates |
| Tool does too much | Explicit side-effect list | Block, request approval, or switch to read-only mode |
| Tool runs forever | Hard time budgets + partial flag | Stop, summarize partial results, choose a fallback |
Contract-First Tool Design
A common mistake is building the tool, then writing the contract later. By then, behavior is inconsistent and hard to constrain.
Contract-first design flips the order:
- Write the envelope schema.
- Write the success payload schema.
- Write the error taxonomy for that tool.
- Decide which fields are mandatory versus optional.
- Decide how partial results must be marked.
- Decide what the tool is forbidden to do.
Then implement the tool to satisfy the contract. This produces a tool that is easier to test, safer to expose, and friendlier to agents.
Make Side Effects Loud
Agents should not infer side effects. They should see them.
If a tool can change state, the contract should say exactly what it can change and under what conditions. It should also provide a “dry run” mode that returns a preview rather than performing the change.
Dry runs are one of the best tools for agent safety because they force the system into a verify-before-act rhythm:
- Preview the change.
- Validate that the preview matches intent.
- Ask for human approval if required.
- Execute the change using the same idempotency key.
This pattern eliminates most high-cost mistakes.
Validation Is Part of the Contract
Validation should not live only in the agent prompt. It should be built into the system.
A contract should include explicit invariants that can be checked automatically. Examples:
- Returned totals must match the sum of line items.
- Dates must be ISO-8601 and include timezone when relevant.
- IDs must match a defined regex.
- Currency must be explicit and never implied.
- “Updated_count” must equal the number of objects in “updated_items”.
When the tool enforces these, your agent can trust the tool more, and your monitoring can alert earlier.
Human-Readable Fields Are Still Valuable
Structured outputs keep machines reliable. Human-readable fields keep operators sane.
A good contract can include a short summary field that mirrors the structured output:
- summary: one paragraph describing what happened
- evidence: a short list of references or identifiers
- next_actions: suggested follow-ups when partial results occur
These are not excuses for unstructured blobs. They are operator aids that make run reports and debugging easier without compromising reliability.
Versioning Without Pain
If your tool contract changes, older agents can break.
The simplest way to prevent this is explicit versioning:
- The agent sends a requested contract version.
- The tool responds with the version it used.
- When a breaking change is needed, publish a new major version and keep the old one available.
Versioning feels like overhead until the day you need it. That day will arrive.
The Payoff: Better Routing and Better Safety
Once you have tool contracts, routing becomes straightforward.
The agent does not need to “feel” its way through the run. It can follow crisp rules:
- If validation fails, do not retry. Ask for corrected inputs.
- If permission is denied, escalate for approval rather than trying alternatives.
- If transient failure, retry with backoff and a max attempt cap.
- If partial result, summarize, then decide whether to expand budget or accept partial.
- If conflict, produce a diff and ask a human to choose.
Those rules turn chaotic behavior into a controlled system.
Testing a Contract Like You Mean It
If a contract cannot be tested, it will drift.
The quickest way to make contracts real is to build a small suite of contract tests that run in CI:
- Golden responses for a few standard inputs, including edge values.
- Property checks that required fields always exist and optional fields are marked correctly.
- Error tests that force each typed error and confirm the envelope shape.
- Idempotency tests that repeat the same call and verify no duplicate side effects.
- Budget tests that confirm partial results are labeled and summaries are consistent.
When contract tests exist, an agent system becomes easier to evolve because every change proves that the boundary still holds.
Keep Exploring Reliable Agent Workflows
• Tool Routing for Agents: When to Search, When to Compute, When to Ask
https://ai-rng.com/tool-routing-for-agents-when-to-search-when-to-compute-when-to-ask/
• Guardrails for Tool-Using Agents
https://ai-rng.com/guardrails-for-tool-using-agents/
• Verification Gates for Tool Outputs
https://ai-rng.com/verification-gates-for-tool-outputs/
• Sandbox Design for Agent Tools
https://ai-rng.com/sandbox-design-for-agent-tools/
• From Prototype to Production Agent
https://ai-rng.com/from-prototype-to-production-agent/
Books by Drew Higgins
