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?

Annotations provide only 'openWorldHint: true', indicating potential side effects, but the description does not elaborate on behavioral traits like data modification, authorization requirements, or consequences. It merely states it registers a disagreement.

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 with two sentences, front-loading the core purpose and adding a critical deadline. 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 presence of an output schema and 4 optional parameters, the description provides a minimal but functional explanation. However, it lacks context on what the response contains or any side effects implied by '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?

Schema description coverage is only 50% (only 'TipoAmbiente' has a description). The tool description provides no additional meaning for parameters, leaving 'Chave', 'Observacao', and 'NumeroSequencial' unexplained.

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

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

The description clearly states the specific action ('Registra desacordo') and resource ('CT-e recebido'), and distinguishes itself from sibling tools like 'evento_manifestar' by specifying it's for disagreement (evento tipo 4).

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 includes a deadline ('Prazo: 45 dias da emissão') which is useful, but lacks explicit guidance on when to use this tool vs. alternatives, such as when not to use it or related tools like 'evento_manifestar'.

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 description aligns with annotations (destructiveHint=true) and adds important behavioral details: the requirement for the environment to match the original document, the need for a protocol number when the document was issued by an external system, and the automatic protocol retrieval for BrasilNFe-issued documents. It also clarifies the conditional use of ChaveNF vs NumeroNFSe.

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

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

The description is three sentences: first states the core action and document types, second explains the NFS-e special case, third provides the deadline. Every sentence adds essential information 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 complexity (10 parameters, 4 required, conditional logic, and an output schema), the description covers key behavioral aspects: cancellation scope, document type distinction, environment matching, deadline, justification rules, and external system handling. It is complete for an agent to select and 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?

With 100% schema coverage, the description still adds significant value: it specifies the 44-digit length for ChaveNF, the minimum and maximum length for Justificativa with examples of inadequate text, the requirement that TipoAmbiente matches the original environment, and the conditional requirement for NumeroProtocolo. This goes well beyond the 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?

The description explicitly states the tool cancels authorized fiscal documents (NF-e, NFC-e, NFS-e, CT-e, MDF-e, DC-e) and distinguishes between document types via TipoDocumento. The title and description are aligned and differentiate from sibling event tools like 'evento_carta_correcao'.

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 when-to-use guidance (cancellation after authorization) and includes a critical deadline (24h for NF-e) and constraints (justification length). While it does not explicitly state when not to use, the alternative tools are listed as siblings and the description's focus on cancellation implies exclusivity.

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 the constraint that CC-e cannot correct certain fields and a limit of 20. Annotations only provide openWorldHint, no safety hints. The description implies a write operation but does not disclose required permissions or reversibility. Moderate extra value.

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 concise sentences that front-load the action and then list constraints. No unnecessary words. Highly efficient.

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

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

The description covers purpose and constraints but does not mention the dual correction modes (string for NF-e vs list for CT-e) which are important for correct usage. Given the complexity and presence of an output schema, the description is adequate but could be more 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?

Schema coverage is 100% with detailed parameter descriptions. The tool description does not add additional parameter-level information; it only restates constraints that are already in the schema. Baseline score of 3 applies.

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

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

The description clearly states the action (Envia Carta de Correção) and the target documents (NF-e or CT-e authorized). It specifies it is for event type 2, which differentiates from other event tools like cancelar or inutilizar, though not 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?

Describes what cannot be corrected (values, dates, parties, tax regimes, document numbers) which guides when not to use. Mentions a limit of 20 CC-e per NF-e. Does not explicitly recommend alternative tools but the constraints help the agent decide.

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 critical behavioral context beyond the destructiveHint annotation by stating 'Não pode ser desfeito' (cannot be undone) and emphasizing the need for user confirmation. This fully aligns with the annotation and provides extra 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 consists of three concise sentences: first defines the action, second gives usage context, third warns about rarity and confirmation. No unnecessary words or repetition.

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 presence of an output schema (not shown), the description need not cover return values. It adequately covers purpose, usage, and behavioral warnings. It could mention prerequisites or side effects, but the overall completeness is high.

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 100% schema coverage, each parameter already has a description in the schema. The tool description does not add parameter-level details, so it meets the baseline without compensating further.

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 action (inutilizar faixa de numeração) and the specific resource (SEFAZ). It distinguishes itself from sibling event tools like evento_cancelar and evento_manifestar by focusing on range invalidation due to sequence breaks.

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 a specific use case ('quebra de sequência por erro de emissão') and cautions that it's a rare operation that should be confirmed with the user. However, it doesn't explicitly state when not to use it or compare to 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?

