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 cover the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false). The description adds genuinely useful behavior beyond that: the return is base64-encoded content, and the file type is driven by the TipoArquivo choice. That disclosure matters because there is no output schema.

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 filler, with the scoping keys and return format front-loaded. Nothing could be removed without losing 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 no output schema, naming the base64 return is the key missing piece and it is present. The remaining gap is minor: it does not say what happens if the event does not exist or whether TipoArquivo has a default, but the schema's enum values (1=XML, 2=PDF CC-e) cover the parameter side well.

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 baseline is 3. The description adds little beyond the schema, and in fact is slightly looser: it says 'número sequencial' where the parameter is NuProtocolo (event protocol number), a mild terminology mismatch that could confuse an agent.

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 ('Baixa o arquivo de um evento') and enumerates the event types covered (CC-e, cancelamento, manifestação, encerramento), which helps separate it from the generic arquivo_baixar. It does not explicitly name the sibling tools it differs from, so the differentiation is inferable rather than stated.

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 scoping phrase 'por chave de acesso + número sequencial', which tells an agent this is the per-event download path. However, it never states when to choose this over arquivo_baixar or arquivo_baixar_periodo, nor any prerequisites (e.g. event must already exist on the NF).

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 declare destructiveHint=true and openWorldHint=true, so the agent knows this is an outward-facing, mutating call. The description usefully adds the auth/config prerequisites (enabled service, A1/A3 certificate), but it does not warn that TipoAmbiente=1 emits a real, irreversible fiscal document, nor say anything about what is created or returned. Adds some value beyond annotations, but leaves the biggest behavioral risk implicit.

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 filler, and the core action is front-loaded before the prerequisites. Every sentence 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?

Because an output schema exists, the description need not explain return values, and the annotations cover the safety profile. But for a 21-parameter, deeply nested, fiscally consequential emission tool, the description is thin: it omits any orientation to the payload structure or the production/homologation distinction that the schema encodes. Adequate minimum, clear gaps remain.

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 43%, below the 50% threshold, so the description is expected to compensate for undocumented parameters — yet it contains no parameter-level information at all. With 21 parameters and 8 required, the description gives no help on the structural payload (Carga, Modal, Servico, Tomador, etc.) that the schema leaves partly 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?

States a specific verb (Emite) and resource (CT-e, with the acronym spelled out in Portuguese), so an agent knows exactly what operation this is. It does not, however, differentiate itself from sibling emission tools such as dce_emitir, mdfe_emitir, or nfe_emitir beyond the document type in 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?

The description gives real prerequisites — CT-e service must be enabled on the company registration and an A1 or A3 digital certificate must be configured — which is useful context for deciding if the call can succeed. It offers no when-to-use versus when-to-use-an-alternative guidance and no exclusions.

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 safety profile is covered structurally. The description adds nothing behavioral – it omits that this transmits an irreversible fiscal event to SEFAZ, that repeated manifestations are limited, or any timing constraint, which matters greatly for a destructive, open-world write.

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?

Only two sentences and front-loaded with the core action, which is good. But the second sentence is not merely redundant – it is incorrect relative to the schema, so it does not earn 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?

An output schema exists, so return values need no explanation. Still, for a destructive fiscal mutation with three required parameters and a legal-deadline semantics, the description omits environment-matching rationale, irreversibility, and correct enum documentation – the essentials for calling it 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 100%, so the baseline would be 3, but the description actively misleads: it references "TipoEvento" with values 0=ciência, 1=confirmação, 2=desconhecimento, 3=não realizada, while the actual schema parameter is "TipoManifestacao" with a different numbering (1=Confirmação, 2=Ciência, 3=Desconhecimento, 4=Não Realizada). An agent following the description could send a wrong enum value.

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"), so an agent knows the core action. However, it then describes a parameter named "TipoEvento" with values 0-3 that does not exist in the schema, which muddies rather than sharpens the stated purpose.

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 guidance on when to manifest versus using siblings such as evento_cancelar or evento_carta_correcao, nor any mention of the legal deadline or prerequisites (e.g., the NF-e must exist and the environment must match). The agent must infer usage entirely.

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, 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, readOnlyHint=false, openWorldHint=true, so the write/irreversibility profile is covered structurally. The description adds the grouping semantics and the legal-obligation context, but says nothing about SEFAZ submission, authorization response, numbering, or what happens on rejection — useful additions beyond annotations are thin.

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 zero waste; the purpose and the usage condition are front-loaded. Nothing is padded or restated from the title.

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 heavy 24-parameter emission tool with nested modal-specific branches, an output schema, and a side-effecting SEFAZ call, a two-sentence description is inadequate. An agent gets no help on which modal object to supply, required field interplay, or what the emission result looks like beyond 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?

With 24 parameters and only 42% schema description coverage, the description carries a real compensation burden, and it mentions no parameters at all (not modalidade, ufCarregamento, peso, Rodoviario, etc.). The schema does describe many nested fields, but the modal-dependent requirements (Rodoviario when modalidade=1) remain undisclosed in the 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 (Emite) and resource (MDF-e), and clarifies the key semantic that it groups multiple CT-e/NF-e into one transport, which distinguishes it from cte_emitir and nfe_emitir. However, it never names those siblings or explicitly contrasts its role with them.

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 sentence 'Obrigatório para transportadores com vários DFs no mesmo veículo' gives an implied usage condition (multiple fiscal documents, one vehicle). There is no explicit when-to-use vs. alternative routing, no mention of prerequisites, and no exclusions, so guidance is only inferred.

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 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 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.

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 guidance on when to create a rule versus editing one with tributacao_editar, nor any prerequisite or context condition. Usage is only implied by the verb 'Cadastra'.

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?

Adds behavior beyond the annotations: the payload is a full replace where omitted fields are zeroed, and ownership is validated via IdEmpresa. These are exactly the traits an agent needs since destructiveHint=true alone does not explain the zeroing risk, and the annotation set is consistent with the described overwrite 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-loads the purpose, then the critical zeroing warning, then the recommended workflow. Every sentence earns its place, though the Id/payload/workflow instructions could be tightened 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?

For a destructive 23-parameter overwrite with an output schema present, the description covers the essential risks (zeroing, ownership check, prior consult) without needing to explain return values. It could say more about what happens on validation/ownership failure, but it is sufficient 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?

With 23 parameters at 0% schema description coverage, the schema explains almost nothing, so the description must carry the burden. It clarifies the Id input and the all-fields-required nature of the payload, but note 'Id obrigatorio' conflicts slightly with the schema where Id is nullable and not in the required list; per-field meanings remain 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 specific verb and resource ('Atualiza uma regra de tributacao existente'), making the update semantics clear and distinguishing it implicitly from tributacao_criar. It does not explicitly name a sibling to route against, but 'existente' plus the consult-first workflow leaves little ambiguity.

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 concrete prerequisite workflow: call tributacao_consultar first to fetch current data, then resend everything with modifications. It names the alternative sibling and the condition for using it, though it never states when NOT to use this tool (e.g., use tributacao_criar for new rules).

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