fiscal

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds useful return-format context ('Retorna conteúdo em base64'), but says nothing about rate limits, batching behavior, or what happens with multiple Chaves.

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?

Two tight sentences with no filler, and the core operation is front-loaded. It is appropriately sized, though the brevity contributes to the unaddressed parameters.

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 5-parameter tool with 40% schema coverage and no output schema, the description omits essential detail on three undocumented parameters and provides no sibling differentiation. Only the base64 return hint rounds it out.

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 only 40%; only FileType and TipoDocumentoFiscal carry descriptions. The description's 'por chave de acesso' partially maps to ChaveNF/Chaves, but it does not clarify the Chaves-vs-ChaveNF relationship or the purpose of Base64Logo, leaving the coverage gap only partly compensated.

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 (Baixa) and resource (arquivo XML/PDF de NF-e/NFC-e/NFS-e), and names the lookup key (chave de acesso). It does not distinguish itself from the closely named siblings arquivo_baixar_evento and arquivo_baixar_periodo, which an agent must disambiguate against.

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 gives no when-to-use guidance and never references the sibling download tools or the conditions that select this one over them. Usage is only implied from the tool name.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context — the payload is base64-encoded, which the agent must decode — but says nothing about failure behavior (invalid key, event not found, PDF unavailable for certain event types).

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?

Two tight sentences with the action and the return format front-loaded; every clause carries information. The 'chave de acesso + número sequencial' fragment mildly duplicates the schema, keeping it just short of ideal.

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?

With no output schema, the description rightly discloses that content comes back as base64. However, for a tool where all three parameters are optional, it gives no hint about which combination is needed or how TipoArquivo=2 availability varies by event type, leaving meaningful gaps for correct invocation.

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%: every parameter, including the TipoArquivo enum, is documented in the schema. The description only restates the inputs, and its phrase 'número sequencial' is a slightly loose gloss on NuProtocolo (protocolo do evento), which is a minor source of ambiguity rather than added meaning. Baseline 3 applies.

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 (baixa) and resource (arquivo de um evento), enumerating the event types it covers (CC-e, cancelamento, manifestação, encerramento) and naming the two identifying inputs. It does not explicitly distinguish itself from the sibling file tools arquivo_baixar / arquivo_baixar_periodo, so an agent must infer the difference from the 'evento' qualifier.

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?

Usage is implied by the resource qualifier: use this when you need the file of a specific event identified by access key plus protocol number, rather than a whole NF-e or a period download. There is no explicit when-to-use/when-not statement nor a named alternative, leaving the agent to derive the routing from sibling names.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description usefully discloses the return packaging (single ZIP in base64), but says nothing about volume limits, size caps, or that XML/PDF/EXCEL are all selectable, which matters for an 11-parameter export.

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?

Two sentences with zero redundancy, and the core capability (multi-file export of a period into one ZIP base64) is front-loaded before the use-case hint.

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 need not be described, and 0 required parameters means no mandatory-input caveats are missing. For an 11-parameter tool the description is thin on filtering behavior (e.g. how Chaves, cpfCnpjs and Situacoes combine), but it is not required for a correct call.

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 100%, so the schema already documents every parameter including enum meanings and defaults. The description adds no parameter-level detail, and even narrows the format to "XML/PDF" while the Type enum also offers EXCEL (0-PDF, 1-XML, 2-EXCEL). Baseline 3 applies.

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 (Exporta), resource (múltiplos arquivos XML/PDF), scope (um período) and output form (ZIP base64). This implicitly distinguishes it from the singular sibling arquivo_baixar, but neither sibling is named, so an agent must infer the difference rather than read it.

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?

"Útil para backup, contabilidade ou auditoria" gives positive usage contexts but no when-not conditions and no references to arquivo_baixar or arquivo_baixar_evento as alternatives. The agent gets a hint of intent but no routing rule.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, openWorld, non-destructive), and the description layers on the traits that matter: absent IE does not imply an inactive CNPJ, automatic Receita Federal fallback for CNPJs with the 'fonte'='receita' marker, and an instruction to always read 'mensagem'. This is behavioral disclosure well beyond the annotations.

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 action, then caveats and the fallback rule. Dense and largely waste-free, though the capitalized warnings make it longer than a minimal summary and could be trimmed slightly.

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 need no explanation, and the description still covers the interpretive traps (missing IE != inactive CNPJ, fallback source, 'mensagem' field). Given the open-world external dependency, this is complete enough for an agent to call and interpret results 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 50% and the 'cpfCnpjIe' property has no schema description, but the description compensates by stating the accepted identifier types (CNPJ/CPF/IE) and pairing them with UF. It adds real meaning over the bare schema, though it doesn't spell out format expectations.

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 ('Consulta a Inscrição Estadual (IE) ... na SEFAZ estadual'), scopes it to the NF-e/ICMS domain, and names the input keys (CNPJ/CPF/IE + UF). It also distinguishes itself from cliente_consultar, so an agent can route between them without opening schemas.

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?

