consultar_novo_mural_pr

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavior beyond that: it reads records via HTTP Range, discovers a ZIP from Power BI's open data section, requires an extra browser to find the source, clarifies cursor semantics ('número de registros já examinados, não página'), and explains filter normalization. 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?

The description is dense but every sentence earns its place: scope, source mechanism, type variance, filter semantics, cursor meaning, external dependency, and an explicit exclusion. It is front-loaded with the core purpose and avoids redundant restatement of the tool name or 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?

For a complex tool with an output schema already present, the description covers the key operational details: where the data comes from, how it is read, what the two modes mean, how filtering and cursor work, and the prerequisite to discover the source. The output schema relieves the description from explaining return values, so nothing critical 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 description coverage is 0%, so the description must compensate. It meaningfully explains tipo, filtros, and cursor, and gives a discovery strategy for the fields. However, 'ano' and 'limite' are not explicitly explained, and the filter object's expected keys are left to be discovered, so it is strong but not fully complete.

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 verb and resource: 'Consulta CSV oficial do NOVO Mural, editais a partir de 01/05/2026.' It clearly distinguishes the two modes via tipo='itens' and tipo='licitacoes', and adds an explicit contrast with 'Não mescla o CSV tradicional,' helping an agent separate it from sibling tools 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 gives practical usage guidance: 'Primeiro consulte sem filtros para descobrir os campos' and explains how filters behave ('substrings sem acentos combinadas por E'). It also warns about the need for an extra browser and what the tool does not do. It does not explicitly name alternative sibling tools, but provides enough context to route usage.

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