emissaoja · NFS-e

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description earns credit for disclosing the three terminal/intermediate states and that failures return the error, which is real behavioral context not available from annotations or schema (no output schema exists).

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 compact sentence with the core information front-loaded. Efficient, though slightly telegraphic and the '(cancelamento)' aside is less prominent than it deserves.

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, describing the possible states is genuinely necessary and done well. However, for a polling tool the description omits how the operacao_id is obtained and any polling guidance, leaving meaningful gaps for correct invocation.

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

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

The single parameter operacao_id has 0% schema description coverage, and the description says nothing about it — no format, no indication that the id comes from cancelar_nota. The description fails to compensate for the schema gap.

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

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

States a specific resource (operação) and its status check, and enumerates the possible outcomes (processando, concluida, falhou com erro). It does not differentiate from the near-identical sibling acompanhar_pedido, leaving the agent to infer the target object from the name alone.

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 parenthetical '(cancelamento)' hints this is used to poll a cancellation operation, but there is no explicit statement of when to call it, how often to poll, or why one would choose it over acompanhar_pedido. Usage is implied rather than specified.

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 and destructiveHint=false; the description adds the state machine (na_fila, emitindo, confirmando, autorizada, recusada, incerta) and what each carries (numero/chave_acesso on success, motivo on rejection). That is meaningful context beyond the annotations, though it doesn't say what 'incerta' means operationally or whether the poll can time out.

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 dense sentences: the state enumeration is front-loaded and the polling instruction follows. No filler, and the return-relevant fields are named inline rather than in a separate list.

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 carries the burden of explaining return values and does so via the state enumeration plus the fields returned in each terminal state. The mention of proxima_consulta_ms covers polling cadence. It only misses guidance for the 'incerta' outcome.

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?

One parameter with 100% schema coverage (UUID, 36 chars) does all the work; the description adds nothing about where pedido_id comes from (presumably emitir_nota). Baseline 3 is appropriate when the schema fully documents the only parameter.

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

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

States a specific verb+resource ('Estado de um pedido de emissão') and enumerates the possible states, so the agent knows this is a status lookup for a previously created emission request. It does not explicitly distinguish itself from siblings like acompanhar_operacao or status, which keeps it from a 5.

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

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

Explicitly says to call again after proxima_consulta_ms while the state is not terminal, which is real usage guidance for a polling tool. It does not name alternatives or exclusions (e.g. acompanhar_operacao vs status), so 4 rather than 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?

Beyond the annotations (destructive, non-idempotent), the description discloses irreversibility, the deadline constraint, the confirmation requirement, and the asynchronous pattern — returns an operation that must be tracked via acompanhar_operacao with processando → concluida/falhou states. That is substantive behavioral context the annotations cannot convey.

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

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

Three short sentences, front-loaded with the action and its key constraint, then the safety warning, then the follow-up path. No filler.

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

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

For a destructive mutation with no output schema, the description covers the return shape at a high level (an operation handle) and the tracking workflow. The remaining gap is the unexplained 'origem' and 'justificativa' parameters, which an agent could get wrong.

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

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

Schema coverage is 50%: motivo's enum and nota_id's UUID format are already documented in the schema. The description says to confirm 'número, tomador, valor' and 'motivo' but adds nothing about 'origem' (local/importada) or the optional 'justificativa' (15–255 chars), so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Cancela uma nota emitida') plus a scope constraint ('dentro do prazo do Emissor Nacional'), which clearly separates it from emitir_nota and listar_notas among the siblings.

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

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

Gives the operative precondition (within the National Issuer deadline) and instructs confirming nota details and motivo with the person before calling. It does not name explicit alternatives or when-not-to-use cases beyond the deadline, so it stops short of full routing 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?

Goes well beyond the annotations: states the password is validated against the portal and never stored or returned, discloses the 3-attempts-per-day lockout risk, the immediate synchronous response, and the downstream effect of reading fiscal registration and pulling 90 days of invoices. This is exactly the context the annotations (readOnlyHint=false, openWorldHint=true) cannot convey.

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

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

