fiscal

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

Annotations already declare readOnlyHint and idempotentHint, so the agent knows the tool is safe and idempotent. The description adds value by specifying the return format (base64) and the file types. It does not contradict 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?

The description is two sentences long, directly stating the purpose and output format. It is front-loaded with the key action and resource. Every sentence is necessary and 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 five parameters, no required ones, and no output schema, the description is insufficient. It does not explain how to specify the access key (which of the two key parameters to use), the role of Base64Logo, or the behavior when parameters are omitted. The agent lacks guidance to invoke the tool 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 low (40%), and the tool description does not adequately compensate. It mentions file types (XML/PDF) which maps to FileType, but leaves Chaves, ChaveNF, and Base64Logo unexplained. The user must infer that ChaveNF is a single key, but the array parameter Chaves is ambiguous. No guidance on parameter combinations.

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 clearly states the verb 'Baixa' (downloads) and specifies the resource as XML or PDF/DANFE of a NF-e/NFC-e/NFS-e by access key. It distinguishes from sibling tools like 'arquivo_baixar_evento' and 'arquivo_baixar_periodo' by emphasizing the input method (access key).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when the user has an access key, but it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. No guidance on when not to use it or which sibling tool to choose.

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 provide readOnlyHint and idempotentHint, so the tool's safety profile is clear. The description adds that the output is base64-encoded and lists event types, but does not disclose additional traits like size limits or error responses. No contradiction with 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?

Two sentences with no superfluous words. Clearly states action, input, and output. Efficiently 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?

For a simple download tool with no output schema, the description covers the return format (base64) and event types. It lacks details on error handling or constraints but is adequate for the complexity. No missing critical information.

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?

All three parameters are fully described in the schema (100% coverage), so the description adds minimal value. It loosely maps 'chave de acesso + número sequencial' to ChaveNF and NuProtocolo, but this is already implied. No new semantic depth beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool downloads event files (CC-e, cancellation, etc.) by access key and sequential number, returning base64. However, it uses 'número sequencial' while schema calls it 'NuProtocolo' (protocol number), causing slight ambiguity. The name and description sufficiently distinguish from siblings like 'arquivo_baixar' and 'arquivo_baixar_periodo'.

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 explicit guidance on when to use this tool versus alternatives (e.g., 'arquivo_baixar' for general files). The description implies it's for event-specific downloads but doesn't state exclusions or provide comparative context.

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 give readOnlyHint=true, and the description confirms a read operation ('exporta'). It adds value by disclosing the output format (ZIP base64) and the included file types (XML/PDF). No contradictions with 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?

Two sentences, no fluff. First sentence states the core action and output; second adds context. 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?

Given 11 parameters and an output schema, the description is adequate but not comprehensive. It covers high-level purpose and usage context but does not explain parameter relationships (e.g., date range required) or provide examples. The output schema exists, reducing the need to describe return values.

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 tool description does not add new meaning beyond what parameters already provide; it only restates the high-level concept of period and file types.

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 clearly states the verb (Exporta), the resource (múltiplos arquivos XML/PDF de um período), and the output format (único ZIP base64). It distinguishes from siblings by specifying batch download over a period, as opposed to single file or event downloads.

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 mentions use cases (backup, accounting, audit) but does not explicitly contrast with sibling tools like 'arquivo_baixar' for single files or 'arquivo_baixar_evento'. The context is implied but lacks explicit when-to-use and when-not-to-use guidance.

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 significant context beyond annotations: notes that missing IE does not mean CNPJ is inactive, describes fallback to Receita Federal for CNPJ, and instructs to read the `mensagem` field. No contradiction with 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 purpose and includes essential warnings and fallback info, but slightly verbose due to multiple caveats. Each sentence adds value.

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?

Covers edge cases (UF unavailability, service providers), fallback mechanism, and expected behavior given the output schema. Adequate for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% (only `uf` described). Description mentions the combination of CPF/CNPJ/IE and UF but does not detail parameter format or requiredness, only partially compensating for the missing schema descriptions.

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?

Clearly states it consults the state registration (IE) for a taxpayer via CNPJ/CPF/IE + UF, distinguishing from sibling `cliente_consultar` which is for basic cadastral data.

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 warns that many UFs do not offer the service (e.g., RJ) and that service providers typically lack IE. Advises using `cliente_consultar` if only checking active status, and describes fallback behavior for CNPJ.

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

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

Disclosures beyond annotations: explains search order (local then BrasilAPI), that CPF has no public base, and pagination details (return includes TotalGeral). Annotations already indicate read-only, open-world, idempotent; description adds valuable context without contradiction.

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?

Description is informative but somewhat lengthy; includes essential details and front-loads the main purpose. Slightly verbose but maintains clarity.

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?

Covers key aspects: search logic, pagination, and tool distinction. Output schema exists so return values are not needed. Sufficient for an AI agent to use correctly, though could explicitly mention that local search may work for CPF.

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?

