Baixar XML de uma NFS-e

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.