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

The description adds crucial context beyond annotations by warning 'mexe em dinheiro, irreversível' (deals with money, irreversible), which meaningfully frames the tool's risk profile. It also discloses bulk execution. However, with readOnlyHint: false already signaling a write operation, the description's added behavioral value is modest; it doesn't explain what happens server-side (e.g., whether NF-e is immediately registered with authorities), side effects, or failure modes—valuable for a financial mutation. No annotation contradiction found.

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 description is information-dense, packing a warning, an action catalogue, a flattening directive, and bulk support into four short lines—efficient for the number of concepts covered. However, it front-loads four irrelevant actions that belong to sibling tools, forcing the reader to wade through redundancy before reaching the relevant '[Flattened action: generate_invoice]'. Leaner, more targeted phrasing would improve scannability.

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 an irreversible financial mutation with no output schema, the description omits critical operational aspects: no mention of expected response shape (e.g., invoice ID, NFe status), no asynchronous processing notes, no prerequisites (e.g., transaction must be approved), no validation rules for the 'data' payload, and no error conditions. Given its complexity (nested 'data' object, 4 params) and the absence of output schema, the description is incomplete; the warning about irreversibility is good but incomplete for an agent to reliably invoke this tool.

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?

With 0% schema description coverage, the description had to compensate but only clarifies that 'id' is the identifier for the transaction (via 'generate_invoice (id, NF-e BR)') and that 'ids' enables batching. The 'data' object—often the NF-e payload—is entirely unexplained despite being a likely complex object with property names/values, and 'account' is never mentioned. The description provides minimal meaning over the raw schema for an important parameter ('data') and misses another ('account').

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 description identifies this as a transaction mutation tool and specifies 'generate_invoice (id, NF-e BR)', clearly indicating Brazilian electronic invoice generation. However, purpose clarity is undermined by listing five different actions (refund, chargeback, reissue, update_buyer, generate_invoice) in a single blob; the agent must parse '[Flattened action: generate_invoice]' to infer this is the only relevant action. The verb feels implicit—'generate' is implied but the description is a generic template rather than tuned for this specific tool.

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?

The description provides no explicit when-to-use or when-not-to-use guidance for the generate_invoice action. It implicitly differentiates by listing alternative actions (refund, chargeback, etc.), which a careful agent could use to distinguish this from sibling tools, but there is no decision support—no statement like 'use generate_invoice when you need to issue a fiscal receipt for a completed transaction.' The bulk note gives a usage hint but no exclusion criteria.

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