Input schema has 7 parameters with 0% description coverage. Description adds meaning for 'Termo' (search term), 'Limite' (default 10, max 50), and 'Offset', but omits 'Fontes', 'TipoBusca', 'IncluirInativas', and 'Uf'. Partial coverage; could be more thorough.

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 clearly states it performs a unified search for client/supplier, first checking local database then BrasilAPI for CNPJ. It distinguishes from sibling 'cadastro_consultar' which only retrieves IE, making the purpose specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises when to use (to check CNPJ status and get data), when not to confuse with cadastro_consultar, and provides pagination instructions (default limit 10, max 50, use offset). Also recommends using before asking user for CNPJ.

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

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

Annotations are minimal (only title), so description carries behavioral burden. It mentions error behavior for duplicates but does not disclose authorization needs, side effects, or other safety traits. Adequate 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?

Two sentences in Portuguese, front-loaded with purpose, no wasted words. Efficient and clear.

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 10 parameters and existing output schema, description explains core use case and duplicate handling but lacks explanation of return values and many parameters. Adequate for a focused tool but not fully comprehensive.

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 description must compensate. It mentions CpfCnpj, Nome, Endereco, Ie but omits many parameters like Im, Email, Telefone, IndicadorIe, ConsumidorFinal. Coverage is incomplete.

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 clearly states the tool registers a new client (Cadastra um novo Cliente) and lists typical fields (CNPJ/CPF, razao social, endereco, IE). It distinguishes from siblings by explicitly referencing cliente_consultar and cliente_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 states when to use: after cliente_consultar when user confirms, and when not (if duplicate CPF/CNPJ, use cliente_editar). Provides clear decision guidance.

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 idempotentHint annotation, the description reveals full-replacement behavior, ownership validation (UserCreate and IdEmpresa), and the necessity of sending complete payload, adding significant context for the agent.

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 concise with two main sentences and a warning, front-loading the purpose. It could be slightly more structured but is efficient with no wasted words.

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 complexity (10 parameters, no param descriptions), the description covers critical behavioral aspects (full replacement, ownership, partial edit workaround). With an output schema present, return values need no explanation, making it reasonably complete.

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?

Despite 0% schema coverage, the description explains that Id is required (though schema marks it optional) and emphasizes complete payload. However, it does not detail other parameters nor compensate fully for the lack of schema descriptions, and the statement about Id being required contradicts 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?

The description clearly states 'Atualiza dados de um Cliente existente no cadastro' with specific verb (atualiza) and resource (Cliente existente), distinguishing it from sibling tools like cliente_criar and cliente_consultar.

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 warns 'envie o payload COMPLETO - campos omitidos sao zerados, nao preservados' and advises 'Para edicao parcial, faca cliente_consultar primeiro e mande os dados existentes mais o que muda', providing clear when-to-use and when-not-to-use guidance.

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?

The description indicates a write operation ('Registra') and the openWorldHint annotation suggests side effects, but it does not disclose additional behavioral traits such as idempotency, reversibility, or consequences of registration. No contradiction with annotations, but it adds little beyond the annotation.

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 a single, concise sentence with no redundant information. It efficiently conveys the core purpose and a key constraint, maintaining excellent structure and brevity.

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?

While the description includes an important deadline and event type, it omits details about the output, any prerequisites, or post-registration effects. Given that an output schema exists, the description could be more complete but is not severely lacking for a write operation with openWorldHint.

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?

The description provides no explanation for any of the parameters (Chave, Observacao, TipoAmbiente, NumeroSequencial). Since the schema has 50% coverage (Chave and Observacao lack descriptions), the description could have filled this gap but does not, leaving the meaning of key parameters ambiguous.

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 clearly states the tool's function: registering a recipient's disagreement with a received CT-e, specifying the event type (type 4) and the deadline (45 days from issuance). This provides a precise and unambiguous purpose, distinct from sibling tools like evento_manifestar or evento_cancelar.

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 a temporal constraint (deadline) but does not explicitly contrast this tool with alternatives or state when to prefer it over other event tools. It lacks explicit when-to-use or when-not-to-use guidance, though the deadline implies a usage boundary.

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?

The description adds prerequisites (CT-e service enabled, digital certificate A1/A3), but it does not disclose behavioral traits of emitting a legal fiscal document, such as irreversibility in production, validation failure risks, or potential side effects. Annotations provide only openWorldHint and no safety profile, so the description carries the transparency burden and falls short.

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, appropriately sized and front-loaded. The first sentence states the core purpose, and the second adds essential prerequisites. No fluff 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?

Given the complexity (21 parameters, nested objects, fiscal emission), the description is too thin. It lacks an overview of the CT-e process, potential errors, or warnings about production emissions. While an output schema exists, the description does not provide enough context to confidently invoke this tool among many sibling emit tools.

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?

The description provides no information about parameters. Schema coverage is only 43%, leaving many parameters without descriptions, and the description does not compensate for these gaps. For example, it does not mention that ModeloDocumento can be 57 or 67, or that TipoAmbiente distinguishes production vs homologação.

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 clearly states the tool emits CT-e (Conhecimento de Transporte Eletrônico) with the verb 'Emite' and the specific resource 'CT-e', expanded with the full name. This distinguishes it from sibling emit tools like nfe_emitir or mdfe_emitir, which target different document types.

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: the tool is for CT-e emission, which is evident from the name and description. However, it does not explicitly compare to alternatives or state when not to use it. It does mention prerequisites (service enabled, certificate), but these are requirements rather than usage guidance.

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?