Annotations include openWorldHint but no destructiveHint. The description does not explain side effects, such as irreversibility or creation of a record. Moreover, the description contradicts the schema on event type values, which is a behavioral misrepresentation.

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 sentence with a list, making it concise. However, the inaccuracy in the list detracts from its effectiveness. It is front-loaded but flawed.

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 but was not provided; the description does not mention return values. Given the complexity (5 parameters, 2 enums) and the schema-cover error, the description is incomplete and fails to address the mismatch.

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 input schema already documents all parameters well. The description adds a mapping of TipoEvento that is inaccurate (0-3 vs schema's 1-4), which actually harms understanding rather than adding value.

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

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

The description clearly states the verb 'Registra' and resource 'manifestação do destinatário sobre NF-e', but then lists TipoEvento values that do not match the schema's TipoManifestacao enum, causing confusion. It is distinct from siblings but the inconsistency weakens clarity.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. The agent must infer usage from the name and 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 adds context about the blocking consequence but does not explicitly mention the irreversible nature of the encerramento (though the schema's 'tipoAmbiente' notes it as DEFINITIVO). The annotation 'openWorldHint' already indicates potential unknown side effects, so the description aligns but adds limited extra 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?

Two concise sentences, front-loaded with the core action, 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 output schema exists (context indicates true), the description adequately explains the tool's necessity and consequence. However, it does not describe what the return value contains, but the output schema likely fills this 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?

The input schema covers 100% of parameters with descriptions. The main description does not add further parameter-level meaning 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 clearly states it ends an authorized MDF-e (specific event type 3). It is distinct from siblings like mdfe_emitir and other event tools, making its purpose unmistakable.

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 it is mandatory at the end of each transport and warns that not using it may block new MDF-e. However, it does not provide explicit alternatives 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 are minimal (only openWorldHint), so the description carries the behavioral burden. It discloses that the operation is synchronous and may take 5-30 seconds, and lists the key return fields (chave de acesso, número, protocolo, status, XML/DANFE). This adds genuine context beyond the schema, though it could mention side effects like email sending or irreversibility of production issuance.

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 only three sentences, front-loaded with the primary action, then covers model selection, returns, latency, and test guidance. Every sentence earns its place with no filler or redundancy.

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

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

For a tool with 30 parameters including nested tax objects and 6 required fields, the description is quite sparse. It covers core decision points (model, environment, latency) but does not guide agents on required fields or structural dependencies, such as needing Cliente for NF-e or payment methods for NFC-e. The schema and output schema fill some gaps, but given complexity, more operational context would make it 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?

Schema description coverage is 73%, so the schema already documents most parameters. The description adds minimal new semantic value by reiterating the meaning of modeloDocumento and tipoAmbiente, both of which already have detailed schema descriptions. It does not explain other critical parameters like Produtos or Cliente, relying on 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 emits NF-e (model 55) or NFC-e (model 65) to SEFAZ. It distinguishes the two models by target audience (B2B vs consumer) and differentiates from siblings like nfe_emitir_complementar and nfe_previsualizar by focusing on actual emission and synchronous behavior.

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 on when to use each model (55 for NF-e B2B, 65 for NFC-e consumer) and recommends tipoAmbiente=2 for testing. However, it does not explicitly mention when not to use the tool or alternatives like nfe_previsualizar for validation, so it stops short of full exclusion 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?

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?

The description adds behavioral context beyond the readOnlyHint and idempotentHint annotations by explicitly stating that the operation does not send to SEFAZ. It does not contradict the annotations, and the side-effect-free nature is reinforced. It could mention the watermark/tarja or output details, but those are partially covered by the schema.

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

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