Front-loaded with what the tool does, then credentials handling, side effects, usage restriction and follow-up — each sentence carries distinct information. Slightly dense in a single paragraph, but nothing is 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?

No output schema exists, and the description compensates by saying it answers immediately with the attempt result and pointing to situacao_credencial for the asynchronous outcome. For a credential-connecting mutation with a rate-limited external portal, nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real disambiguation by clarifying the password is the Emissor Nacional portal password and 'não é a conta gov.br'. The ciente_ultima_tentativa flag is left entirely to the schema, which is acceptable given its description calls out the situacao_credencial dependency.

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

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

Specific verb (conecta) plus resource (empresa da conta ao Emissor Nacional) plus the credentials required. It is clearly distinct from siblings like situacao_credencial or consultar_cnpj, which only read state.

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?

Explicit gate: 'Só use quando a pessoa pedir e informar a senha ela mesma', plus the hard portal rule of at most 3 wrong attempts per day. It also names the follow-up path (situacao_credencial until proximo_passo leaves "aguardar"), so the agent knows both precondition and next step.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description still adds real context beyond them: no side effects on tomadores, and that partner CPFs are returned masked — a data-handling detail an agent should know before surfacing results.

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

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

One sentence for content and one for routing, with zero filler. The field list is front-loaded before the disambiguation clause, which is the right order.

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, listing the returned fields is exactly the right compensation, and the sibling pointer closes the main ambiguity. Minor gaps remain: nothing about behavior on an unknown/invalid CNPJ (error vs empty result) or whether the lookup is cached/live.

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?

Single parameter with 100% schema coverage, and the schema already says punctuation is optional. The description adds nothing about the cnpj argument, so the baseline 3 applies — the schema does all the work here.

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

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

States a specific verb+resource (fetch registry data for a CNPJ from Receita Federal) and enumerates the returned fields (razão social, situação, CNAEs, endereço, Simples/MEI, sócios). The explicit "Não cria tomador" separates it from the sibling criar_tomador.

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 excludes a plausible misreading ("Não cria tomador") and routes to criar_tomador for the issuing flow, which is strong guidance. However it does not distinguish this from the sibling validar_cnpj, leaving the agent to infer which lookup to use when it only needs validation.

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 real context beyond the annotations: it discloses the external dependency on Receita (reinforcing openWorldHint), the idempotent-collapse behavior with the ja_existia flag, and the chaining contract (retorna tipo + id para emitir_nota). It does not mention auth/permission requirements, which would be the remaining gap for a create operation.

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 tight sentences, zero filler, and the primary branching rule plus the return contract are front-loaded. Every clause carries information an agent needs.

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 compensates by naming the returned fields (ja_existia, tipo, id) and their downstream use. Combined with the CNPJ/CPF branching and idempotency note, there is nothing essential left for an agent to guess.

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

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

Schema coverage is 100% and both parameters already carry descriptions covering the CNPJ/CPF and punctuation tolerance, so the description largely restates the schema (nome obrigatório para CPF). No added syntax, format, or validation detail beyond what the schema states — baseline 3 applies.

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

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

Specific verb + resource ("Cadastra um cliente") with the two supported identity paths spelled out (CNPJ auto-filled from Receita, CPF requires full name). An agent can distinguish this from listar_tomadores or consultar_cnpj by the act of creation, though no sibling is named explicitly.

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

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

States the selection rule between the two modes (CNPJ → only documento needed, data sourced from Receita; CPF → must supply nome) and warns that an existing record is returned rather than duplicated. Lacks an explicit "check with consultar_cnpj/validar_cnpj first" exclusion, so it stops just short of full when/when-not coverage.

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?

Goes well past the annotations by disclosing the two response branches: a pedido to be tracked, or a blocker payload with code, mensagem and acao. It also explains the idempotency mechanism behind idempotentHint=true (repeating the same referencia returns the same pedido, never double-issues) and warns of real fiscal effect. It does not cover permission/credential prerequisites or what an "incerta" state requires next.

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?