Explicitly names the alternative ('Para apenas saber se um CNPJ está ativo ... prefira cliente_consultar') and the condition that selects it. It also warns when the tool will not yield a useful IE (UFs without the service, service providers), which is exactly the when/when-not guidance an agent needs.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description goes well beyond them: local-first fallback to an external government API, the CPF limitation, and pagination behavior (default 10, max 50, TotalGeral reconciliation instead of inventing data). That is meaningful context an agent needs before calling.

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-loads the core purpose and labels pagination clearly, so it scans well. It is still fairly long and repeats the cadastro_consultar/IE guidance twice, which is minor redundancy rather than bloat.

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 multi-source, externally dependent search tool the description supplies the decision-critical behavior and pagination rules, and an output schema exists so return fields are not the description's burden. The main gap is that four of seven parameters get no explanation anywhere.

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 0%, so the description must compensate. It does give real semantics for Termo (name/nickname/CNPJ, valid-CNPJ triggers BrasilAPI), Limite (default 10, max 50) and Offset, but leaves Uf, Fontes, TipoBusca and IncluirInativas entirely undocumented.

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 clear verb+resource (“Pesquisa unificada de cliente/fornecedor”) and defines the two-stage strategy (local registry first, then BrasilAPI/Receita for valid CNPJ). It explicitly distinguishes itself from cadastro_consultar, so an agent can tell the siblings apart without opening either 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 explicit when-to-use (“Use ANTES de pedir CNPJ ao usuario”), when-not (“consulta na Receita so funciona por CNPJ - CPF nao tem base publica”), and names the alternative with its condition (“Para obter a Inscricao Estadual ... use cadastro_consultar”). Routing is unambiguous.

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

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

Annotations already declare the write/non-destructive profile, but the description adds real behavioral context: the operation is scoped to the logged-in company, and a duplicate CpfCnpj triggers a specific error carrying the existing Id. It stops short of stating permission/auth requirements or whether partially-specified addresses are normalized, so it is strong but not exhaustive.

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?

Three compact sentences with the core action front-loaded and the workflow/error guidance trailing. Nothing is filler, though the parenthetical field list is slightly compressed relative to the parameter surface.

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 mutation tool with an output schema, the description need not explain return values, and it covers the duplicate-error workflow well. The gap is the input side: 10 parameters at 0% schema coverage remain largely unexplained, which is a meaningful omission for a create operation.

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 0% across 10 parameters, so the description carries the full burden and only glosses about four of them (CpfCnpj, Nome, Endereco, Ie). Optional fields like Im, Email, Telefone, IndicadorIe, ConsumidorFinal, and the entire nested Endereco structure (9 subfields) get no meaning, format, or nullability guidance.

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 ('Cadastra um novo Cliente no sistema da empresa logada') and enumerates the core identity fields (CNPJ/CPF, razao social, endereco, IE). It clearly distinguishes itself from cliente_consultar (read) and cliente_editar (update) by naming both siblings.

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 explicit sequencing ('Use depois de cliente_consultar quando o usuario confirmar') and an explicit failure branch: duplicate CpfCnpj returns an error with the existing Id, in which case use cliente_editar. Both when-to-use and the alternative path are spelled out.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), it discloses the critical destructive behavior that omitted fields are zeroed rather than preserved, plus ownership validation (UserCreate) and empresa-scoping rules. This is the kind of consequence detail annotations cannot convey.

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?

Well front-loaded: purpose, then the full-payload warning, then the alternative workflow, then ownership rules. Dense but each sentence carries weight; only minor redundancy in the ownership sentence.

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 covered, and the mutation risks are explained. However, with 0% param coverage and references to a non-existent IdEmpresa plus a required-Id claim that conflicts with the schema, the definition leaves real gaps for a 10-param mutation 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?

Schema description coverage is 0% across 10 params, so the description should carry the field-level burden but does not. Worse, it states "Id e obrigatorio" while the schema's required list is only CpfCnpj/Nome, and it references an IdEmpresa field that does not exist in the schema, so it misleads on parameters rather than clarifying them.

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 specific verb+resource ("Atualiza dados de um Cliente existente no cadastro"), making it clearly distinct from cliente_criar and cliente_consultar. An agent can immediately tell this is the update path for an existing customer.

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 explicitly routes the agent: use a full payload for edits, and for partial edits call cliente_consultar first and resend existing data plus changes. It names the alternative tool and the condition that selects it, which is exactly the when/when-not guidance the dimension asks for.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the agent knows this is a mutating, externally-visible operation. The description adds the 45-day validity window, which is real behavioral context, but says nothing about irreversibility or the meaning of the event registration.

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?

Two tight sentences: purpose front-loaded, constraint second. No filler; every clause carries information.

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 need no explanation, and annotations cover the mutation profile. But with 4 parameters at 50% coverage and no guidance on key/observation inputs, the definition leaves real gaps for an agent invoking it.

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 50%: TipoAmbiente and NumeroSequencial are documented in the schema, but 'Chave' and 'Observacao' are bare. The description adds no parameter meaning at all, so it fails to compensate for the undocumented half of the input surface.

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 (Registra) and resource (desacordo do tomador com um CT-e recebido), and cites the exact event type (evento tipo 4 do CT-e). This cleanly distinguishes it from sibling event tools like evento_cancelar, evento_carta_correcao, and evento_manifestar.

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 '45 dias da emissão' deadline gives a concrete precondition for use, which is genuinely useful. However, it never states when to prefer this over adjacent event tools (e.g. evento_manifestar) or what else must be true before calling.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the safety profile is largely covered. The description adds useful prerequisite context (enabled service, digital certificate) but does not warn that TipoAmbiente=1 issues a legally binding document or describe what a failed SEFAZ response looks like — a notable omission for an irreversible emission.

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?

