CONTRACT DESK / GUIDES03 NOTES
Design the contract
before the integration.
Portability, prompt weight, and version safety decided up front instead of debugged later.
What this section covers
Tool definitions are prompt content and API surface at the same time. They occupy context on every request, they steer which tool a model selects, and they are a contract that callers depend on. That combination makes ordinary API-versioning instincts insufficient.
These guides cover the decisions that are expensive to reverse: how to express optionality so it survives compilation to every provider, how to reduce schema token cost without deleting the descriptions models rely on for routing, and how to classify a change as structural, behavioural, or safe.
Agent tool contract guides
Portable optional fields across OpenAI, Anthropic, Gemini, and MCP
Design optional tool parameters once, then compile correct provider-specific null and required semantics.
- Optional ≠ nullable
- Provider-specific required rules
- Canonical intent
Estimate and reduce tool schema token cost
Estimate tool-definition prompt weight and reduce it without deleting the descriptions models need for reliable routing.
- Approximate token weight
- Active-tool pruning
- Description value
Detect breaking changes in agent tool contracts
Classify required fields, enums, unions, side effects, and output changes before an agent tool deployment breaks callers.
- Structural breaking changes
- Behavioral description diff
- Side-effect annotations
RELATED WORKBENCHES01
Reproduce it locally.
These tools take the same evidence the notes above describe and compute the result in your browser tab.
Section FAQ
Before you dig in
Why does a description change count as a breaking change?
Descriptions are how a model decides whether a tool applies. Rewriting one can change tool selection even though every schema still validates — a behavioural break that structural diffing will not catch.
How much context do tool definitions actually consume?
Enough to matter once an agent carries a dozen tools: definitions are re-sent with every request. The token cost guide shows how to measure the real weight and which reductions are safe.
CONTINUERELATED SECTIONS
Field-level differences that change client code, not marketing feature tables.
Open section →Contract deskTool schema convertersMechanical repairs where intent is recoverable; explicit warnings where it is not.
Open section →Workbench indexAll six APITC toolsDecode, simulate, analyse, plan, diff, and compile — locally.
Open section →