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

Não há annotations, então a descrição carrega todo o ônus de informar efeitos colaterais e comportamentos. Ela diz que baixa XML e PDF, mas não esclarece se isso grava arquivos em disco, se sobrescreve arquivos existentes, se há necessidade de autenticação/empresa, nem como age quando a nota não é encontrada. Para uma operação que produz arquivos, essa ausência é uma lacuna relevante.

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 descrição tem duas frases curtas, sem repetir o que o título já diz e com a ação principal na primeira frase. A segunda frase traz apenas o pré-requisito crítico. Não há palavras desperdiçadas.

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?

Para um tool de download com 7 parâmetros e sem output schema, a descrição somada ao schema cobre o essencial para uma chamada correta: numero e o período que contém a nota. Ficam de fora detalhes sobre o retorno/gravação dos arquivos e orientação explícita de roteamento entre os irmãos, mas não há lacuna crítica que impeça o uso.

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?

A cobertura do schema é alta (86%) e os parâmetros já vêm bem descritos. A descrição agrega uma relação semântica útil ao afirmar que o período informado deve conter a nota procurada, o que ajuda a entender como preencher dataInicial e dataFinal em relação ao numero.

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?

A descrição usa verbo específico ('Baixa') e recurso claro ('XML e a DANFSe (PDF) de uma nota pelo numero'), deixando evidente o que a ferramenta faz. Ela se distingue intuitivamente das ferramentas de consulta como nfse_consultar_por_numero, mas não nomeia nem diferencia explicitamente irmãos próximos como nfse_obter_xml ou nfse_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?

A frase 'Precisa do periodo que contem a nota' comunica um pré-requisito importante para o uso correto. Porém, a descrição não diz quando preferir esta ferramenta em vez de alternativas como nfse_baixar_periodo ou nfse_obter_xml, nem apresenta exclusões; o contexto de uso fica apenas implícito.

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?

Sem anotações, a descrição carrega o peso da transparência. Ela informa que a operação baixa um lote de arquivos para uma pasta, mas não revela possíveis efeitos colaterais, como sobrescrita de arquivos existentes, necessidade de autenticação, limites de tamanho do lote ou comportamento em caso de erro.

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?

Duas frases curtas e objetivas, com a ação central no início e o contexto de uso logo em seguida. Não há redundância com o título nem com o schema.

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

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

O comportamento central está claro, mas a ferramenta tem 6 parâmetros, sem output schema e sem anotações. A descrição não menciona o formato da resposta, se retorna confirmação, caminhos gerados ou condições de falha, o que deixa lacunas relevantes para um agente que precisa invocar a ferramenta corretamente.

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?

A cobertura do schema é alta (83%), e o schema já documenta os parâmetros principais. A descrição apenas reforça a noção de período e competência, sem acrescentar detalhes novos sobre dataInicial, dataFinal ou tipoPeriodo além do que o schema informa.

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?

A descrição usa verbo específico ('Baixa'), recurso claro ('XML de todas as notas') e escopo definido ('de um periodo' para 'uma pasta'). Isso a diferencia dos irmãos nfse_baixar_nota e nfse_obter_xml, que lidam com notas individuais.

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?

A frase 'Ideal para escritorios de contabilidade fecharem a competencia de um cliente' oferece um contexto de uso concreto e identificável. Porém, não menciona explicitamente quando não usar ou quais alternativas escolher, como nfse_baixar_nota para um único documento.

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 no annotations provided, the description carries the full behavioral burden. It usefully discloses that the operation goes 'direto no portal da prefeitura (login/senha)', which signals authentication and a portal-based flow, and it gives accepted date formats. It does not disclose return shape, pagination, or whether any local download/storage side effect occurs, so the behavior is only partially 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?

The description is three sentences long and front-loads the core purpose in the first sentence. Additional details like date formats and the optional number range are useful and compact. The final marketing-style sentence about accounting offices adds some context but is slightly redundant with the stated 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?

For a listing tool with six parameters and no output schema or annotations, the description gives essential context: period scope, portal login/password, date formats, and optional filters. It lacks explicit statement of what the tool returns (data records? downloadable files?) and does not mention pagination or result limits. This makes it minimally viable but not fully 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 100%, so the schema already documents all six parameters, including enums, defaults, and formats. The description mostly repeats what the schema states, such as date formats and the optional number-range filter, without adding new semantic meaning beyond it. This matches the baseline of 3 for high 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 starts with a specific action and resource: 'Lista as NFS-e emitidas num periodo', which clearly distinguishes this from lookup-by-key/consult tools. It also adds the important 'portal da prefeitura (login/senha)' context. However, the final sentence about accountants 'baixarem as notas' creates mild ambiguity with the sibling nfse_baixar_periodo, so it stops short of a 5.

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

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