Two compact sentences with no filler; the operation comes first and the prerequisites second. It is efficiently written, though efficient in this case partly because so much is left out.

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 25-parameter, nested, destructive fiscal emission tool, the description covers only the name and prerequisites. It omits the TipoCte taxonomy (normal/complementar/substituto), the production-vs-homologação consequence, and any note that an output schema exists carrying the authorization result. Far too thin for this complexity.

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 25 parameters, only 8 required and 52% schema description coverage, the description contributes nothing about parameters. It leaves the agent to discover from the schema which 8 are mandatory, that TipoCte=1 needs ChavesComplementadas and TipoCte=3 needs ChaveSubstituida, or that TipoCte has no documented enum in the schema.

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 ("Emite CT-e") with the acronym spelled out, so an agent can tell it apart from nfe_emitir, mdfe_emitir, dce_emitir and the other cte-prefixed tools. It stops short of differentiating from sub-variants like cte_desacordo or evento_* tools, but the core purpose is unambiguous.

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 gives prerequisites (CT-e service enabled on the company record, A1/A3 certificate configured) which imply when the call will succeed. However it never says when to use this versus siblings such as nfe_emitir or the event tools, nor what TipoCte values exist or how they change the required payload.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the mutating/irreversible nature is covered structurally. The description adds a real behavioral constraint — the tool only covers non-fiscal content shipped by an individual or MEI, and requires prior service enablement — but says nothing about production vs test impact, ID return, or authorization flow.

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?

Two sentences, zero padding, and the identifying scope is front-loaded before the prerequisite. Every clause earns its 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?

For a 20-parameter, nested-object, enum-bearing emission tool, the description is thin: it omits the ambient (1/2) choice consequence, the mandatory declaration texts, and any note on what a successful emission returns, even though an output schema exists for the last point. Purpose and one prerequisite are the only gaps it closes.

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 20 parameters at 75% schema coverage, the description must contribute something, and it contributes nothing: not one parameter name, format, enum, default, or required-field caveat (e.g. UfFisco/XOrgaoFisco when TipoEmitente=0) appears in the text. All semantics live in 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?

States a specific verb ('Emite') and resource ('DC-e'), spells out the acronym's meaning, and scopes it to 'transporte de itens não-fiscais por pessoa física ou MEI'. That scope implicitly separates it from fiscal-document siblings like nfe_emitir/cte_emitir, though no sibling is named explicitly.

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 gives one hard prerequisite ('Requer serviço DC-e habilitado no cadastro'), which is useful. But it never says when to prefer this over nfe_emitir/cte_emitir/mdfe_emitir for a given shipment, nor any exclusions or environment guidance, leaving selection largely to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the irreversible write nature is covered structurally. The description adds the genuinely useful SEFAZ 24h post-authorization window, but says nothing about permissions, idempotency, or what happens if the window has passed.

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?

Four dense sentences, front-loaded with the action and its supported document types, with no filler. Slightly crowded by packing the NFS-e branch and the SEFAZ deadline into the same block, but every sentence carries operational information.

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?

With an output schema present, return values need no explanation, and the description covers document routing, required inputs, and the critical time constraint. Missing only ancillary context such as authorization requirements or consequences of cancellation after the deadline.

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 100% and every parameter is already documented in detail, including the cross-parameter branching for TipoDocumento. The description largely restates that routing logic (TipoDocumento=1 → NumeroNFSe, otherwise chave) rather than adding syntax or format detail beyond the schema.

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 (Cancela) and resource (documento fiscal autorizado), and enumerates the exact document types covered (NF-e, NFC-e, NFS-e, CT-e, MDF-e, DC-e). This clearly separates it from siblings like evento_inutilizar and evento_carta_correcao, which act on unused numbers or corrections rather than authorized documents.

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 concrete invocation conditions: supply the 44-digit chave plus a justification of at least 15 characters, and use TipoDocumento=1 with NumeroNFSe for NFS-e. It also flags the real-world SEFAZ 24-hour deadline that gates whether the call can succeed, though it never explicitly contrasts itself with sibling event tools.

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

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

Annotations already convey destructive, non-read-only, open-world behavior. The description adds valuable business-rule context beyond annotations: specific correction exclusions (values, dates, parties, tax regimes, document number/series) and a per-document event limit, which help the agent understand what will happen and what is prohibited.

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 three tight sentences, front-loading the core action and purpose before listing exclusions and limits. Every sentence adds material information with no redundancy.

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?

With an output schema, full parameter descriptions, and annotations covering safety, the description supplies the remaining essential context: what the event does, what it cannot correct, and the CC-e limit. Nothing critical for correct invocation is missing.

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 100%, so all five parameters are already documented in the input schema. The description restates some correction restrictions but adds no syntax or format details beyond what the schema provides, making 3 the appropriate baseline.

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 states a specific verb ('Envia') and resource ('Carta de Correção (CC-e)') for an authorized NF-e or CT-e, explicitly noting the event type (2). It is clearly distinguishable from sibling event tools like evento_cancelar or evento_manifestar.

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 clear constraints on when this tool is appropriate: only for authorized documents, and it lists fields that cannot be corrected plus a 20-per-NF-e limit. However, it does not explicitly name alternative tools (e.g., evento_cancelar) for cases where correction is not allowed.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true. The description adds that the action cannot be undone, is a rare operation, and requires user confirmation before execution, which goes beyond the annotation's binary destructive flag and gives operational context. No mention of authentication or rate limits, but for a rare irreversible action this is helpful.

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?

Three sentences, front-loaded with purpose, then usage context, then caution. Every sentence earns its place; no redundant restatement of schema or annotations.

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?

Given the destructive, rare nature and full schema/annotation/output schema coverage, the description supplies the necessary usage caution and irreversibility warning. An agent has enough to decide and invoke correctly, especially since output details are in the schema.

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 100% and all six parameters have detailed descriptions (enums, min/max, production irreversibility). The description adds no parameter-level information beyond the schema, so baseline 3 is appropriate.

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?

Description states a specific verb ('Inutiliza') and resource ('faixa de numeração não utilizada na SEFAZ'), and clarifies the scenario ('quebra de sequência por erro de emissão'). It implicitly distinguishes from siblings like evento_cancelar by targeting unused numbering ranges, not cancellation of issued documents.

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?