The description adds only a prerequisite beyond the annotations. With minimal annotations (openWorldHint), the description does not disclose authorization needs, side effects, or other behavioral traits.

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 concise at two sentences, front-loading the purpose and adding a prerequisite. No redundant information is present.

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 high complexity (20 parameters, nested objects), the description is too brief. It does not cover validation rules, parameter interactions, or other nuances needed for correct invocation, though an output schema exists.

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?

The input schema has 75% parameter description coverage, so the schema itself explains most parameters. The tool description adds no extra parameter semantics, maintaining the 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 clearly states the tool emits a DC-e (Declaração de Conteúdo Eletrônica) for transporting non-tax items by individuals or MEIs. This differentiates it from other emitir siblings like nfe_emitir or cte_emitir.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for usage (non-tax items by individuals/MEI) and mentions a prerequisite (service enabled). However, it does not explicitly state when not to use it or name alternative 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?

The destructive effect is explicit ('Cancela um documento fiscal') and consistent with the destructiveHint annotation. The description adds useful behavioral details such as automatic protocol lookup for notes emitted within BrasilNFe and the need to supply the original protocol when issued externally. No contradiction with 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?

The description is short and front-loaded: purpose first, followed by key usage rules. Each sentence adds distinct information; there is 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?

For a tool with 10 parameters, conditional branches, and an output schema, the description plus parameter docs cover required combinations, defaults, external-system protocol handling, NFS-e specifics, and the SEFAZ deadline. An agent has enough context to invoke cancellation 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?

All 10 parameters have rich semantic descriptions beyond the schema types, including conditional requirements (ChaveNF vs NumeroNFSe), environment matching (TipoAmbiente), justification rules with examples, enum meanings for CodCancelamentoNFSe, and DC-e-specific CPF/CNPJ behavior. This significantly helps the agent choose correct values.

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 starts with a specific verb and resource: 'Cancela um documento fiscal autorizado', and explicitly enumerates the document types covered (NF-e, NFC-e, NFS-e, CT-e, MDF-e, DC-e). This clearly differentiates the tool from siblings focused on issuance, consultation, or other events.

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 direct operational instructions: provide the 44-digit key and justification, switch to TipoDocumento=1 + NumeroNFSe for NFS-e, and notes the SEFAZ 24-hour deadline. It does not explicitly contrast with sibling cancellation/event tools, but the instructions are sufficient for the main use cases.

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 only include openWorldHint=true, so the description carries the burden of behavioral disclosure. It clearly states this is a mutation (sending an event), lists explicit restrictions on what can be corrected, and notes the per-document limit. This adds meaningful behavioral context beyond the minimal annotations, though it doesn't describe side effects like returned protocols.

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, front-loaded with the main purpose, then key restrictions and the limit. Every sentence earns its place with no fluff 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?

The description covers the core purpose, restrictions, and limits, while the output schema and parameter schemas handle return values and parameter details. It doesn't explicitly mention prerequisites like authorization status or how to determine the correct environment, but the TipoAmbiente parameter description addresses that. The tool is complete enough for an agent to invoke 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?

The input schema has 100% description coverage, with detailed explanations for every parameter, including the NF-e/CT-e distinction between Correcao and Correcoes. The description adds no additional parameter-specific meaning beyond what the schema already provides, so a 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?

The description states a specific verb ('Envia'), a precise resource (Carta de Correção for NF-e or CT-e), and scopes it to already authorized documents (evento tipo 2). It clearly distinguishes from sibling tools like evento_cancelar and evento_inutilizar by naming the correction event 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?

The description implies usage context by specifying constraints (cannot correct values, dates, parties, etc.) and the 20-per-NF-e limit, but it does not explicitly name alternative tools or state when NOT to use this one. The schema further clarifies when to use Correcao vs. Correcoes for NF-e vs. CT-e, but the description alone gives no direct comparison to siblings.

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?

The description goes beyond the destructiveHint/openWorldHint annotations by clearly warning that the operation 'Não pode ser desfeito' and that it is rare, requiring user confirmation. This gives the agent essential behavioral context for a destructive external action.

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 brief and well-structured, using three short sentences to convey purpose, usage scenario, and critical warnings without redundancy or irrelevant detail.

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 complete parameter schema and the presence of an output schema, the description covers the essential context: what the tool does, when to use it, and the critical irreversibility warning. No important operational context 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?

All six parameters have descriptions covering allowed values, constraints, and relationships (e.g., NumeracaoInicial <= NumeracaoFinal, minimum Justificativa length). The description adds no extra parameter-level meaning beyond the schema, so baseline 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?

The description clearly states the specific action ('Inutiliza uma faixa de numeração não utilizada na SEFAZ') and the resource involved, making its purpose unambiguous and distinct from related siblings like cancellation or correction events.

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 identifies when the tool is useful ('quebra de sequência por erro de emissão') and provides a strong caution about irreversibility and user confirmation. However, it does not explicitly contrast with sibling tools such as evento_cancelar, so usage guidance is strong but not fully alternative-aware.

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?

The description discloses that it registers a manifestation (a write operation) but does not mention side effects such as SEFAZ transmission or irreversibility. More critically, the type mapping in the description (0–3) contradicts the schema's enum (1–4), misleading agents about valid inputs. Annotations only include openWorldHint, which does not clarify 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?

