compras_buscar_contratacoes_similares

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

Beyond the readOnly/idempotent annotations, the description discloses important runtime behavior: three PNCP modality calls made in parallel, 30-60s per call, 60-90s total cold-cache latency, and <1s with Redis warm cache. It also explains the deduplication and ordering behavior. 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 well-structured and front-loaded: one-sentence summary, then composition details, then a bolded latency warning. Every sentence adds operational value; there is no filler or repetition of the tool name.

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 read-only, idempotent search tool with full schema coverage and an output schema, the description is nearly complete: sources, algorithm, ordering, use case, and latency are all covered. The main gap is that it never explicitly states that at least one of codigo_catmat or codigo_catser should be provided, even though all parameters are marked optional in the schema.

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 coverage is 100%, so the baseline is 3, and the description adds value by clarifying that codigo_catmat/codigo_catser identify the target item and that max_resultados applies after deduplication. It does not add much for uf or periodo_meses, but the schema already documents those adequately.

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 verb and resource: federating Dados Abertos + PNCP to find similar contracts ('contratações similares'). It distinguishes this tool from list/consult siblings by detailing the unique composition: filtering by CATMAT/CATSER, deduplicating by CNPJ + year + sequential, and returning the most recent max_resultados.

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 a clear intended use case: 'Insumo para mapear benchmarks de outros órgãos' (input for mapping benchmarks of other agencies). It does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5, but the usage context is clear.

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