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

The description goes well beyond the readOnly/idempotent annotations: it discloses that termo is deliberately not sent to the upstream endpoint (sending it would return ~340k items), that the tool emits _aviso_filtro when the structural cut is too broad, and that results are cached for 24h. However, the input schema's termo description ('Aceita fragmento — a API faz match parcial') directly contradicts the main description's 'Não existe busca por substring nesta API', giving the agent two opposing models of the tool's core behavior.

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?

Every sentence earns its place: the critical warning is front-loaded, the explanation of why termo is not sent upstream prevents a costly mistake, and the workflow and cache notes are compact and actionable. Though long (~230 words), the length is justified by the counter-intuitive behavior it must convey, and the emoji/bold formatting makes the warning stand out.

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 rich annotations, 100% schema coverage, and an existing output schema, the description covers all essentials and even adds payload-level behavior (_aviso_filtro) and cache semantics. It falls just short of complete because the conflicting termo semantics between the schema and the description are never reconciled, which could mislead an agent at invocation time.

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?

With 100% schema coverage the baseline is 3, but the description adds decisive meaning beyond the schema: termo's real role (ordering/marking, not filtering) is only explained here, and it reinforces codigo_pdm as the most precise cut and codigo_grupo as strongly recommended. The gain is offset by the schema's contradictory claim that termo does partial matching, which muddies the semantics of the only required parameter.

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 opening line 'Busca itens CATMAT' states a specific verb and resource, and the body sharpens the purpose: this tool searches the CATMAT catalog using structural filters (codigo_grupo, codigo_classe, codigo_pdm), with termo used only for ordering/marking results. The workflow explicitly names sibling tools (compras_catmat_listar_grupos, compras_catmat_listar_classes, compras_catmat_listar_pdms), distinguishing it from neighboring catalog tools.

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 'Workflow recomendado' section gives an explicit 4-step sequence that names the sibling tools and lands on this tool, telling the agent exactly when to call it. It also marks codigo_grupo as FORTEMENTE RECOMENDADO because the upstream text filter is broken, and states what NOT to expect (no substring search, termo never sent upstream), leaving no ambiguity about when this tool is appropriate.

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