ler_documento_judicial

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

No annotations are provided, so the description carries full behavioral disclosure. It explains truncation via max_chars, pagination via pagina_inicial, PDF caching for continuation, detection of PJe IDs, and the behavior for scanned attachments (empty response with a warning). This is rich, specific, and goes beyond basic operational details.

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 well-structured in three short paragraphs: purpose and ID source, long-document behavior, and scanned attachment edge case. Every sentence adds value, with no redundant repetition of schema or annotations.

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?

The description is complete given the tool's complexity and lack of annotations. It covers edge cases (long documents, scanned attachments), explains key output behaviors (truncation, pagination, PJe detection), and provides alternatives. With an output schema present, detailed return values are not necessary here.

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 0% schema coverage, the description adds meaning to several parameters: max_chars is tied to truncation, pagina_inicial to continuation, and documento_id to the list function. It does not explain soap_setting_id, but it compensates well for the parameters that matter to the user.

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's function: extracting text from a judicial document without saving the file. It specifies the resource type (document in the case folder) and distinguishes it from siblings like baixar_documento_judicial (download) and listar_documentos_judiciais (list).

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 explicitly instructs to use listar_documentos_judiciais to obtain the document ID, and for scanned attachments without a text layer, it directs users to baixar_documento_judicial for OCR. This provides clear when-to-use and alternative guidance.

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