pdf_to_markdown

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

With no annotations, the description must carry the behavioral load, and it does disclose meaningful traits: the output transformation (reflow, hyphenation, page separators) and a concrete cost model ('$0.01 PER PAGE'), which matters for large PDFs. It omits auth/permission requirements, error behavior, and idempotency/repeat-call behavior, so it falls short of fully covering a no-annotation mutation-adjacent tool.

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?

Three tight sentences, front-loaded with what the tool produces, followed by use cases, the OCR caveat, and the price. Each sentence earns its place; nothing is restated from the schema or title.

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?

With 7 parameters, no output schema and no annotations, the description is complete on purpose, cost and OCR routing but silent on page-range extraction, output destination, and idempotency-key usage. An agent can call it for the basic case but lacks guidance for the pagination and file-writing options the schema exposes.

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 only 29% – file, first_page, last_page, output_path and idempotency_key carry no descriptions. The prose partially compensates by explaining the reflow-vs-layout behavior and that output is Markdown text, but it never mentions pagination ranges, the output_path destination, or idempotency, leaving most parameters unexplained.

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?

States a specific verb+resource ('Extract the text of a PDF ... as clean Markdown') and goes further by naming the transformation guarantees (reflowed paragraphs, resolved hyphenation, page rules). It also distinguishes itself from the OCR sibling by noting scanned PDFs need ocr first, so an agent can tell it apart from pdf_to_images, pdf_extract_tables and ocr without opening a schema.

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 frames intended uses (summarising, RAG ingestion, further processing) and gives a clear exclusion with a named alternative: 'Scanned PDFs need ocr first.' That is the when, the why, and the routing rule in two sentences.

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