The description implies the use case with 'Ideal para escritorios de contabilidade baixarem as notas de um cliente' and signals period-based listing. It does not explicitly name alternatives such as nfse_consultar_por_numero or nfse_baixar_periodo, nor does it state when not to use this tool. Usage is therefore implied rather than explicitly guided.

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 present, so the description carries the burden of behavioral disclosure. It does state this is a read-only lookup on a 'base publica', which implies a safe query operation, but it does not mention auth needs, rate limits, response shape, or error behavior. Basic context is provided, but not rich 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?

Two sentences with no filler: the first states the core lookup purpose and example fields, and the second gives a practical usage tip. Every sentence earns its place and the key information is front-loaded.

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

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

For a single-parameter lookup with no output schema, the description adequately covers purpose, target data, and a concrete use case. Minor omissions like return structure or error conditions exist, but given the low complexity and sibling context, the description is largely sufficient.

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

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

Schema description coverage is 100%, so the schema already documents the single 'cnpj' parameter and its format. The description only restates 'pelo CNPJ' and adds no meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Busca') and resource ('dados cadastrais de uma empresa pelo CNPJ') with concrete examples like razao social and endereco. It is clearly distinct from siblings that consult by chave, numero, or id_dps, so an agent can differentiate it without opening schemas.

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

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

The description provides a clear use case: 'Util para preencher os dados do tomador antes da emissao.' This gives context for when to use the tool, though it does not explicitly name alternatives or state 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?

No annotations are present, so the description carries the burden. It transparently states this is a read-only consultation and specifies return behavior ('Retorna todos os dados da nota'). It also discloses an input tolerance: the key is accepted with or without spaces.

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

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

Three short sentences, each carrying meaningful information. The action and key criteria are front-loaded, and there is no filler or redundant restating of structured fields.

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 one-parameter query tool with no output schema, the description covers what it does, how the input may be formatted, and what the caller gets back. The main gap is not mentioning alternatives explicitly, but the key-based lookup is self-evident.

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 schema already fully documents the only parameter, so baseline is 3. The description adds the valuable normalization detail that the key can include or omit spaces, which improves an agent's ability to format the input correctly.

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 queries an NFS-e by access key, a specific verb plus resource and identifier. This distinguishes it from sibling tools like nfse_consultar_por_numero and nfse_consultar_por_id_dps, which use different lookup criteria.

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 phrase 'Metodo mais confiavel' implies this should be preferred when the access key is available, but it does not explicitly state when to use alternative lookup methods such as por_numero or por_id_dps. Guidance is implied rather than 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?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. The description only states the lookup action; it does not mention whether this operation is read-only (likely, given the name), whether any authentication or authorization is required, what the response format will be, or any error conditions. As a typical query tool, it's likely safe, but the lack of any behavioral detail beyond the action is a significant 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?

The description is a single, clear sentence that front-loads the purpose and includes an example format. It is minimal but complete for the purpose it serves. Every word earns its place; no fluff.

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 lookup tool with one parameter and no output schema, the description covers the essential purpose and parameter format. However, it lacks any indication of what the return value will be (e.g., full NFS-e details, an object, a reference), and does not mention any prerequisites or side effects. Given the operation's simplicity, the description is nearly sufficient, but the lack of return-content guidance makes it slightly under-specified.

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%: the single parameter 'idDps' is described as 'Id do DPS'. The description adds a concrete example ('DPS1100023...') which clarifies the expected format. Since the schema already documents the parameter, the description provides minor added value in the formatting example, but nothing more. This is a baseline 3.

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

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

The description clearly states the specific verb ('Consulta'), the resource ('uma NFS-e'), and the unique identifier ('pelo Id do DPS'), including an example. This distinguishes it from siblings like nfse_consultar_por_chave or nfse_consultar_por_numero, which target different identifiers. Even without reading the schema, an agent knows what this tool does and how it differs from other lookup tools.

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

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

The description implies the primary use case: fetching a specific NFS-e by its DPS id. It does not, however, explicitly state when to prefer this over alternatives (e.g., consulting by chave or numero), nor when not to use it. The sibling tool names imply the different identification methods, but the description offers no guidance on selection among them. This is a clear but not explicit 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?

With no annotations, the description is the only source of behavioral context. It conveys a read-only lookup scoped to the configured provider, but it does not describe response format, error/not-found behavior, or any side effects. For a simple query operation this is adequate but not deeply 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?

