ler_documento_pr

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

The description goes well beyond the annotations by disclosing concrete behavioral constraints: PDF page limits, XLSX 100-row block selection, offset/limit pagination, a 20 MiB download cap, no OCR, and no P7S signature validation. This gives an agent realistic expectations about limitations and failure modes. It is consistent with the readOnlyHint, idempotentHint, and openWorldHint annotations.

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 compact and front-loaded: the first sentence states the core purpose, and the following sentences pack limitations and pagination rules into short, scannable segments. There is no filler, no repetition of schema defaults, and every sentence adds distinct information.

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 read-only tool with five parameters, annotations, and an output schema, the description covers the essential operational details: supported formats, public URL scope, per-format pagination, download size cap, non-capabilities, and response metadata. Minor ambiguities remain about how 'pagina' applies to non-PDF/XLSX formats and the exact semantics of 'limite', but these are not blocking. Overall, the definition is sufficient for correct invocation.

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 compensate, and it largely does: 'pagina' and 'paginas' are explained for PDFs, 'pagina' is mapped to XLSX 100-line blocks, and 'deslocamento'/'limite' are tied to extracted-text pagination. The main gaps are the exact unit of 'limite' and the precise URL format requirements, but the default values and surrounding context reduce ambiguity.

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 opens with the specific verb 'Lê' (reads) and enumerates concrete resource types: PDF, DOCX, XLSX, CSV, JSON, XML, and text from public TCE-PR URLs. This makes the tool's function clear and distinguishes it from the many query-oriented sibling tools. It does not explicitly distinguish from 'ler_pagina_portal_pr', so differentiation is mostly implied rather than stated.

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 clearly implies when to use the tool: to read and extract text from public documents and URLs. However, it never explicitly says when not to use it or names an alternative for structured queries, such as consultar_base_pr or consultar_processo_pr. Usage context is present but alternative routing is left to inference.

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