The description is concise and front-loaded with the core purpose, but it includes an incorrect mapping that should be removed or corrected. The brevity is good, but the flawed content detracts from its usefulness.

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 details are not required. However, the description is incomplete due to the erroneous type mapping and does not mention constraints like the mandatory Justificativa for TipoManifestacao=4 (though the schema covers it). The contradiction between description and schema makes it incomplete and unreliable.

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?

Although schema coverage is 100%, the description's type mapping (TipoEvento: 0–3) directly conflicts with the schema's TipoManifestacao enum (1–4). This is a severe misrepresentation that could cause an agent to send invalid values. The description adds no value beyond the schema and actively misleads.

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 ('Registra') and resource ('manifestação do destinatário sobre uma NF-e'), clearly distinguishing it from sibling event tools like evento_cancelar or evento_carta_correcao. The purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for manifestações but does not explicitly contrast it with alternatives or state when not to use it. Sibling tools like evento_cancelar are not mentioned, so an agent must infer usage from context.

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?

No annotations are provided, so the description carries full burden. It only says 'Gera o arquivo' without disclosing side effects, authentication requirements, or what happens with the transmit flag. Parameter descriptions partially compensate (e.g., note about certificate), but the tool description itself is minimal.

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 efficiently states the tool's purpose with no wasted words. Excellent conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite clear purpose, the description lacks completeness for an agent to fully understand the tool's behavior and output. No output schema exists, but the description does not mention what the tool returns (e.g., file content, success message). Given the array parameter and conditional transmission, more context is needed.

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 baseline is 3. The description adds no additional meaning to the parameters beyond what the schema already provides. It does not clarify parameter relationships or usage.

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 clearly states the tool generates the FCI file for products with imported content in interstate operations. The verb 'Gera' and specific resource 'arquivo FCI' are precise, and it distinguishes from sibling tools focused on other tax 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?

The description explains when the tool is required (products with imported content in interstate operations). It does not explicitly mention when not to use it, but the context of sibling tools implies it is for FCI only. This is adequate but could be more explicit.

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 indicate readOnlyHint=true and idempotentHint=true. The description adds that the tool returns status, timestamp, and version, providing more granular behavioral context without contradicting 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?

The description is a single focused sentence in Portuguese, front-loaded with the verb and resource. Every part is necessary and no words are wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description properly explains what the tool returns (status, timestamp, version). Given the simplicity of the tool and good annotations, the description is complete.

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?

The input schema is empty with 100% coverage. The description confirms no parameters are required, adding clarity 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?

The description clearly states the tool's purpose: to verify the health of the API BrazilNFe, including status, timestamp, and version. It explicitly mentions no parameters. This distinguishes it from siblings, none of which are health-checks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for health checking, but does not provide explicit guidance on when to use versus alternatives (e.g., sefaz_status). No 'when not to use' or context is given.

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 provide readOnlyHint=true and idempotentHint=true. The description adds that it simulates without issuing a note, confirming non-destructive behavior. It lists the specific taxes simulated. No contradictions. The output schema (mentioned in context) likely covers return values, so description does not need to detail them.

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 a single, clear sentence that efficiently conveys purpose and key limitations. However, it could be slightly more structured to also introduce parameters without losing conciseness.

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 simple complexity, good annotations, and an output schema, the description covers purpose and usage context. The major gap is the complete lack of parameter semantics, which hinders the agent from using the tool correctly. Additional details about the parameters are needed for completeness.

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 has two integer parameters (Count, Capacity) with 0% description coverage. The tool description does not mention or explain these parameters. 'Lista de produtos' suggests some relation but not mapped to Count/Capacity. Without explanation, an AI agent cannot understand or correctly use these parameters.

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 clearly states it simulates tax calculation (ICMS, PIS, COFINS, IPI, ST) on a list of products without issuing a note. The verb 'simular' and resource 'cálculo de impostos' are specific. This distinguishes it from siblings like nfe_emitir (issue invoice) and nfe_previsualizar (preview invoice).

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 explicitly states the tool simulates without issuing a note ('sem emitir nota') and positions it for pricing ('Útil para precificação'). This gives clear context. Though it does not explicitly name alternatives or when not to use, the sibling list and the 'without emitting' clause help differentiation.

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 are sparse (only openWorldHint), so the description carries the burden of behavioral disclosure. It adds useful context about grouping behavior and mandatory usage, but does not explain post-emission behavior, return values, or failure modes. The openWorldHint already signals side effects, but the description adds only limited extra behavioral detail.

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 compact and front-loaded, with two sentences that each add value: the first defines the action and purpose, the second states a key usage condition. No wasted words 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?

Given the tool's high complexity (24 parameters, nested structures) and low schema coverage, a two-sentence description is inadequate. It fails to mention prerequisites like referencing existing CT-e/NF-e keys, how to structure the grouped documents, or important environmental parameters like tipoAmbiente. The presence of an output schema reduces the burden for return values, but the description still lacks sufficient guidance for safe and correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool description contains no parameter information whatsoever. With schema description coverage at only 42%, the description needed to compensate for the many undocumented parameters (e.g., lote, serie, codigo, numero, carregamentos, descarregamentos), but it does not. This is a critical gap for such a large parameter set.

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 clearly identifies the specific action ('Emite MDF-e') and resource (Manifesto Eletrônico de Documentos Fiscais), and explains it groups multiple CT-e/NF-e into a single transport. This differentiates it from sibling emission tools like cte_emitir and nfe_emitir.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides an explicit when-to-use condition: 'Obrigatório para transportadores com vários DFs no mesmo veículo.' However, it does not name alternative tools or state when not to use it, so it falls short of a 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?

