An agent tool needs a contract its server actually enforces
Tool descriptions help a model choose an action. Schema validation, authorization and documented retry behavior determine what the server will actually permit.

A model can produce valid JSON for the wrong business action. A well-described tool helps it choose an operation, while the server's contract determines whether that operation is allowed. Both parts need to describe the same behavior.
Start with one action whose completion can be observed. A tool that creates an invoice draft should say that it creates a draft. If sending the invoice is a separate action, give that action its own boundary. The distinction should appear in the implementation as well as the description the model receives.
Explain the condition for choosing the tool
A short description can identify the user's intent that the tool handles. It can also name the nearby intent handled by a different tool. Someone asking to change an existing invoice needs an update operation, with an identifier for the existing document. Someone asking to inspect an invoice needs a read operation.
Keep the names stable across those descriptions. Renaming the same object in each paragraph makes the relationship harder to inspect. The model-facing definition should use the same field names as the server that receives the request.
Examples should expose the distinction. Give the tool a case where creation is appropriate, then a case where it would produce a duplicate because the user asked to update an existing draft. The second case tests routing behavior that an ordinary successful example leaves unexamined.
Validate the actual arguments
JSON Schema gives the server a way to describe input structure. Listing an object property does not automatically make it required. Extra properties also remain allowed unless the schema constrains them. These are defined behaviors, explained in the JSON Schema object reference.
For a hypothetical tool that creates a draft from an existing customer and approved line items, a small schema could begin like this:
{
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"minLength": 1
},
"line_item_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1
}
},
"required": [
"customer_id",
"line_item_ids"
],
"additionalProperties": false
}
That schema can reject a missing customer identifier or an empty list. The server must separately check whether the caller can use that customer, whether the listed items exist, and whether creating this draft is allowed. Those are joint business conditions outside the structural example.
The default annotation needs similar care. JSON Schema validation does not fill an omitted value merely because the schema includes a default. If the application applies a default, define that behavior in the application contract. The annotation reference explains the distinction.
An adapter may also accept only a subset of the schema vocabulary used by the server. Test the exact definition sent through that adapter. A schema that validates in one library can still be unsupported by the interface that exposes it to the model.
Explain what a retry will do
After a timeout, the client may not know whether the server completed the action. The response path can fail after the server has already written the result. A tool contract needs to explain how the client can resolve that uncertainty.
Stripe provides a concrete example of documented idempotent behavior. In its API v1, an idempotent retry can return the stored status and body from the original executed request, including a server error. Retention and parameter matching also affect reuse of the request identifier. Stripe's idempotency reference states the behavior for that API.
A different service may implement a different contract. Document the identifier's scope, how long the server remembers it, and what happens when the same identifier arrives with different parameters. These details belong beside the operation that can create a side effect.
The response should help the caller distinguish a rejected input from an uncertain completion. A validation error gives a reason to repair the arguments. An uncertain completion may require reading the existing result before another write is attempted. Treating every failure as permission to submit a new creation request can duplicate work.
Treat annotations as descriptions of behavior
MCP tool annotations can describe whether an operation is read-only or idempotent. The MCP maintainers' March 2026 discussion explicitly calls them hints, with trust depending on the server providing them. They describe a behavior the client may consider; they do not implement that behavior. The maintainers' explanation sets out that limitation.
A server must enforce the permissions for a write even when the client receives a read-only-looking description. The client also needs its own authorization decision about the requested action. The tool's wording is part of the interface through which that decision is made.
Keep a regression set for the complete contract. Include a valid request, a structurally invalid request, and an attempted action outside the caller's permissions. Add the timeout case that exposes the retry rule. These cases test different failure paths.
Run that set when changing the schema, the implementation, or the model that chooses the tool. Inspect the chosen operation alongside the server result. A correct tool contract is observable when the permitted request completes and the prohibited request stops at the defined boundary.