Verb and resource lead, then the branch behavior, then the idempotency rule, then the confirmation warning; every sentence carries operational information and the parenthetical examples do real work.

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 9-parameter mutation with no output schema, the description supplies the missing return-value semantics (pedido vs bloqueios with their fields) and the escalation path via acompanhar_pedido, which is exactly what an agent needs to call and then handle the result.

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 baseline is 3, but the description adds real semantics the schema lacks: referencia must be unique per nota the person wants issued, and reusing it collapses to the same pedido. The confirmation-related parameters (confirmo_repeticao, permitir_repetida_de) are only partly addressed, so it stops short of 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?

Names a specific verb and resource ("Emite uma nota fiscal de serviço no Emissor Nacional") and constrains the target ("para um tomador já cadastrado"), which cleanly separates it from criar_tomador, listar_notas and cancelar_nota.

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?

Explicit prerequisites (use listar_tomadores or criar_tomador first), explicit follow-up (acompanhar_pedido until autorizada/recusada/incerta), explicit confirmation duty before calling, and the condition that switches behavior (com bloqueio vs sem bloqueio). Nothing about when to call is left to inference.

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

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

Annotations already declare readOnlyHint and non-destructive, so the lower bar applies; the description still adds real value by declaring the result fields (número, situação, data, tomador, valor, origem+id) and the fact that both local and portal-imported notes appear. It stays silent on the default page size and pagination behavior.

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

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

Front-loads what the tool returns before the filter list, and every clause carries information. Slightly dense packing of the return fields into one clause, but no filler.

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

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

With no output schema, the description does the work of describing the result shape, which is the main thing an agent needs for a read-only listing. The remaining gap is pagination/limits (limite defaults to 20, max 50), which goes unmentioned.

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

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

Schema coverage is only 25% (just busca is documented), yet the description spells out the accepted period values and the três situacao values, effectively covering 3 of 4 parameters. Only limite is left unexplained in both places.

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

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

States a specific verb and resource (list issued notes) and pins down scope: local notes plus ones imported from the portal. It also enumerates the fields returned and names the origin+id pair that cancelar_nota consumes, which separates it from its siblings.

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

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

The mention of the origin+id pair 'que cancelar_nota usa' implies the chaining pattern (list, then cancel), but there is no explicit statement of when to choose this tool over acompanhar_pedido or acompanhar_operacao, and no stated exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful semantics about the 'principal' flag and its interaction with emitir_nota. It does not disclose that results are filtered by the ativos parameter by default (default '1'), which is a real behavioral trait an 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?

Two short sentences with no filler; the resource and returned fields come first, and the cross-tool dependency note follows. Every clause carries information an agent can use.

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

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

For a read-only single-parameter list tool with annotations and no output schema, the description covers what is returned and why it matters to emitir_nota. It leaves the active/inactive filtering behavior and ordering/results size undocumented, which an agent needs to interpret the response correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the sole parameter, and it does not mention 'ativos' at all. The enum values '1'/'0'/'todos' with default '1' are guessable but unexplained in either location. The description spends its words on returned fields rather than on controlling the filter.

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 names the resource (registered company services) and enumerates the key returned fields (descrição, código nacional de tributação, ISS, principal), which makes it distinguishable from siblings like listar_tomadores and listar_notas. It lacks an explicit verb ('listar'), but the intent of retrieving catalogued services is unambiguous.

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

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

The second sentence hints at the main downstream use case: emitir_nota falls back to the 'principal' service when servico_id is omitted, implying this tool is where an agent looks up service IDs. It never states explicit when-to-use/when-not-to-use rules or any alternative for looking up services. Usage is implied rather than prescribed.

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=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: the shape of each returned record (tipo, id, nome, documento) and the downstream contract that tipo + id feeds emitir_nota. Pagination/empty-result behavior is not described, keeping it below 5.

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

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

Two compact sentences with the core purpose front-loaded, followed by the return-shape and cross-tool contract. Every clause carries information; nothing is padding.

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 usefully enumerates the returned fields and the key identifier pair, which is what an agent needs to chain into emitir_nota. The only gap is pagination semantics for pagina, a minor omission for a read-only list tool.

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

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

