read_pdf_as_text

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

No annotations are provided, so the description carries full burden. It discloses speed, low token consumption, limitation to text PDFs, and includes warnings for scanned PDF detection and truncation. The return structure is also described.

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 with separate sections for purpose, args, and returns. It is front-loaded with the main purpose and limitations. However, it is somewhat lengthy; slight trimming could improve conciseness without losing value.

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 the tool has 4 parameters and no output schema, the description fully covers the return dictionary, potential warnings, and parameter behavior. It addresses edge cases like scanned PDFs and result truncation, making it complete for the tool's complexity.

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%, but the description compensates with detailed explanations of pages, max_pages, and max_chars. The pages parameter is especially well-documented with multiple format examples. The file_path parameter is minimally described, but the schema title is clear.

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 extracts text content from PDFs, specifying it is suitable for text PDFs and distinguishing it from read_pdf_as_images for scanned PDFs. The verb 'extract' and resource 'PDF text' are specific, and the sibling differentiation is explicit.

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 provides explicit guidance: suitable for text PDFs, not for scanned PDFs, and recommends the alternative tool read_pdf_as_images for scanned PDFs. It also explains the pages parameter in detail, helping the agent understand how to use it correctly.

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