The description warns that encerramento is 'DEFINITIVO' and advises to review data before proceeding. This clearly communicates the irreversible side effect, even though no explicit destructiveHint is present in annotations. The warning is embedded in the parameter description but is part of the tool's overall documentation.

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 concise, using three short sentences to convey purpose, obligation, and consequence. Each parameter description is focused and free of unnecessary verbiage, achieving high information density without 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?

Given the tool's moderate complexity (4 params, 2 required) and the presence of an output schema, the description covers all necessary context: what it does, when to use it, the irreversible nature, and parameter semantics. No critical information 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?

All four parameters have detailed descriptions that go beyond basic field names. For example, tipoAmbiente includes explicit instructions to pass it explicitly, explains the valid values, and reiterates the definitive nature. The chave description specifies its 44-digit format, and protocolo notes it can be omitted with fallback behavior.

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 clearly states the tool's function: 'Encerra um MDF-e já autorizado (evento tipo 3)', with a specific verb and resource. It also explains the mandatory nature at the end of transport, making its purpose unambiguous and distinct from sibling 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?

The description provides explicit trigger conditions ('Obrigatório ao final de cada transporte') and consequences of non-use ('novos MDF-e podem ser bloqueados pela SEFAZ'). This frames when the tool must be invoked, which is sufficient guidance given the unique nature of the operation.

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?

With only openWorldHint in annotations, the description carries the behavioral burden and does well: it discloses that the operation is synchronous, can take 5-30s, and returns key, number, protocol, status, and XML/DANFE in base64. It does not explicitly state that production emissions are irreversible or legally binding, though the test-environment hint partially mitigates that.

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 compact and front-loaded: it states the operation, the two modes, the return values, the latency, and the test environment in five sentences with no filler. 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?

Despite the tool's complexity and 34 parameters, the description covers the essential decision points: which document model to use, what to expect in the response, timing behavior, and testing environment. It does not mention relationships to complementar/cancel events or prerequisites like certificates, but the rich schema and output schema offset much of that gap.

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 76%, so the schema already documents most parameters in detail. The description adds usage-oriented meaning for modeloDocumento and tipoAmbiente, but largely repeats what the schema already says rather than adding genuinely new parameter-level insight.

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 clearly states a specific verb ('Emite'), the resource ('NF-e modelo 55 / NFC-e modelo 65'), and target ('na SEFAZ'), making the core purpose unambiguous. It distinguishes the two document models, though it does not explicitly differentiate itself from siblings like nfe_emitir_complementar or nfe_previsualizar.

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 concrete usage direction: modeloDocumento=55 for NF-e (B2B), modeloDocumento=65 for NFC-e, and tipoAmbiente=2 for tests. It provides clear context for when each mode is appropriate, but does not explicitly state when to prefer a sibling tool such as nfe_emitir_complementar.

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?

With only openWorldHint annotation, the description carries the burden of explaining the tool's behavior. It discloses that the tool requires an already authorized NF-e and directs the user to provide the original key in NFReferencia, adding meaningful behavioral context beyond the annotation. It does not enumerate all technical side effects (e.g., SEFAZ submission), but the essential behavior is transparent.

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 no fluff. The first states the core action, the second gives the use case and the key parameter. Information is front-loaded and every word 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?

Given the tool has 16 parameters and a complex fiscal domain, the description is minimal. It omits guidance on TipoComplemento, ImpostoComplementar, and how to handle item-level complements. The output schema may cover return values, but an agent would struggle to know the full set of considerations for correct usage, so the description is merely adequate.

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?

The description explicitly instructs to pass the original invoice key in NFReferencia, adding meaningful value beyond the schema's vague 'Notas fiscal de Referência'. With schema coverage at 56%, highlighting this critical parameter helps agents avoid misusing the tool. However, it does not clarify the distinction between TipoComplemento values or the ImpostoComplementar structure, so it's not a 5.

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 clearly states the tool emits a complementary NF-e referencing an already authorized NF-e, using the specific verb 'Emite' and the resource 'NF-e complementar'. It distinguishes itself from sibling tools like nfe_emitir through the qualifier 'complementar' and the explicit finalidade=2 context.

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 usage context: for complementing values, taxes, or items of an already authorized invoice. It does not explicitly name alternative tools (e.g., nfe_emitir for normal invoices), but the reference to a previously authorized NF-e and finalidade=2 gives an agent enough context to select this over a regular emission.

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 only include openWorldHint=true, so the description carries the burden. It discloses that the tool sends to SEFAZ (external system), implying network dependency and authorization. However, it does not mention synchronous vs. asynchronous behavior, potential errors, or side effects beyond sending. Lacks detail for a mutation tool with external interaction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundancy, front-loaded with the core action. Every word contributes to understanding the tool's purpose.

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 tool's complexity (12 parameters, required fields, nested objects, and external authorization), the description is too sparse. It lacks prerequisites (e.g., required certificates, SEFAZ configuration), error handling notes, and any mention of idempotency or duplication control (despite the 'identificadorInterno' parameter hinting at it). While an output schema may explain return values, the description fails to provide sufficient context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The tool description adds no additional meaning to any parameter. Baseline of 3 is appropriate given full schema coverage.

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 clearly states the tool sends the NF-EnerCom to SEFAZ for authorization, distinguishing it from sibling tools like nfenercom_gerar_arquivo (which only generates the file) and nfe_emitir (general NF-e emission). The verb 'Envia' plus the explicit target 'autorização na SEFAZ' leaves no 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?