Schema coverage is only 50%: busca is documented in the schema and merely restated in the description, while pagina has no description in either place. The description does not compensate for the undocumented pagination parameter, so it adds no meaning beyond structured fields.

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

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

States a specific verb and resource ("Lista os tomadores (clientes) da empresa") and names the search capability. It also enumerates the returned fields and ties the tool to emitir_nota, so an agent can distinguish it from listar_notas and criar_tomador.

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 clause "com busca por nome ou documento" tells the agent when the busca parameter is appropriate, and the emitir_nota reference clarifies why one would list tomadores (to get tipo + id). There is no explicit exclusion or comparison against siblings like criar_tomador, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile needs no repetition. The description adds genuine value beyond them: it enumerates the state machine values (ausente, verificando, ativa, congelada; configurando, perguntas, pronto), which is the actual behavior an agent must interpret.

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

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

Two sentences, front-loaded with what is returned and followed by the routing advice; nothing is redundant. The parenthetical state enumerations are dense but each value carries decision-relevant information for the agent.

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 must carry the return shape, and it does by naming every field and its possible states. It is complete enough to call and interpret, with the only gap being the unresolved overlap with `status`/`situacao_credencial`.

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 takes zero parameters, so there is no parameter semantics to convey and the baseline of 4 applies. The description correctly spends no words on arguments.

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 enumerates exactly what the tool returns: CNPJ, name, credential state, onboarding state, import and warnings, which is a precise resource statement. It is distinguishable from configurar_credencial and responder_perguntas_fiscais, but it never explains how it differs from the sibling tools `status` and `situacao_credencial`, which likely overlap heavily.

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?

"Comece por aqui" gives an explicit entry-point instruction, and the conditional branches (credential absent → configurar_credencial; pending questions → responder_perguntas_fiscais) route the agent correctly. What's missing is guidance on when to prefer this over `status` or `situacao_credencial` for credential information.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds what content is returned (stages, pendências, blocks), which is useful, but says nothing about empty-state behavior or ordering of the returned questions.

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 plus one action sentence — no filler. The telegraphic style ('e bloqueios.') is slightly terse but still parseable.

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 must convey the payload, and it names the three kinds of content an agent will receive. Minor gap: it doesn't say what an empty result means (onboarding complete / nothing pending), which matters for a pendências-style tool.

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

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

The tool takes zero parameters, so there is nothing for the description to compensate for; baseline 4 applies. The description correctly implies a parameterless consultation by describing only returned content.

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 enumerates what the tool surfaces — onboarding stages, fiscal questions the cadastro can't answer (Simples rate, apuração regime), and blocks — which is specific enough to distinguish it from siblings like status or minha_empresa. It lacks an explicit verb (list/retrieve), so the read nature is only implied by the noun phrase and the annotations.

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

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

It explicitly routes the agent to the alternative: 'Responda com responder_perguntas_fiscais', clearly separating consultation from answering. It does not state when this tool should not be called (e.g., no pending questions) or any prerequisites, keeping it short of a 5.

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

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

Annotations already declare write behavior (readOnlyHint false), idempotency, and non-destructiveness, and the description's "Grava" is consistent with that. It adds the meaningful "nunca invente" constraint, but does not disclose overwrite behavior, auth needs, or what happens to existing values on a partial save.

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 dense but efficient sentences front-load the write action and resources, then the value constraints and guardrail. Nothing is wasted, though the range and enum decoding make it somewhat information-packed.

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 two-parameter write tool with no output schema, the description covers both parameter semantics, their constraints, and the key guardrail about only using user-provided values. Only the save/overwrite outcome is left implicit, which is a minor gap given there is no output schema to explain returns.

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 adds real meaning beyond the schema: it supplies the valid range 0 < x ≤ 33 for the aliquot and decodes the otherwise-bare enum (1 = competência, 2 = caixa, 3 = outro). This compensates well for the 50% schema description coverage, only lacking the unit interpretation already hinted by the schema example.

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 concrete verb ("Grava") and names the two specific resources (alíquota do Simples Nacional and regime de apuração), which usefully corrects the potentially misleading name/title that sound like it returns answers. It is clear what gets persisted, though it doesn't explicitly contrast with the sibling perguntas_fiscais tool that presumably serves the questions.

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

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