Provides when to use: 'quebra de sequência por erro de emissão' and warns it's rare and irreversible, advising user confirmation. However, it does not name explicit alternatives (e.g., evento_cancelar) or state when not to use it, leaving some routing inference to the agent.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the agent knows this writes an external, non-trivial event. The description's type/Justificativa rules are behavioural additions, but it never says the event is registered with SEFAZ irreversibly, cannot be retracted, or what error states to expect.

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?

Two compact sentences with the action front-loaded and the enum semantics immediately after. Minor redundancy with the schema's TipoManifestacao description, but no filler.

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?

With a full output schema and complete parameter documentation, the description only needs to frame the operation, which it does. The missing piece is operative context (irreversibility, environment matching risk already noted in schema), not call-shaping detail.

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 100%, so TipoManifestacao, Chave, TipoAmbiente and Justificativa are already fully documented in the schema. The description only restates the TipoManifestacao enum, adding no syntax or format detail beyond structured data — baseline 3.

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 ("Registra a manifestação do destinatário sobre uma NF-e") and enumerates the four manifestation types, so the agent knows exactly what the call does. It does not explicitly contrast itself with nearby event siblings such as evento_cancelar or cte_desacordo, which keeps it below a 5.

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 gives one concrete usage rule — type 4 requires a Justificativa of 15+ characters — which steers invocation. It offers no guidance on when to choose this event over other event tools, nor preconditions such as the NF-e needing to be addressed to the CNPJ.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the agent knows this is a non-destructive, closed-world write. The description adds no behavior beyond that — it does not mention optional signing/transmission, certificate requirements, or what the generation produces (all carried by the schema instead). Adequate only because annotations lower the bar.

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 single front-loaded sentence that identifies the artifact and its regulatory trigger with no filler or redundancy.

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?

There is no output schema, yet the description never says what is returned (generated file reference, bytes, status) or that output can be signed and transmitted via TED. The regulatory purpose is well stated, but return behavior and the transmit path remain undocumented in prose.

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 100%: Ncm, Gtin, ValorSaida, ValorImportado/PercentualImportado mutual requirement, and the Transmitir/ValidarCodigos semantics are all documented in the schema. The description adds nothing about parameters, so it sits at the baseline 3.

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 states a specific verb ('Gera') and resource ('arquivo FCI') and even expands the acronym (Ficha de Conteúdo de Importação), so the agent knows exactly what artifact is produced and for what domain. No sibling tool covers FCI, so differentiation is implicit, but it does not explicitly contrast with any sibling.

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 supplies the business condition that triggers use ('requerido para produtos com conteúdo importado em operações interestaduais'), which is genuine implied usage guidance. However, it gives no explicit when-to-use/when-not-to-use instruction and names no alternative or prerequisite workflow.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered by structured data. The description adds the useful behavioral fact that required fields vary per receita (documento de origem, referência, valores, campos adicionais), but says nothing about what happens when Uf is omitted, environment-dependent behavior, or caching/latency. Modest value added on top of annotations.

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?

One front-loaded sentence with a parenthetical that enumerates the field groups; zero redundancy and no filler. It could have spent one more clause on the zero-required-parameter behavior without bloat, but nothing in it needs cutting.

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-structure explanation is correctly omitted, and annotations cover safety. But with zero required parameters and an undocumented TipoAmbiente, the agent cannot tell what a bare call returns or which combinations are valid — meaningful gaps for a configuration-lookup tool that an extra sentence would have closed.

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 only 33%: only Receita carries a description ("Opcional: só a regra desta receita."). The description implies Uf scoping and receita scoping but never explains TipoAmbiente at all — a critical GNRE concept (produção vs. homologação) — nor what an omitted Uf returns (all UFs? error?). With under half the parameters documented, the description fails to compensate for the gap.

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?

Specific verb ("Lista") plus a concrete resource: the receitas a UF accepts in GNRE and the required fields per receita, with examples of those field groups. This is clearly distinguishable from gnre_emitir/gnre_consultar, though the description never names a sibling to sharpen the boundary. Purpose is unmistakable without opening the 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?

Usage is only implied: because the tool returns "os campos que cada uma exige", an agent can infer it should be called before gnre_emitir to discover required fields. There is no explicit when-to-use, no when-not-to-use, and no mention of the gnre_consultar/gnre_emitir alternatives. Nothing is misleading, but the routing is left to inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds that the response includes situação, linha digitável, PIX copy-and-paste, and official PDF in base64, and that PDF inclusion is conditional, which is useful behavioral context beyond annotations.

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?

Single sentence that front-loads the action and lookup method, then lists return fields. No filler.

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?

Output schema and annotations cover return shape and safety, but the description does not compensate for undocumented TipoAmbiente, which matters for an open-world query that can target different environments. It also omits error/not-found behavior.

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 50%, and the description only echoes the two lookup keys ('Id ou identificador interno') without adding syntax or constraints. It does not explain TipoAmbiente or IncluirPdf beyond what the schema already states, leaving half the parameters underexplained.

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 ('Consulta') and resource ('GNRE'), identifies the two lookup keys, and lists the returned data. It is clearly a query tool distinct from gnre_emitir, but it does not explicitly name a sibling or state when to choose it.

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 implies the tool is for fetching an existing GNRE by ID or internal identifier, but it does not state when to use it over gnre_emitir or gnre_configuracao, nor does it mention prerequisites. The schema's Id description carries the fallback logic, not the tool description.

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

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

Annotations already declare destructive and open-world, but the description adds the key non-obvious trait: the portal processes asynchronously and returns status 3, with the outcome retrieved via gnre_consultar. It also names the service-enablement prerequisite. It stops short of describing failure modes or what an actual emitted guide commits the taxpayer to, so not a 5.

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?