No explicit guidance on when to use this tool vs. alternatives (e.g., nfenercom_gerar_arquivo for file generation without sending, or nfe_emitir for other document models). The description does not state prerequisites, context requirements, or when not to use it.

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 provide only a title; no readOnlyHint, destructiveHint, or other behavioral flags. The description merely states the generation action without disclosing side effects, required permissions, file overwrite behavior, or state changes. For a tool that likely creates a file, this is insufficient transparency.

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 extremely concise—two sentences that front-load the core purpose and prerequisite relation. No superfluous words; every sentence contributes value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite a complex input schema (5 parameters, nested objects for notas), the description provides only a high-level summary and prerequisite hint. It omits any reference to return values, error conditions, file format, or validation rules, which is inadequate given the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema fully documents all five parameters. The description adds no additional semantics or context for any parameter, achieving only the baseline expectation.

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 clearly states the tool generates the NF-EnerCom file (specific verb 'gera' and resource 'arquivo da Nota Fiscal de Energia') and explicitly positions it as a prerequisite for the sibling tool nfenercom_emitir.

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 explicitly links the tool as a prerequisite for nfenercom_emitir, providing clear contextual guidance. However, it does not elaborate on alternative tools or when to use each generation mode (tipoGeracao 1 vs 2), which are detailed only in the schema.

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 provide readOnlyHint=true and idempotentHint=true, which cover safety. The description adds the key behavioral trait that no submission to SEFAZ occurs ('sem enviar para a SEFAZ') and the preview nature ('pré-visualização'). This is meaningful additional context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no redundancy. The core verb/resource/constraint ('Gera', 'DANFE em PDF', 'sem enviar para a SEFAZ') is front-loaded, and the use-case context ('Útil para conferência visual antes de emitir') is concise.

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 rich schema (89% coverage), output schema, and annotations covering safety, the description is largely complete. It lacks explicit mention of the output document format nuances (e.g., which DANFE variants are generated per document type) but the schema covers the document types.

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 89%, so the baseline is 3. The description adds value by clarifying that the tool accepts various document types (nf, cte, dce, mdfe, nfse) and generates preview PDFs/XML - context not fully evident from the schema alone. However, it doesn't detail parameter-specific semantics 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?

The description states a specific verb ('Gera'), resource ('DANFE em PDF'), and mode ('pré-visualização', 'sem enviar para a SEFAZ'). The title 'Pré-visualizar DANFE' is reinforced with clear differentiation from emission 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?

The description clearly indicates when to use this tool: 'para conferência visual antes de emitir' and states the key exclusion 'sem enviar para a SEFAZ'. It implicitly distinguishes from emission tools (nfe_emitir, cte_emitir, etc.) by emphasizing it does NOT submit to SEFAZ, though it doesn't name alternatives explicitly.

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 and idempotentHint, so the description's disclosure of 'consulta status e dados' adds little beyond that. No behavioral traits beyond annotations are revealed.

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 a single, concise sentence that front-loads the purpose. No redundant 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?

Given the existence of an output schema and clear annotations, the description is adequate but fails to explain how the parameters relate to the query criteria mentioned. Missing detail on what exactly is returned.

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%, but the description mentions 'número, série e ambiente' which are not present as parameter names; the actual parameters are 'Rps' and 'codLote'. This mismatch adds confusion rather than clarity.

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 clearly states the verb 'consulta' and the resource 'NFS-e já enviada', specifying query criteria (número, série e ambiente). It effectively distinguishes from sibling tool 'nfse_emitir' which is for emission.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for already-sent NFS-e but provides no explicit guidance on when to use it vs. other tools, nor exclusion criteria. Usage context is implied but not explicit.

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?

With only openWorldHint available, the description adds useful context about municipality-specific rules, webservices, and routing based on company registration. However, it does not mention side effects such as the fiscal/legal weight of a production emission, required credentials, or what happens after successful submission.

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 with no filler: the core action comes first, followed by the two essential caveats about municipality-specific rules and routing. Every sentence earns its place in a domain with heavy regulatory 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?

The most important non-obvious context is present: municipality-dependent rules/webservices and the choice between Portal Nacional and a specific prefeitura. It could more explicitly warn that TipoAmbiente=1 is a real, fiscally valid emission, but the schema already documents the environment enum, and an output schema exists.

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?

The tool description itself adds no parameter-level meaning, leaving the schema to explain TipoAmbiente and nFSInfo. With 67% schema description coverage and the large nested schema already carrying most parameter semantics, a mid score 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?