Usage is only implied: the agent should call this when a person has supplied fiscal values, reinforced by the guardrail "Só com valores que a pessoa informou; nunca invente." There is no explicit when-not or comparison to perguntas_fiscais, so the when-to-use guidance is inferred rather than stated.

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 and destructiveHint=false, and the description does not contradict them. Beyond that it adds real behavioral value: the polling cadence and the mapping of next-step outcomes to the agent's expected action, which annotations cannot express.

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

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

Two sentences, front-loaded with the returned fields before the parenthetical value lists and the polling instruction. The enum lists are dense but each value earns its place by letting the agent branch on proximo_passo without a follow-up call.

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

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

There is no output schema, so the description carries the burden of describing return values, and it does so by enumerating both state families. The trailing ellipsis after 'bloqueada…' signals the list is non-exhaustive, leaving the agent to handle unknown states unguided, which is the only real gap for a zero-parameter status tool.

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

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

The tool takes zero parameters, so the schema baseline is 4 and there is nothing for the description to disambiguate. It correctly adds no parameter prose, keeping the focus on the return semantics instead.

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 precisely what is returned: the credential state and the last connection attempt, naming both fields (estado, proximo_passo). It never names a verb or a sibling, so an agent must infer that this is a read-only poll rather than a configuration action like configurar_credencial, but the enumerated return values make the scope 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?

It gives explicit operational guidance: poll every few seconds while the state remains 'aguardar', which tells the agent both cadence and the loop termination condition. It does not state when to prefer configurar_credencial instead, or what to do once proximo_passo leaves 'aguardar', so alternatives are left implicit.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond them by disclosing that no API key is required — a real behavioral fact an agent needs before credentials exist.

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

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

One short sentence plus a two-word qualifier, front-loaded with the main outcome. Nothing is wasted, though the 'Sem chave' fragment reads slightly abrupt.

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

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

For a no-parameter read-only health check with rich annotations and no output schema, the description covers what the agent needs: what is checked and that no authentication is required. A brief hint at the shape of the returned status 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline applies. No parameter information is missing.

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

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

The description states a specific check: whether 'emissaoja' is online and the health of the fiscal engine. It distinguishes itself from credential-related siblings like 'situacao_credencial' by naming the two subsystems it reports on, though it never explicitly contrasts with them.

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

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

Usage is only implied. The tag 'Sem chave' hints that this can be called before configuring credentials, which is a useful signal, but there is no explicit statement of when to prefer this over 'situacao_credencial' or 'acompanhar_operacao'.

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=false and destructiveHint=false, so the safety profile is covered. The description adds two genuinely useful behavioral facts beyond them: it performs no external lookup and requires no API key/credential, which matters given the configurar_credencial sibling. It does not describe the response shape (boolean vs. structured error), a minor remaining gap.

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

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

Two terse sentences, zero filler, with the core function stated first and the offline/no-key constraints following. Nothing could be removed without losing information.

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

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

For a one-parameter, read-only offline validator this is nearly sufficient: the agent knows what is checked, that nothing external is queried, and that no credential is needed. The only omission is how results are returned (valid/invalid flag, error detail), which there is no output schema to cover.

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

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

Schema description coverage is 100% and the single parameter is documented ('CNPJ com ou sem pontuação'), so the schema does the heavy lifting. The description adds only that formatting is checked, not anything about accepted input forms beyond what the schema states; baseline 3 applies.

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

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

States a specific verb (confere) and resource (formato e dígitos verificadores de um CNPJ), making clear this is a structural validation rather than a registry lookup. The phrase 'sem consultar nada' implicitly separates it from the sibling consultar_cnpj, though it never names that sibling 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?

'Sem consultar nada. Sem chave.' implies the when-to-use condition (offline/format-only checks, no credentials required), which a careful agent can map against consultar_cnpj. However, no sibling is named and there is no explicit statement of when NOT to use it, e.g. when real registry data is needed.

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