Four short sentences with no filler, front-loaded with what the tool creates before moving to the async behavior and prerequisites. Slightly dense but every clause carries operative information.

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?

With an output schema present the description needn't explain return values, yet it still clarifies that the immediate return is an async status and the real result lives in gnre_consultar — exactly the gap an agent would hit. Preconditions and the config prerequisite are covered; only error/duplicate handling is left implicit.

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 100%, so documented parameters already carry their own meaning (Receita codes, Periodo enum, DataVencimento ISO format). The description only adds that the emitente is always the token's company and points to gnre_configuracao for UF-specific fields — useful but marginal beyond the rich schema.

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 first sentence states a specific verb and resource ('Gera a GNRE') and immediately scopes it to ICMS for another UF (DIFAL, ICMS-ST de uma NF-e), which distinguishes it from gnre_consultar and gnre_configuracao. An agent can identify this as the creation tool in the gnre_* family without opening the 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?

It gives explicit sequencing: check gnre_configuracao first to learn the UF's required fields, and read the result via gnre_consultar later. It also states a precondition ('Requer serviço GNRE habilitado no cadastro'), so the agent knows when the call will fail.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds the return content (status, timestamp, versão), but with no output schema it does not describe failure behavior, auth requirements, or return format.

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?

Two short sentences, fully front-loaded with the purpose first and the no-parameter fact second. Every phrase earns its place with no filler.

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 no-parameter, annotation-covered health check this is nearly sufficient, and the returned fields are named despite the absence of an output schema. It could go slightly further by disambiguating from the sibling status 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?

There are zero parameters, so the baseline is 4. The description's 'Não recebe parâmetros' correctly and concisely matches the empty schema.

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 (verifica) and resource (a saúde da API BrasilNFe) plus the returned fields. It is clear what the tool does, but it offers no differentiation from the similarly-named sibling sefaz_status, which is also a status-style 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?

No when-to-use or when-not-to-use guidance is given. An agent cannot tell from the description when to call health versus sefaz_status for a status/liveness need, so the choice is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's 'sem emitir nota' restates the no-side-effect nature rather than adding new context (rate limits, permissions, return shape). With annotations doing the heavy lifting, this is adequate but not additive.

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?

Two short sentences, front-loaded with the core action and tax scope; the pricing note is brief and functional. No wasted preamble.

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 need not be explained, but the description asserts a 'lista de produtos' input while the schema exposes generic Count/Capacity fields, leaving the agent without a coherent picture of how to actually call the 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?

Schema description coverage is 0% for two parameters, and the description mentions only 'uma lista de produtos', which does not correspond to the declared 'Count'/'Capacity' parameters at all. The description fails to compensate for the coverage gap and appears inconsistent with the actual inputs.

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 (simula), resource (cálculo de impostos with the named taxes ICMS/PIS/COFINS/IPI/ST) and scope (sobre uma lista de produtos). The phrase 'sem emitir nota' cleanly separates it from the emission siblings like nfe_emitir and nfse_emitir, so an agent can route without opening either 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?

'Útil para precificação' gives a use context and 'sem emitir nota' implies the when-not (use emission tools if you need an actual document). However, no sibling is named and there is no explicit when-to-use vs when-to-use-something-else statement.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds nothing about irreversibility, SEFAZ authorization, rejection handling, or that emission creates a legal fiscal document. For a destructive fiscal write with real-world consequences, this is a meaningful gap.

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?

Two compact sentences, front-loaded with the verb and purpose, no filler. Slight under-specification rather than verbosity, but the structure is efficient.

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 needn't be explained, but a 24-param destructive emission tool needs more than one sentence: required-vs-optional group selection, environment choice, and error/failure behavior are all absent.

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 24 parameters and only 42% schema description coverage, the description should compensate — it says nothing about any parameter. Key conditional logic (modalidade selecting Rodoviario/Aereo/Aquaviario/Ferroviario, tipoAmbiente=2 for tests) lives only in the schema.

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 ('Emite MDF-e') and expands the acronym, plus explains the domain purpose (grouping multiple CT-e/NF-e into a single transport). It doesn't explicitly name sibling tools like cte_emitir or nfe_emitir to distinguish, so it falls short of a 5.

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?

Adds a usage condition ('Obrigatório para transportadores com vários DFs no mesmo veículo'), which implies when to use it. But there is no when-not guidance, no prerequisite/authorization notes, and no routing to alternatives such as cte_emitir for a single document.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds regulatory consequence (new manifests blocked by SEFAZ without closure), which is real context beyond the annotations, though it does not itself restate irreversibility.

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?

Three short sentences, each earning its place: what it does, when it is required, and the consequence of skipping it. The purpose is front-loaded.

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?

With an output schema present and rich annotations, the description need not explain returns or safety. It covers purpose, obligation, and consequence adequately, though it says nothing about error/duplicate-closure behavior for an operation the schema calls definitive.

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% and the enum/default for tipoAmbiente plus the optional protocolo fallback are all documented in the schema itself. The description adds no parameter-level syntax or format detail, so the baseline of 3 applies.

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 ('Encerra um MDF-e já autorizado') and pins the domain event type ('evento tipo 3'), which separates it from mdfe_emitir and evento_cancelar without opening either 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: it is mandatory at the end of every transport, and omitting it can cause SEFAZ to block new MDF-e. It stops short of naming a sibling alternative or an explicit when-not-to-use case.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds critical context beyond them: synchronous 5-30s operation, real transmission to SEFAZ ('TRANSMITE DE VERDADE'), the OAuth requirement for confirmacaoUsuario=true, and the return payload (chave, protocolo, XML/DANFE base64). This is genuinely useful behavioral disclosure.

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 action and model distinction, then the return payload, then the safety gate. Every sentence carries actionable information; the emphasis on 'TRANSMITE DE VERDADE' is warranted for an irreversible operation.

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?

