Buscar/listar NFS-e por periodo (portal)

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.