The description is two sentences with no filler: the main lookup mechanism comes first and the routing observation follows. Every clause contributes either the object of the query or a usage boundary.

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 two-parameter read operation, the description covers the lookup key, the configured-provider scope, and the relevant alternative for portal-issued notes. It does not state the return shape or error behavior, and there is no output schema, but these are minor gaps for this straightforward query.

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 already covers both parameters with descriptions, including the default for 'serie', so schema coverage is 100%. The description's reference to 'numero do DPS (e serie)' restates that coverage without adding new parameter-level meaning, so the baseline 3 applies.

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

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

The description uses a specific verb ('Consulta') with the resource ('NFS-e') and a precise lookup key ('numero do DPS (e serie) do prestador configurado'). It also distinguishes this tool from the sibling nfse_consultar_por_chave by explicitly scoping it to DPS number/series lookup.

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 states when the tool is appropriate (querying by DPS number/series for the configured provider) and gives an explicit exclusion: for notas emitidas pelo portal, prefer nfse_consultar_por_chave. This routes an agent to the right sibling without requiring schema inspection.

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 no annotations present, the description carries the burden and provides a notable security behavior: 'sem expor as senhas'. It also discloses that the data comes from clientes.json, giving implementation context beyond the empty 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 a single, focused sentence with no filler. The main action is front-loaded and the security qualifier is stated concisely.

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 zero-parameter list tool, the description provides the essential information: what is listed, where it is configured, and that passwords are not exposed. It does not specify the return shape, but the absence of an output schema and the low complexity make this a minor 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 tool has zero parameters and an empty input schema, so the description has no parameter semantics to explain. Per the calibration baseline, this merits a 4.

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 explicit verb 'Lista' and identifies the resource as 'empresas configuradas no clientes.json', making it clear this is a configuration listing operation. This distinguishes it from the sibling tools, which all target NFSe documents/status operations.

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 conveys that the tool lists configured companies, so an agent can infer it is the right tool for discovering available clients. However, it never explicitly states when to prefer it over sibling tools or mentions any exclusions/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?

With no annotations, the description carries the transparency burden and does disclose the output nature: raw XML in national NFSe layout. However, it says nothing about auth requirements, invalid-key behavior, or whether the XML is returned inline or as a file, leaving meaningful behavioral gaps.

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 with no filler. It front-loads the verb and resource, then immediately gives the lookup key.

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 one-parameter retrieval tool, the description names the required input and the return type sufficiently for a correct call. There is no output schema, so the explicit mention of 'XML bruto (bloco NFSe, layout nacional)' compensates; only error/not-found behavior is left unspecified.

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 schema already describes 'chave' as the 50-digit access key, and the description only restates that lookup is by access key. With 100% schema description coverage, the description adds no extra parameter semantics beyond what the schema 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 names a specific action ('Retorna o XML bruto') and a specific resource ('de uma nota pela chave de acesso'), making the tool's function immediately clear. It does not explicitly contrast itself with siblings like nfse_consultar_por_chave, so it falls short of full differentiation.

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 phrase 'pela chave de acesso' clearly identifies the required input and the conditions under which the tool applies: retrieving a specific invoice's raw XML by its access key. It does not mention when to prefer an alternative sibling, 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?

Sem annotations, a descrição carrega o peso de revelar comportamento. Ela comunica que é uma consulta aberta, sem autenticação, e que testa a conexão, o que implica leitura e ausência de efeitos colaterais. Não detalha o formato do retorno, mas isso é menos crítico para um tool de status.

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?

Duas frases curtas, sem redundância e com a ação principal ('mostra a configuração e testa a conexão') no início. Tudo na descrição contribui para o entendimento.

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?

Para um tool simples, sem parâmetros e sem output schema, a descrição cobre o essencial: finalidade, recurso e requisitos de autenticação. Faltam detalhes sobre o que exatamente o retorno contém, mas isso não impede a seleção correta.

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?

O tool não possui parâmetros e o schema já é completo (100% de cobertura com objeto vazio). A descrição não precisa explicar parâmetros; o valor adicional está apenas no contexto geral de configuração/conexã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?

A descrição usa verbo específico ('mostra' e 'testa') e recurso claro (WebService Nacional de NFS-e de Ariquemes). Diferencia-se dos irmãos, que são consultas/operações sobre notas, pois este é exclusivamente de status/configuração.

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?

A descrição informa que a consulta é aberta e não exige login nem certificado, o que contextualiza o uso. Porém, não diz explicitamente quando usar este tool em vez dos irmãos, nem sugere 'verifique a conexão antes de operações'.

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