compras_fornecedor_cnpj_receita

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

With no annotations provided, the description carries the full burden. It discloses caching (24h), error behavior (404/upstream errors return encontrado=false with _erro), and data source (BrasilAPI/MinhaReceita). It implicitly indicates read-only via 'consulta'. However, it does not explicitly state that the tool is read-only or has no side effects, which would be a minor improvement.

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: first line states purpose, then lists return fields, followed by usage guidance, note about sanctions, and caching/error behavior. Each sentence is necessary and contributes to understanding. No wasted words.

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 single parameter, clear output (output schema exists), and many sibling tools, the description covers all key aspects: what it returns, when to use it, how it differs from other tools, data source, caching, and error handling. The agent has enough information to decide when and how to invoke this 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?

The schema already has 100% coverage with a description for the cnpj parameter. The description adds value by specifying the exact format (14 digits, with or without punctuation) and mentioning the provider switching via environment variable. This goes beyond the schema, but the schema already handles the basics, so the additional info is welcome but not critical.

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 the tool returns public CNPJ data from Receita Federal, lists specific return fields, and explicitly distinguishes from sibling tools like compras_perfil_fornecedor_completo and sanction tools. The verb 'consulta' and resource 'Dados públicos do CNPJ' are specific and unambiguous.

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 includes a 'Quando usar' section that tells when to use this tool (due diligence complement of compras_perfil_fornecedor_completo) and explicitly says not to use it for sanctions, directing to sanction tools. It also mentions cache duration and error handling behavior, providing clear when-to and when-not-to guidance.

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