compras_fornecedor_consultar

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond those: the specific Dados Abertos endpoint, the return fields, and the 1-hour cache behavior. No contradictions with annotations; the additional context earns a strong score.

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?

Four short sentences, each carrying distinct information: purpose, endpoint, return fields, and cache behavior. No filler or repeated content, and the core purpose is front-loaded.

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 single-parameter read-only query with a fully documented schema, an output schema, and annotations covering safety, the description is complete. It tells the agent what will be returned, where the data comes from, and caching behavior. Nothing essential 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 100%, and the schema already explains the CNPJ/CPF format and punctuation tolerance. The description reiterates that the lookup is by CNPJ or CPF but adds no extra parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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 states a specific verb (consulta) and resource (cadastro de fornecedor) filtered by CNPJ/CPF, and lists the returned data fields (razão social, CNAE, porte, natureza jurídica). It does not explicitly contrast itself with supplier-related siblings like compras_fornecedor_cnpj_receita, but the endpoint and field list give enough specificity.

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 context is explicit: use this tool to query supplier registration data by CNPJ or CPF. It does not mention alternatives or exclusions, but the query criterion and returned fields make the intended use case clear. Given the many sibling tools, some when-not guidance would improve it, but it is not ambiguous.

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