The description is two sentences, front-loaded with the main action, and contains zero filler. 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?

For a simple preview tool with strong annotations and an output schema, the description captures the essential behavioral context. However, it only mentions PDF output, omitting that TipoArquivo can also generate XML previews, and does not mention the configurable 'SEM VALOR FISCAL' tarja. These are minor gaps but do not prevent an agent from understanding the tool's core purpose.

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 60%, and the description adds no parameter information. While the schema explains TipoEnvio, TipoArquivo, and mostrarTarjaPreVisualizacao, the primary input params Base64Xml and notaFiscal lack descriptions, and the tool description does not clarify the choice between them. The description contributes no additional meaning 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 uses a specific verb ('Gera') with a clear resource ('DANFE em PDF') and states the scope ('pré-visualização', 'sem enviar para a SEFAZ'). This clearly distinguishes it from sibling tools like nfe_emitir, which actually transmit to SEFAZ.

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: use it 'antes de emitir' and 'sem enviar para a SEFAZ', which implies it is the alternative to emission tools. It does not explicitly name alternatives (e.g., nfe_emitir), but the contrast is strong enough for an agent to infer when 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 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 an openWorldHint annotation and no readOnly/destructive hints, the description carries the burden of behavioral disclosure. It adds useful context about municipal variation and routing ('Pode usar Portal Nacional NFS-e ou prefeitura específica conforme cadastro da empresa'), but it does not explicitly warn that emission is a real fiscal act, that production mode has legal effect, or that authorization/credentials may be required. The schema's TipoAmbiente description covers production vs. homologation, but the tool description itself stays at a general level.

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

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

The description is two sentences, front-loaded with the primary verb and resource, and every sentence adds value: the first states the action, the second warns about municipal variability and routing options. No filler or tautology.

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 of NFS-e emission, the description is brief but includes the most critical operational caveat (per-municipality rules/webservices) and the routing choice. The input schema fills in parameter details and the output schema covers return values. A more thorough description could mention environment safety and prerequisites, but the combination of description plus schema is sufficient for an informed agent.

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 provides no parameter-level guidance, but the input schema is rich and covers the required parameters (TipoAmbiente, nFSInfo) with detailed nested descriptions. Schema description coverage is 67%, so the schema carries most of the semantic weight. The description does not add meaning beyond the schema, but it also does not conflict with it; 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 starts with 'Emite NFS-e (Nota Fiscal de Serviços Eletrônica)' which is a specific verb+resource pairing that immediately distinguishes this tool from siblings like nfse_consultar, nfe_emitir, and cte_emitir. It also clarifies scope by mentioning the National Portal and specific city halls.

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 clear context on when to use the tool: to emit an electronic service invoice, and it warns that each Brazilian municipality has its own rules and webservices. It does not explicitly name alternative tools or exclusion criteria, but the guidance to 'confira o município emissor antes' and the distinction between Portal Nacional and prefeitura específica provides practical usage 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 already declare readOnlyHint and idempotentHint, so safety is clear. The description adds useful context about 'emitidas ou recebidas' and date range, but it claims support for filters by 'chave, número, status e tipo', which are not present in the input schema. This misleading claim reduces 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 concise and front-loaded with the main verb 'Lista'. The second sentence is short but contains an inaccurate claim, so it does not fully earn its place. Still, overall brevity is good.

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 an output schema and strong annotations, so return values and safety are covered. The description conveys the core purpose but lacks details about behavior without required parameters and contains a misleading filter statement. Adequate but with clear gaps.

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 does not add meaningful parameter semantics; instead, it introduces filter concepts (chave, número, status) that have no corresponding schema parameters, potentially confusing agents about available inputs.

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

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

The description uses the specific verb 'Lista' and clearly identifies the resource as NF-e/NFC-e/NFS-e with scope (emitidas ou recebidas) and a date interval. This differentiates it from sibling tools that emit or consult specific invoices.

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: use this tool to list invoices in a date range. It does not explicitly name alternatives or exclusions, but the purpose is specific enough to guide selection among 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?

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.