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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds significant value beyond these: it discloses that the tool is ASYNCHRONOUS (returns job_id requiring polling), returns TEMPORARY links that expire (nothing is archived), and notes empty list for processes without public decisions. It also clarifies it's a read-only fetch of public data per CNJ Res. 121/2010. The only minor gap is not detailing auth/captcha specifics beyond a passing mention.

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 dense but well-organized: it leads with the core action, then scope limitations, then async behavior and return format, then input sourcing and edge case. Every sentence adds value. Slightly long but for a complex async tool it's justifiable; each clause earns its place.

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 complex async tool with 4 parameters, 0% schema coverage, and no output schema, the description does substantial work: it covers the async pattern, return payload shape (markdown/pdf_url/expires_at), the polling sibling tool, the CNJ legal scope, and the empty-result edge case. Missing: no explicit explanation of peca_ids and tribunal parameters, and no detail on error cases beyond empty results. Strong but not perfect.

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%, so the description must carry the full burden for parameters. The description explains numero_cnj (source: processos_get_resultado/datajud) and formato (markdown/pdf implied by conversion to Markdown). However, peca_ids (array) and tribunal are not explicitly explained anywhere in the description. Despite a strong description, these two parameters remain undocumented.

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 downloads public decisions (acórdãos/inteiro teor) from a legal process, converts PDF to Markdown, and returns the decision text with a temporary link. It's very specific about verb (DOWNLOAD/busca/baixa/converte), resource (decisões públicas de um processo), and clearly distinguishes from siblings by stating it does NOT return full case files. The term 'processos_obter_pecas' is made concrete.

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 states when to use (for public decisions), when NOT to use (petitions/documents require lawyer credential), and mentions the polling pattern with processos_get_resultado(job_id). It also specifies the async nature (captcha per search), and guides on using numero_cnj from processos_get_resultado/datajud. This is exceptionally thorough for usage guidance.

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