compras_perfil_fornecedor_completo

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

Annotations already establish readOnly/openWorld/idempotent/non-destructive hints, so the bar is higher — and the description clears it. It discloses parallel composition of four upstream sources, a configurable provider (CNPJ_PROVIDER, default brasilapi), partial-failure behavior when the CGU WAF blocks or the API key is missing, and a 10-minute cache. This is exactly the behavioral context annotations cannot express.

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?

Well-structured and front-loaded: the one-sentence purpose leads, followed by a scannable bullet list of data sources. The exclusion rationale, alternative, API-key caveat, and cache line each earn their place — no filler. The length is justified by the tool's genuine complexity (four parallel aggregations with distinct upstream dependencies).

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 aggregator with an output schema present, nothing an agent needs to call it correctly is missing: data source composition, upstream endpoints, provider configurability, the contracts exclusion with alternative, environmental dependencies, failure semantics, and cache duration are all covered. The output schema handles return-value documentation.

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% — the `cnpj` parameter is fully documented in the schema (format, length, punctuation allowed). The description reinforces that CNPJ is the lookup key across all four blocks ('pelo CNPJ' appears three times), which adds confirmation but no substantially new semantic information. Baseline 3 is appropriate given the schema carries the load.

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?

Opens with a specific statement of what the tool produces: 'Perfil consolidado do fornecedor (cadastro + Receita + sanções + impedimentos)' — a clear verb+resource definition. The four data components are enumerated in a bulleted breakdown, and the description explicitly states what the tool does NOT include (contracts), distinguishing it from sibling contract-listing tools.

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?

Gives explicit when-not-to-use guidance: contracts are excluded because upstream endpoints require `codigoOrgao`, and names the alternative directly: 'Se você já souber o órgão, use compras_contratos_listar(codigo_orgao=X, ni_fornecedor=Y, ...)'. It also flags the operational precondition that sanctions depend on TRANSPARENCIA_API_KEY and may degrade gracefully.

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