States a specific action and resource: 'Emite NFS-e (Nota Fiscal de Serviços Eletrônica)', and the title adds '(serviços)' to distinguish it from product-invoice siblings like nfe_emitir. The description also clarifies the two possible delivery channels, so an agent can identify this as the service-invoice emission 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?

Gives clear operational context: the issuing municipality must be checked first, and the tool may use Portal Nacional NFS-e or a specific prefeitura depending on company registration. It does not explicitly name alternative tools such as nfse_consultar or state when not to use the tool, so it falls short of a 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 and idempotentHint, covering the safety profile. The description adds the date-range and invoice-type context, but its claim of filters for chave, número, and status conflicts with the schema and is a misleading disclosure; it also omits pagination/limit 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?

The description is compact and front-loaded in the first sentence, but the second sentence contains an inaccurate list of filters. A concise description is only valuable if every sentence earns its place, and this one does not.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a rich schema, output schema, and readOnly/idempotent annotations, the description is mostly sufficient for a list operation. It misses pagination/limits, date-format details, and an accurate mapping of actual filter parameters, but the output schema covers return-value details.

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 some meaning by naming NF-e/NFC-e/NFS-e and emitted/received types, but it does not clarify DtInicio/DtFim date format or correct the unsupported 'status' filter claim.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence uses a specific verb and resource ('Lista NF-e/NFC-e/NFS-e') with a date-range scope, making the core purpose clear. However, the second sentence advertises filters for chave, número, and status that do not exist in the input schema, which detracts from precision.

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 date-range and emitted/received framing implies this is for broad invoice listing, but the description never explicitly says when to prefer it over sibling consult/emission tools or lists exclusions. There is implied usage context, not explicit guidance.

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 and idempotentHint true, indicating a safe read operation. The description adds pagination behavior (default 20, max 50, offset, TotalGeral) and warns against inventing or grouping results, which goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no wasted words. The first sentence states the purpose and inputs, the second covers pagination. It is front-loaded with the most important 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?

The tool has 4 parameters (none required) and an output schema (not shown). The description covers the primary use case and pagination well, but fails to explain the TipoBusca parameter. Given the output schema exists, the description is mostly complete but has a notable gap.

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 coverage, the description must compensate. It explains that the Termo parameter can accept internal code, NCM (8 digits), GTIN/EAN (8/12/13/14 digits), or partial description. It also hints at pagination parameters (Limite default 20 max 50, Offset). However, the TipoBusca parameter is not explained, leaving a 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?

Title and description clearly specify that this tool queries products by internal code, NCM, GTIN, or partial description. It distinguishes from siblings like produto_criar by advising to use before creating new products to avoid duplicates.

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 explicitly states to use this tool before creating new products to avoid duplicates, providing a clear when-to-use guideline. It does not explicitly state when not to use it, but the context from sibling tools implies alternatives.

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?

The description adds behavioral details beyond the sparse annotations: duplicate validation by Codigo, automatic zero-padding for NCM, and check digit validation for EAN/GTIN. These are important mutations that the agent should know.

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 concise sentences with essential information front-loaded. No redundant or vague wording.

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 11 parameters and presence of an output schema, the description covers key validations for critical fields but omits behavior for optional parameters. Some context is provided, but not fully complete for a tool with many optional 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 coverage is 0%, so the description must compensate. It adds meaning for 'Codigo' (duplicate check), 'Ncm' (format constraints), and 'Ean' (validation). However, it does not explain other parameters like 'Id', 'Cest', 'FatorConversao', leaving gaps.

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 'Cadastra um novo Produto na empresa logada', clearly indicating the verb (cadastrar/criar) and resource (Produto), and it distinguishes from sibling tools like 'produto_editar' and 'produto_consultar'.

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 mentions validation rules for duplicate code, NCM format, and EAN check digit, which guide when the tool is appropriate. However, it does not explicitly state when not to use or list alternatives, but the context of sibling tools makes it clear.

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?

The description discloses critical behaviors beyond annotations: the destructive nature of omitting fields (zeroes them) and ownership checks. Annotations only mark idempotentHint=true, which is consistent. No contradictions.

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 concise (single paragraph) and front-loads the purpose. However, the mix of warnings and instructions could be better structured (e.g., bullet points) for clarity. Still, every sentence adds value.

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 complexity (11 parameters, zeroing behavior, ownership validation), the description adequately covers usage workflow and warnings but fails to document parameter meanings. The presence of an output schema offsets return value explanation, but parameter semantics are lacking.

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. However, it only mentions 'Id' as required and provides no details about other parameters (e.g., Codigo, Descricao, ValorUnitarioVenda). This is a significant gap for an 11-parameter tool.

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 clearly states 'Atualiza um Produto existente' with a specific verb and resource. It implicitly distinguishes from sibling tools like 'produto_criar' (create) and 'produto_consultar' (query) by referencing 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?

