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

Goes well beyond the annotations: discloses that the call consumes external credit (classe 2), that it first returns a cost preview, that execution requires identical arguments plus confirmacaoToken after explicit lawyer confirmation, that replaying a confirmed token returns the cached result with no new charge, and that a new preview constitutes a new request. It also states a saved peça is returned without re-downloading, consistent with idempotentHint=true and openWorldHint=true.

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-loaded with the two actions before the cost/confirmation mechanics and the free-monitoring escape hatch, and every sentence carries actionable content. It is dense and long-chained in places ('Reenviar o mesmo token... Nova prévia e confirmação são um novo pedido'), but no sentence is filler.

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 paid, two-mode, open-world tool with no output schema, the description covers cost, confirmation, idempotency, polling cadence, and handoff to sibling tools. It stops short of describing what a buscar result looks like versus a baixar result, or what happens when the tribunal returns nothing, so an agent still lacks a complete mental model of outcomes.

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 50% schema coverage and 6 parameters, the description adds real meaning for key (opaque, from listar_pecas, never show the lawyer) and reinforces the confirmacaoToken contract, which the schema only briefly notes. However, titulo, extensao, and processoId get no explanation anywhere, leaving a meaningful gap the description should have closed.

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?

Names two specific operations (buscar autos no tribunal / baixar UMA peça) with concrete scope, and ties each to a source (listar_pecas com fonte tribunal). It does not, however, distinguish itself from the sibling buscar_autos, whose name suggests an overlapping purpose, nor from checar_peca — so the agent gets an accurate but not fully discriminating picture.

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?

Explicitly routes the agent to free alternatives for monitoring ('Acompanhe sem gastar usando processo_status com consultarTribunal true e listar_pecas com fonte tribunal') and to listar_pecas/ler_paginas for reading imported documents after ingestion. It also states the waiting condition (status gratuito indicando busca em andamento, aguarde) and the 30-second polling cadence, which is exactly the when/when-not guidance expected.

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