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

Annotations cover only the safety profile (readOnly, idempotent, non-destructive), leaving the most important trait to the description: this is a long-blocking call with a ~25s round, a 90s server-side ceiling, and a 5-attempt retry protocol. That retry/timeout semantics is exactly what an agent needs and what nothing else provides.

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 core behavior, then the retry protocol, then the rationale and precondition. Dense rather than padded, but the six-sentence length is near the upper bound for a single tool; the PostFinance explanation 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 are not the description's burden, and it still signals that a final state is reported. For a blocking, retry-looped tool with non-obvious failure semantics, the description supplies everything needed to invoke it correctly.

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%: attempt and max_seconds are documented in the schema, but order_handle is bare, and the description compensates by pinning its origin ('Verlangt das Handle aus create_order'). It also reinforces the attempt increment and the warning against raising max_seconds beyond the webserver truncation point, adding rationale the schema only states flatly.

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: it holds the request open until a payment for an order has arrived, then reports the final state. This is clearly distinguishable from siblings like get_order_status (a non-blocking query) and create_payment_link (which initiates).

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?

Names the trigger condition explicitly ('sinnvoll direkt nach create_payment_link, sobald die Zahlungsaufforderung im Gespraech steht') and explains why no alternative exists ('Der Chat erfaehrt von einer Zahlung nichts von selbst'). It also pre-empts a likely misuse: an empty 25-second round is not an error but a signal to start the next round, capped at 5 attempts.

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