Classificação CNAE

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details beyond the annotations: it states the operation is a live GET against the public IBGE CNAE API and that it returns Markdown. This gives the agent useful execution expectations without contradicting the 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 with purpose, followed by useful hierarchy details, feature bullets, and concrete examples. It is slightly longer than strictly necessary, but every section earns its place by helping the agent understand CNAE levels and how to invoke the tool correctly.

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 lookup tool with four optional parameters, all documented in the schema, plus an output schema, this description is thorough. It covers the domain, the hierarchy, all main query patterns, example values, and the Markdown return format. Minor gaps such as rate limits are not critical given the annotations already establish safety and idempotency.

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 each parameter already has a clear Portuguese description with examples. The tool description reinforces the usage by providing hierarchical context and sample codes like '6201-5/01' and codigo='J', but it does not add substantial semantic meaning beyond what the schema already provides. A 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 opens with a specific verb and resource: 'Queries CNAE (National Classification of Economic Activities) from IBGE.' It clearly defines the domain and differentiates it from sibling IBGE tools, which cover other datasets. The hierarchy breakdown further clarifies exactly what kind of data the tool returns.

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 clear context for when to use it: anytime an agent needs Brazilian economic activity classifications. It lists concrete usage patterns (search by code, by description, list by level) and examples. It does not explicitly name sibling exclusions, but the domain is specific enough that confusion with siblings like ibge_sidra or ibge_paises is unlikely.

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