buscar_normas_cvm

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

With no annotations present, the description carries the full burden and does so well: it discloses that the source is a live portal index, that act text is only captured when indexed, the three possible statuses (ok | parcial | indisponivel) and their meaning, that nao_indexado items assert nothing about vigência, that a declared revocation on the act page blocks validity, and that it may write a local cache. Failure modes, partial-result semantics and a side effect are all surfaced before invocation.

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?

Front-loads the purpose in the first clause, then layers source, result semantics, parameter note and routing advice. Dense and telegraphic with some sentence fragments ('Item nao_indexado não tem captura nem afirma vigência'), but essentially every clause carries operational information and none is redundant.

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?

An output schema exists, yet the description still usefully explains the candidate/status model and the non-indexed caveat, plus the cache write and jurisprudence routing — enough for correct invocation and result interpretation. The one real gap is the unstated value space for `tipo`, which leaves the agent guessing at a required input format.

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 0% for 2 parameters, so the description must compensate. It explains `tipo` only at the level of 'restringe a espécie' — never enumerating the accepted values, so an agent cannot construct a valid `tipo` string from the definition. `q` is left entirely implicit, though its meaning as the query string is inferable from the verb.

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?

States a specific verb and resource ('Busca normas no portal oficial da CVM') and enumerates the covered species (resoluções, instruções, pareceres de orientação), so the agent knows exactly what corpus is searched. It explicitly routes Collegiate decisions to pesquisar_jurisprudencia, distinguishing itself from one sibling, but says nothing about how it differs from buscar_legislacao or buscar_normas_bcb, which occupy adjacent territory.

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 a concrete alternative with its triggering condition ('Decisões do Colegiado são jurisprudência: use pesquisar_jurisprudencia') and explains that `tipo` narrows the species. It also warns that an 'indisponivel' status is a portal/network/offline failure and NOT an empty result set, which is exactly the kind of usage guidance that prevents misinterpretation. No explicit guidance on when to prefer buscar_legislacao, so it stops short of a 5.

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