Despite 36 parameters and an output schema that already documents returns, the description covers the essential decision points (model choice, environment, confirmation precondition) that an agent must resolve before calling an irreversible emission tool. Nothing critical is missing.

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 78%, so the baseline is a 3, but the description adds real meaning for the highest-stakes parameters: modeloDocumento, tipoAmbiente, and the confirmation gate. It doesn't attempt to explain the many tax/fiscal parameters, but the high-coverage schema carries those.

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 ('Emite uma NF-e (modelo 55) ou NFC-e (modelo 65) na SEFAZ') and immediately distinguishes the two document models. An agent can tell this apart from siblings like nfe_previsualizar and nfe_emitir_complementar without opening the 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?

Explicitly maps modeloDocumento=55 vs 65 to their use cases (B2B vs consumidor final), recommends tipoAmbiente=2 for tests, and states the precondition that the user must have approved the preview. Names the alternative (nfe_previsualizar) and the exact condition that gates this call.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the agent knows this is an irreversible external fiscal transmission. The description adds the finalidade=2 reference behavior, but says nothing about numbering/series consumption, authorization prerequisites per environment, or the consequences of a rejected emission.

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?

Two short sentences with zero waste; the reference requirement is front-loaded right after the purpose statement.

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 16-parameter, deeply nested fiscal emission tool with no required parameters declared, the description does not explain the two emission paths (inform Produtos/Imposto versus ImpostoComplementar), the TipoComplemento semantics, or what is mandatory in practice. An output schema exists, so return values need not be covered, but the input-side guidance is far too thin.

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 only 56% and several top-level parameters (Lote, Serie, Numero, CFOP, Observacao, Transporte fields) have no meaningful description. The description does add real meaning for NFReferencia (the original note's access key), but ignores key structural choices such as TipoComplemento and Produtos vs ImpostoComplementar.

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 (emit a complementary NF-e) and the distinguishing condition (referencing an already authorized NF-e, finalidade=2). This separates it from nfe_emitir without naming the sibling, so it is clear but not fully differentiated.

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 context for when the tool applies (complementing values, taxes or items) and a prerequisite (the original note must already be authorized). It does not state when NOT to use it, e.g. devolução via ChaveAcessoReferenciada or a normal emission via nfe_emitir.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the write/external-call profile is covered. The description usefully adds that the document is submitted to SEFAZ for authorization, confirming the external authority, but says nothing about irreversibility, whether homologation is safe, or what happens after authorization.

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 single front-loaded sentence with no filler; the verb and destination come first. It is efficiently structured though extremely terse given the tool's complexity.

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 12-parameter, destructive, open-world emission tool, the description omits critical context: that it is an irreversible fiscal transmission, the Production vs Homologation implications, and any preconditions. An output schema exists so return values need not be explained, but the operational stakes are left undisclosed.

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 100% with 12 parameters, nested objects, and 3 enums, so the schema fully documents field meaning (modeloDocumento, tipoAmbiente, produtos requirements, etc.). The description adds no parameter-level guidance beyond what the schema already provides, so the baseline 3 applies.

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 (Envia/sends), a specific resource (NF-EnerCom, with the Portuguese expansion of the acronym), and the target destination (SEFAZ authorization). This separates it from peers like nfenercom_gerar_arquivo, though it never names that sibling to sharpen the distinction.

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?

No indication of when to use this tool versus nfenercom_gerar_arquivo, nfe_emitir, or nfe_emitir_complementar, and no prerequisites stated (e.g. that it actually transmits for authorization rather than pre-visualizing). The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=false with destructiveHint=false, so the agent knows this writes something without being destructive. The description adds that it is a prerequisite step for emission, but says nothing about whether the generated file is persisted, whether calls are idempotent, or what happens on repeated generation for the same period.

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?

Two short sentences, front-loaded with the action and resource, with the dependency stated last. Zero filler.

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 tool with a deeply nested notas payload and a two-mode tipoGeracao switch, the description never mentions the two generation modes or the notes-vs-period distinction. With no output schema and no explanation of what the generated file is or where it goes, an agent lacks enough context to call this confidently beyond the simplest 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?

Schema description coverage is 100%, so the two required parameters (tipoGeracao, tipoAmbiente) and the nested notas payload are fully documented in the schema itself. The description contributes no additional parameter semantics, which is the expected baseline when the schema does the heavy lifting.

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 ('Gera') and resource ('arquivo da Nota Fiscal de Energia (NF-EnerCom)'), and explicitly names the sibling it precedes (nfenercom_emitir), which helps distinguish it. The term 'arquivo' remains somewhat abstract (file content vs. stored artifact) but the intent is clear.

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?

'Pré-requisito para nfenercom_emitir' gives an implied ordering constraint, which is useful context for sequencing. However, there is no explicit when-to-use guidance, no statement of when NOT to use it, and no mention of the arquivo_baixar* siblings that handle the resulting file.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real behaviour: nothing is transmitted to SEFAZ, output appears in a panel next to the conversation and must be refreshed per edit, and validation problems surface in 'Error'/'Avisos'. It does not mention the 'tarja' watermark behaviour except indirectly via the schema parameter.

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?

Purpose and the no-SEFAZ guarantee are front-loaded, then the calling convention, then the iteration workflow, then error handling. Every sentence carries information, though the panel/refresh instruction is wordier than strictly necessary.

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 NF-e preview the description is essentially complete, and the output schema covers return values. But for a tool whose schema accepts CT-e, MDF-e, NFS-e and DC-e objects, the description never tells the agent those preview paths exist or how to pick between them, leaving a real gap in a multi-model 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?

Schema coverage is 89%, so the baseline is 3, and the description adds useful cross-tool meaning ('notaFiscal' uses the same format as nfe_emitir) plus a recommended TipoEnvio/TipoArquivo combination. It says nothing about the cte, dce, mdfe and nfse document parameters, which are four of the nine top-level inputs.

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 (gera o DANFE em PDF + XML) and immediately distinguishes it from real emission with 'sem enviar para a SEFAZ'. However it frames the tool purely as a DANFE/NF-e preview even though the schema also exposes cte, dce, mdfe and nfse preview paths, so the stated scope is narrower than the actual one.

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 operating context: use for preview without transmitting to SEFAZ, send the full note in 'notaFiscal' with TipoEnvio=1 and TipoArquivo=2, and re-invoke on every requested change so the side panel stays current. The counterpart call for actual emission (nfe_emitir) is only referenced as a format reference, never named as the alternative when the user wants a real transmission.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the qualifier that the NFS-e must have already been sent, which is modest but genuine context beyond the annotations.

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 single front-loaded sentence with no filler, and the resource is stated before the qualifying clause. It is tight, though it wastes its one clause on parameters that do not match the schema.

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 need not be explained, and the one-parameter-plus-optional list is small. Still, the description omits the actual parameter semantics (Rps selector, lote code) and gives no usage routing, leaving the agent to reconcile a mismatch between prose and schema.

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 100%, which normally sets a baseline of 3. However, the description cites lookup keys ('por número, série e ambiente') that do not exist among the actual parameters (Rps, codLote), so it actively misdescribes the input rather than reinforcing it.

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 (consulta) and resource (NFS-e) plus scope ('já enviada'), which separates it from the write-oriented siblings nfse_emitir and nota_listar. The purpose is unmistakable, though it never names a sibling or alternative by name.

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 no guidance on when to use this versus nfse_emitir, nota_listar, or any other read tool in the sibling list. An agent must infer usage entirely from the one-line purpose statement.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the agent knows this is a real, externally-visible write. The description adds the municipal-heterogeneity caveat and the portal-vs-city-hall routing, but says nothing about environment risk (production vs homologação lives only in the schema), idempotency, or duplicate-emission behavior.

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?

Three short sentences, purpose front-loaded, followed by the municipality caution and the routing note. No filler; each sentence contributes.

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 highly complex fiscal-emission tool with a deep schema, an output schema (so returns need no explanation) and strong annotations, the description is on the thin side. It covers the municipality prerequisite but omits things like company/certificate prerequisites, duplicate-NFS-e risk, and what happens on partial lote failure.

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 67% and the description adds no parameter-level detail at all for Lote, nFSInfo or TipoAmbiente. With the schema already carrying rich nested documentation, the schema does the heavy lifting, so the baseline 3 is appropriate rather than a lower score.

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 ('Emite NFS-e - Nota Fiscal de Serviços Eletrônica'), which is clearly the municipal service invoice and distinguishable from the goods-invoice siblings like nfe_emitir and cte_emitir. It also names the two emission channels (Portal Nacional vs prefeitura), adding scope beyond the name.

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 a real prerequisite ('confira o município emissor antes') and a routing condition based on the company's cadastro, which is useful context. However, it names no alternatives (e.g., nfse_consultar to verify, nfe_emitir for goods) and gives no when-not guidance, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the document-type coverage and date-range scoping, which is useful, but it also advertises filters ('chave, número, status') that have no matching schema parameter, which is mildly misleading about what can actually be filtered.

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?

Two tight sentences with the primary purpose front-loaded and the supported scope right behind it. No waste.

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 need not be described, and the read-only annotations carry the safety profile. The one gap is the mismatch between the advertised filters and the actual parameters, but for a simple list tool the definition is otherwise sufficient.

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 100% and the schema documents every parameter including enum meanings and defaults, so the baseline is 3. The description adds no syntax or format detail beyond what the schema already provides.

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 (Lista) plus the exact resources (NF-e/NFC-e/NFS-e) and scope (emitted or received within a date range). This clearly separates it from the many emit/emitir siblings, though it never names a specific alternative 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?

Usage is implied by the stated scope (date-ranged listing with filters), but there is no explicit when-to-use, when-not-to-use, or pointing to a sibling for narrowing results. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: default page size of 20, max 50, offset-based continuation, and a TotalGeral indicator for detecting truncation. It does not discuss empty-result or error semantics.

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 purpose, then the anti-duplicate guidance, then a clearly labeled PAGINACAO block. Every sentence carries actionable information with no filler.

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 format needn't be spelled out, yet the description still surfaces TotalGeral as the truncation signal, which is exactly what an agent needs to page correctly. The unexplained TipoBusca parameter is the one remaining gap for a 4-parameter 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?

Schema description coverage is 0%, so the description must carry the parameter burden, and it explains Termo's accepted formats (codigo/NCM 8 digits/GTIN 8-14 digits/partial description), Limite's default and ceiling, and Offset's purpose. TipoBusca is never explained, leaving one of four parameters undocumented in both schema and description.

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 (Pesquisa) and resource (produto no cadastro da empresa logada), plus the accepted search keys (codigo interno, NCM, GTIN/EAN, descricao parcial). This clearly separates it from the sibling write tools produto_criar and produto_editar.

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?

Explicitly says to run this BEFORE creating new products to avoid duplicates, which is the exact decision point against produto_criar. It also gives concrete continuation guidance: if TotalGeral exceeds the returned matches, request more pages rather than inventing/grouping results.

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

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

Annotations cover only safety hints (readOnlyHint=false, destructiveHint=false). The description adds real behavioral context beyond that: duplicate rejection by Codigo, NCM zero-pad normalization for 7/8 digits, and EAN/GTIN check-digit validation. It omits auth/permission requirements and failure modes for other fields.

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?

Three compact sentences, no filler, with the creation statement and the most error-prone validation rules front-loaded.

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 need not be explained, and the validation rules cover the trickiest inputs. However, for an 11-parameter create tool with 0% schema documentation, the majority of fields remain unexplained in both schema and description.

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 0% across 11 parameters, so the description carries the full burden. It clarifies only three fields (Codigo, Ncm, Ean) and says nothing about Cest, FatorConversao, QuantidadeEstoque, ValorUnitarioVenda, or the unidade-medida fields.

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 ('Cadastra') and resource ('novo Produto') plus scope ('na empresa logada'), which clearly separates it from produto_editar and produto_consultar. It stops short of naming those siblings explicitly, so it isn't a 5.

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 no explicit guidance on when to use this over produto_editar or produto_consultar, nor any stated prerequisites. The creation intent is only implied by the verb and the duplicate-check note.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description explains WHY it is destructive ('omitted fields are zeroed') and adds ownership/auth semantics (UserCreate check, IdEmpresa must be the logged company or 0). That is substantive context beyond the structured annotations.

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 action and the required Id, then the critical warning, then ownership rules. Dense but every sentence (zeroing risk, consult-first, ownership) earns its place; slightly run-on but well prioritized.

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 need not be described, and the description covers the key gotchas for a destructive update (zeroing, ownership, read-before-write). Minor gap: it references an IdEmpresa not present in the input schema, but overall it is complete enough to call 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 description coverage is 0% across 11 parameters, so the schema documents nothing. The description conveys the critical global semantic (send the full payload; omitted fields reset) and that Id is required, but gives no meaning for individual fields (Ean, Ncm, Cest, FatorConversao, etc.), so it only partially compensates for the coverage gap.

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 (Atualiza) and resource (Produto existente), and names the sibling it complements (produto_consultar), so it is clearly distinguishable from produto_criar and produto_consultar without opening any 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?

Explicitly prescribes the workflow: call produto_consultar first to fetch current data, then resend the whole payload plus changes. It also names the selection condition (an existing product the user owns) and the company constraint, leaving little to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds usage timing but does not disclose additional operational behavior such as authentication scope, rate limits, or how the UF/ambiente are resolved.

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 two sentences, front-loaded with the core purpose and then the usage condition. Every sentence earns its place with no redundant repetition of schema or annotation data.

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 one-parameter read-only status tool, the description plus annotations and output schema provide enough to select and invoke it correctly. The only minor gap is the mention of UF and ambiente, which are not represented in the input schema and could briefly confuse an agent about required inputs.

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 100%, and the single ModeloDocumento enum is fully documented in the schema. The description adds no further parameter detail and refers to "UF e ambiente" even though those are not input properties, so the baseline of 3 is appropriate.

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 gives a specific verb and resource: "Consulta o status do serviço de autorização da SEFAZ". It also states the scope (UF and ambiente), making clear how this differs from a generic health check or other status tools.

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 explicitly recommends usage before batch emission and when instability is suspected: "Use antes de uma emissão em lote ou quando suspeitar de instabilidade." This is clear context, though it does not name when not to use it or point to an alternative sibling tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: default page size 20, hard max 50, presence of TotalGeral in the response, and an explicit anti-hallucination instruction to page rather than invent or aggregate.

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 purpose and filters, then pagination guidance, all in a few dense sentences with no filler. Every clause carries operational information.

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 read-only filtered-list tool with an output schema, the description covers everything an agent needs to call it correctly: filters, page sizing, and how to interpret TotalGeral for continued paging. No meaningful gap remains.

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 compensates fully: it defines Tipo's enum-like values (1=NFe, 2=NFCe, 3=Energia/Comunicacao) that the schema lacks, explains CFOP and Termo as filters, and gives Limite's default (20) and max (50) plus Offset's role.

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?

Specific verb+resource: it lists the company's tax rules and enumerates the domains covered (CFOP, CST, ICMS/PIS/COFINS/IPI/IBS/CBS), cleanly separating it from the sibling mutation tools tributacao_criar and tributacao_editar.

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 an explicit when-to-use ('Use antes de criar nota fiscal pra LLM saber quais tributos aplicar') plus filter conditions (Tipo/CFOP/termo). It does not name the sibling alternatives for maintaining rules, so it stops short of 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/safe-mutation profile is covered. The description adds the useful constraint that CstIbsCbs is mandatory under the tax reform, but says nothing about permissions, validation failure modes, or uniqueness of a rule. Note the claimed obligation sits oddly with the schema, where CstIbsCbs is nullable and not in the required list.

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?

Three compact sentences with the purpose front-loaded and zero padding. It is efficient, though the payoff per sentence is limited given how much parameter detail is omitted.

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 23-parameter mutation tool with 0% schema description coverage, the description covers only one enum and one mandatory-field note. An output schema exists, so return values need not be explained, but the input contract is far too thin for an agent to populate the tax fields 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 description coverage is 0% across 23 parameters, so the schema carries essentially no meaning and the description must compensate. It only explains the Tipo enum (1=NFe, 2=NFCe, 3=Energia/Comunicacao) and flags CstIbsCbs as required, leaving roughly 20 tax fields (CstIcms, AliqCbs, AutoAliq, EnquadramentoIpi, etc.) completely unexplained.

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 states a specific verb+resource ('Cadastra uma nova regra de tributacao') and scopes the entity (CFOP + CSTs + aliquotas). It is clearly distinguishable from tributacao_consultar, though it never explicitly contrasts itself with tributacao_editar, the closest sibling.