compras_pncp_contratacoes_atualizacao

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

Annotations are entirely absent, so the description must disclose behavioral traits. It reveals that the 'esfera' filter is applied client-side and notes that '_total_registros' reflects unfiltered totals—key behavior. It also mentions a 15-minute cache. However, it omits important details like whether results are paginated fully, if the endpoint has rate limits, or if it returns all changes within a date range or only a subset, which would be valuable for agents deciding to paginate or cache.

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 very concise: three short sentences that tell the user exactly what the tool does (list updated contracts), why it's useful (monitoring retifications/republications), and a key behavioral note (client-side filter and cache). Every sentence adds value, no filler. It is well structured with a clear purpose statement, a usage context, and a technical note.

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?

Given the tool has an output schema (context signal true), the description does not need to explain return values. With 6 parameters (3 required) and a straightforward purpose (listing updated contracts), the description covers the main use case and the client-side filter nuance. It lacks mention of any constraints like maximum date range, which might be important, but overall it provides sufficient completeness for an agent to decide and invoke the tool 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 100% (all 6 parameters have descriptions in the schema), so the baseline is 3. The description adds significant value beyond the schema by providing context: 'esfera' has a note about client-side application and its effect on '_total_registros'; 'codigo_modalidade' lists common codes with examples (1=Leilão Eletrônico, etc.). This extra guidance helps the agent select and fill parameters correctly, raising the score above baseline.

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 specifies the verb 'Lista' (lists), the resource 'contratações alteradas' (altered contracts), and the scope 'no período' (in the period). The endpoint and purpose for monitoring (discovering retifications/republications) are explicit, and the tool is well-differentiated from siblings like 'compras_pncp_contratacoes_publicacao' (publications) and 'compras_pncp_contratacao_por_orgao' (by agency), which cover different slices.

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 indicates the tool is useful for monitoring changes (retifications/republications), which implies when to use it—tracking updates over time rather than static data. However, it provides no explicit guidance on when NOT to use it, such as for accessing the latest publication or original contract data, nor does it list alternative tools for those purposes. The mention of client-side filtering hints at a limitation but not a clear exclusion.

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