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

Annotations only supply destructiveHint=true, so the description carries most of the burden and delivers: nothing is sent via e-mail or post, nothing is marked paid, and no payment link or discount is generated. It further discloses quota cost (client_id lookup consumes 2 of the daily requests), non-idempotency, and the checksum-based recovery path — exactly the operational traits an agent needs before calling a mutating endpoint.

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?

The 'WRITE:' prefix and the two negations (not sent, not paid) are front-loaded where an agent will see them first, and nearly every clause carries distinct information. It is a dense single paragraph with heavy parenthetical nesting, which costs some scanability.

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 26-parameter mutation with no output schema and only a destructiveHint annotation, the description covers the safety-critical behaviors (unsent, unpaid, non-idempotent, quota cost, recovery tool). It leaves the response content and the behavior when client_name matches an existing client slightly under-specified.

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 description coverage is already 100%, so the baseline would be 3; the description earns a bump by explaining the client_id-vs-client_name decision rule, the item shape (name, unit price without VAT, VAT rate, quantity), and the recovery role of the checksum beyond its length limit. It does not explain the numbering/sequence or symbol fields, which the schema alone carries.

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 and resource ('WRITE: creates ONE document in SuperFaktura') and immediately enumerates the exact document types it can produce (draft/estimate/order/proforma). It also draws a hard boundary ('A final regular invoice cannot be created here'), which lets an agent distinguish it from every other creative sibling without opening a 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 clear when-to-use context (unsent draft/estimate/order/proforma for user review) plus an explicit negative boundary against final invoices, and routes the agent to superfaktura_get_response_by_checksum for timeout recovery instead of retrying. It does not name a sibling for the excluded case (issuing a real invoice) or state prerequisites, so it stops just short of full when/when-not routing.

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