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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description goes further by disclosing a side effect not visible anywhere in structured data — the PostFinance reservation is released immediately instead of after three days — and a mandatory two-step human-confirmation protocol that governs how the tool may be invoked. That is exactly the kind of behavioural context annotations cannot express.

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?

Purpose and the state restriction are front-loaded in sentence one, and each following sentence carries a distinct rule (confirmation flow, no batch cancellation, handle provenance) with no filler. It is however fairly long and dense, with several parallel 'Nur ...' constraints that could be tightened.

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?

An output schema exists, so return values need no explanation, and the description covers everything else an agent needs: prerequisites, the exact confirmation protocol, scope limits, and what to do when the user gives no order number or says 'alle'. Nothing required for a correct call 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 67% and order_handle has no schema description, so the description compensates by specifying its provenance (output of create_order or list_orders, with list_orders first for older orders) and by defining the invocation semantics of confirmed_in_chat beyond the schema's 'never set yourself' rule. The optional reason parameter is left entirely to the schema and gets no added meaning in the description.

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?

Names a specific verb and resource ('storniert eine eigene Bestellung') and narrows it with a precise state precondition ('noch offen oder reserviert'). It also distinguishes itself from siblings by naming create_order and list_orders as the handle sources, so an agent can place it without opening any other 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?

Gives an explicit call sequence: first invoke without confirmed_in_chat to preview what would be cancelled, ask the person, then re-invoke with confirmed_in_chat: true only after consent. It also states a clear exclusion/handling path — never batch-cancel on 'alle', instead enumerate the cancellable numbers and ask — and names the prerequisite handles and the fallback to list_orders for older orders.

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