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

With only generic annotations (readOnlyHint=false, destructiveHint=false), the description carries the behavioral load and does it well: per-page pricing, no charge on an unknown/changed quote, 202-then-GET follow-up, 502 pago_nao_registrado with recibo for refund/support, and how the purchase is recorded against the account/guest right. It states consequences and failure modes rather than just restating the mutation hint, though the delivery/return shape is never described.

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?

A dense run-on block of payment jargon that is not front-loaded: the first thing the agent reads is a price, not what the tool produces. Sentences like 'with the edm_… guest (Bearer), the right is the guest's and the code comes along' pack several distinct rules without structure, forcing re-parsing.

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 paid, stateful operation with no output schema, the description does cover charging rules, retry/idempotency behavior, and error paths. It still omits what a successful response contains, how the markdown is delivered (inline vs. via get_tender_markdown), and how it relates to generation_status or document access siblings.

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 100%, so the baseline is 3. The description adds a little beyond the schema — confirming pages/hash/total against the quote, noting guest Bearer vs X-Credito vs account session, and warning to retain acesso.codigo — but it leaves several of the seven parameters (agent_pass, avaliacao_codigo, idempotencia) to the schema alone.

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?

The opening sentence describes a commercial transaction ('Buys individual access to the document for US$ 0.02/page') rather than the operation itself; the actual purpose only surfaces obliquely in 'A ready text reuses the OCR; a necessary generation is included.' Nothing distinguishes it from siblings like get_tender_markdown, documento_acesso or get_document, so the agent must infer this is the paid markdown generation endpoint.

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?

There is real usage context: send cotacao when authorizing payment, follow up a 202 via GET, keep acesso.codigo for later reopening, and choose between x402, credito_token, and guest/agent credentials. However, there are no explicit when-to-use/when-not rules relative to the several sibling tools that also expose document access.

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