Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover destructive/idempotent/readOnly, but the description adds substantial new context: atomicity, the exact precondition states that gate success, escalation behavior on failure, replay semantics returning the original outcome, and a mandatory Idempotency-Key header not captured anywhere in structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action, then layered with preconditions, escalation path, and idempotency in tight sentences. No filler; each clause adds actionable constraint information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, precondition-gated tool with no output schema, the description covers success window, failure escalation, idempotent replay behavior, and the required header. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries full burden. It clarifies agent_session_id semantics (the order must have been placed via the same session) but says nothing about order_id's format or origin. Partial compensation for the coverage gap warrants a mid-range score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("Cancel an order") and scopes it to orders placed via the same agent_session_id, distinguishing it from unrelated siblings like cancel_reservation. An agent can identify the target operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the success window ("only succeeds while the order is still in 'pending' or 'confirmed'"), the failure condition ("once the kitchen starts preparing"), and names the alternative ("escalate to waiter_call"). This is textbook when/when-not/alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.