Provides explicit guidance: ID required, payload must be complete (omitted fields zeroed), recommends prior consultation via 'produto_consultar', and explains ownership validation rules. This helps the agent use the tool correctly.

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, openWorldHint=true, and idempotentHint=true, which fully covers the safe-read behavior profile. The description adds the context that it should be used as a pre-flight check and mentions it addresses 'autorização' status specifically. It doesn't describe return format or pagination, but with strong annotations and an output schema present, the added behavioral value is moderate.

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 waste. The first sentence states purpose; the second provides usage guidance. Every word earns its place. The description is appropriately sized for a simple single-parameter status-check tool.

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 simple status-checking tool with 1 parameter (fully documented), strong annotations (read-only, idempotent, open-world), and a provided output schema, the description is complete. It covers purpose, usage timing, and the tool's role. It doesn't explain the return values, but with an output schema present, that's not required.

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 one parameter (ModeloDocumento) has a full enum breakdown (55 - NF-e; 65 - NFC-e) plus a default value explained in the schema itself. The description adds nothing about parameters beyond what the schema provides. Baseline 3 is appropriate since 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?

The description clearly states it consults the SEFAZ authorization service status for a UF and environment (Consulta o status do serviço de autorização da SEFAZ para uma UF e ambiente). The verb 'Consulta' plus the resource (status do serviço de autorização) is specific. While sibling tools include many emission tools, this one stands out as a status/health check — but the description doesn't explicitly differentiate it from siblings beyond its obvious distinct 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?

The description provides clear usage guidance: 'Use antes de uma emissão em lote ou quando suspeitar de instabilidade' (use before batch emission or when suspecting instability). This gives concrete when-to-use context. However, it doesn't offer explicit when-not-to-use or name alternatives, though given the sibling list, none of those tools would be alternatives for status checking.

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?

Description adds critical behavioral context beyond the readOnlyHint and idempotentHint annotations, including pagination details (default 20, max 50, offset, TotalGeral) and a directive not to invent or group results. This fully discloses how the tool behaves.

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 concise with 4 sentences, each serving a distinct purpose: purpose, filtering options, usage guidance, and pagination. No redundancy, essential information 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?

Given the 5 parameters and pagination, the description covers filtering and pagination well. Output schema exists, so return format is handled. It lacks error conditions or default behavior when no parameters are given, but overall it's adequate for the task.

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 coverage, the description compensates well by explaining each parameter's meaning: Tipo (1=NFe,2=NFCe,3=Energia/Comunicacao), Cfop (specific CFOP), Termo (search term), and pagination (Limite, Offset). It adds value but could be slightly more precise on data types.

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 clearly states it lists company tax rules (CFOP, CST, aliquotas) and specifies filtering options. It distinguishes from sibling tools like tributacao_criar/editar by guiding use before creating a nota fiscal, making purpose highly specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises to use this tool before creating a nota fiscal to know which taxes to apply. It provides pagination instructions and implies read-only usage, though it doesn't explicitly mention when not to use it or contrast with alternatives beyond pagination.

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?

No annotations beyond title, so the description must disclose behavioral traits. It only mentions that CstIbsCbs is required and lists some fields. It does not discuss side effects, authentication needs, error behavior, or what happens upon success. The output schema exists but is not referenced.

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 concise (two sentences) and front-loaded with key information. It wastes no words but could benefit from a more structured format (e.g., listing parameter groups).

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 tool's complexity (23 parameters, creation logic), the description is incomplete. It lacks info on return values, error conditions, prerequisites, and does not leverage the existing output schema. A more comprehensive description is needed for effective use.

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 groups parameters ('CFOP + CSTs + aliquotas') and notes one required field, but with 23 parameters, this is insufficient. Most parameters are not explained, leaving the agent guessing their meaning and constraints.

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 clearly states the tool creates a new tax rule, lists key components (CFOP, CSTs, aliquotas), and provides a mapping for Tipo (1=NFe, etc.). It is distinct from sibling tools like tributacao_editar and tributacao_consultar.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for creating new rules but does not explicitly compare with alternatives (e.g., when to use tributacao_criar vs tributacao_editar). It does highlight a requirement (CstIbsCbs is mandatory), but lacks general guidance on when or when not to use this 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?

The description warns that omitted fields are zeroed ('ATENCAO: envie o payload COMPLETO - campos omitidos sao zerados'), a critical behavioral trait for a full-replacement update. It also states ownership validation. The annotation idempotentHint=true aligns with the description, as full replacement is idempotent. No contradictions.

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 a single paragraph of three concise sentences, front-loading the main purpose and immediately following with critical usage instructions. Every sentence adds value, 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?

The description covers the essential workflow (fetch first, then update complete payload), ownership validation, and the risk of zeroed fields. However, it does not reference the output schema or explain the response. Given the complexity (23 params, high mutation risk), a brief note about return values would improve completeness.

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?

The input schema has 23 parameters with 0% description coverage (no parameter-level descriptions in the schema). The description does not explain individual fields like Cfop, AliqIcms, etc. It only provides high-level advice to send the complete payload. Given the large number of parameters, the lack of parameter semantics is a significant 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?

The tool name 'tributacao_editar' translates to 'edit taxation rule', and the description states 'Atualiza uma regra de tributacao existente' (updates an existing taxation rule), clearly identifying the verb (update) and resource (taxation rule). This distinguishes it from sibling tools like 'tributacao_consultar' (query) and 'tributacao_criar' (create).

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 explicitly requires the 'Id' parameter ('Id obrigatorio') and instructs the agent to first call 'tributacao_consultar' to obtain current data, then send the complete payload with modifications. It also mentions ownership validation by IdEmpresa (implied in context). This provides clear when-to-use and prerequisites.

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