Listar Seções da CNAE

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds valuable behavioral context by enumerating all 21 sections and their letter codes, which helps the agent anticipate the returned data domain without needing to call the tool. It does not specify exact return format, but the annotation coverage lowers the bar, and this is a simple read-only list.

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 first two sentences are concise and front-loaded, but the description then includes a long enumeration of all 21 sections with names. While informative, this duplicates what the tool likely returns and makes the description lengthy and less scannable. It could be shortened or moved to a more compact format, but it does provide quick reference value.

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?

With no output schema, the description should clarify return values. It states the tool returns the 21 sections with division counts and even lists the sections, giving a good sense of the data. However, it does not specify field names, structure, or whether pagination exists. For a simple read-only list tool, this is adequate but not fully complete.

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 tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the input schema confirms no parameters exist. The description's mention of using the section letter to filter ibge_cnae_buscar indirectly explains that this tool outputs letters for use elsewhere, which is helpful but not necessary.

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 lists the 21 CNAE sections with division counts, using a specific verb ('Lista') and resource ('seções da CNAE'). It also differentiates from sibling tools by explicitly mentioning that it can be used to discover the section letter for filtering ibge_cnae_buscar, making its purpose distinct.

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 provides explicit usage guidance: 'Use para ter uma visão geral da estrutura ou descobrir a letra de seção para filtrar ibge_cnae_buscar.' This indicates when to use the tool and how it relates to a sibling tool. It lacks explicit when-not-to-use instructions, but the context is clear enough for a simple list tool.

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