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

Beyond the readOnly/idempotent annotations, it discloses side-effect-like costs ('gasta uma das consultas da hora'), a success precondition (completo: true), and the response shape (download link in files[]). It even warns the agent not to read the file because it is binary, which is genuinely useful runtime guidance.

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 definition is front-loaded with the purpose, then organized into usage guidance, constraints, and output handling. No sentence is filler; warnings and conditions earn their place.

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?

Even without an output schema, it tells the agent what to do with the result (hand the files[] download link to the user, do not read binary content) and covers all relevant success/failure conditions. The only minor omission is the account parameter, which does not materially undermine the call path.

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 carries the burden and does explain xml, chave, and nsu in terms of when to use each and their SEFAZ cost. The account parameter is not mentioned at all, leaving a gap; otherwise the parameter guidance is strong.

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 opens with a concrete action and resource: 'Gera o DANFE (o PDF da nota) a partir do XML.' It also clarifies that SEFAZ supplies XML, not PDF, which distinguishes this tool from the sibling retrieval/consultation tools like dfe_sincronizar and dfe_consultar_chave.

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?

It provides explicit COMO USAR instructions: pass the xml field from dfe_sincronizar to avoid consuming a SEFAZ query, or fall back to chave/nsu while acknowledging the query cost. It also states the hard precondition that only documentos with completo:true can be used and explains why resumo documents fail.

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