PDF & Office Tools (Tanod)

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

Beyond the annotations (destructive=false, idempotent=true, openWorld=true), it discloses hard limits (100 slides, 2,000 chars per text, 250,000 per deck), the 422 error behavior and that failures aren't charged, price USD 0.005 with no free tier, sub-1s latency, and an untrusted-content warning. That is unusually rich behavioral context an agent cannot infer from structured fields.

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?

Front-loaded with purpose and sibling routing, then packs limits, output format, pricing, and safety into a compact block. It is dense but nearly every sentence carries operational value; only the docs URL and some schema restatement are slightly redundant.

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?

Covers limits, error behavior, pricing, latency, output shape, and a prompt-injection caveat, and an output schema exists so return values need no further explanation. An agent has everything required to call it correctly and set expectations.

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 coverage is 100%, so the baseline is 3; the description still adds value by restating the meaningful constraints (20-bullet cap, layout choices, theme font/accent_color) and clarifying that output=url yields a 24 h link. It mostly mirrors schema detail rather than adding new semantics, so it sits just above baseline.

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 and resource ('Generate a PowerPoint deck from JSON slides') and immediately scopes the inputs (titles, bullets, speaker notes). It explicitly distinguishes itself from build_xlsx_workbook and fill_docx_template, so an agent can route correctly among the output-format siblings.

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?

Names the two alternative tools by name and the condition that selects them (workbook -> build_xlsx_workbook, Word file -> fill_docx_template), and clarifies the tool is text-only with no images. The remaining ambiguities are minor because the sibling routing is explicit.

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

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

Annotations only give the safety profile (readOnly=false, destructive=false, idempotent=true); the description adds the operationally important facts: hard limits (20 sheets, 50,000 cells, 32,767 chars/cell, 31-char sheet names without [ ] : * ? / \), that exceeding them is a 422 and not charged, that strings are never interpreted as formulas, expected latency under 1 s, and a price of USD 0.005 with no free tier.

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 core action and sibling routing are front-loaded, then limits, error behavior, latency and price in a compact run of sentences. Dense but every clause carries information an agent needs; only the docs URL feels like appended boilerplate.

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 single-call generation tool with a full output schema, the description covers what remains unaddressed elsewhere: quotas, failure mode and its billing implication, latency, cost, string-as-text semantics, and a docs link. Nothing needed to invoke it correctly is missing.

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 100%, so the baseline is 3; the description still adds value by spelling out the column `type` enum and clarifying that a type sets the cell number format. It repeats rather than extends most other parameter detail, so it does not push to a 5.

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?

Specific verb + resource (build a styled Excel workbook from JSON sheets, columns and rows), and it explicitly names the inverse tool (convert_excel_to_json) and the sibling for slides (build_pptx_deck). An agent can tell this apart from every other build/convert tool in the family 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?

It routes the agent explicitly: read-back goes to convert_excel_to_json, slides go to build_pptx_deck, and it documents format/limit constraints that determine whether it can be used at all. It stops short of stating when-not-to-use conditions beyond those alternatives, so it lands just under a 5.

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

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

Goes well beyond the annotations: page/size limits, the 2,000-change cap, how tracked changes are treated ('read as accepted'), which failures produce 422/413 and that they are not charged, latency (1-3 s), price (USD 0.01, no free tier), 24 h link expiry, and an explicit prompt-injection warning about returned text. This is exactly the extra context annotations cannot convey.

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?

Front-loaded with the action and the key alternative, and every clause carries information (limits, errors, pricing, safety). It is a single dense block rather than a structured list, which makes the pricing/limits details slightly harder to scan.

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?

Return shape is described (summary plus changes with before/after and word_diff), and limits, error codes, cost, and delivery modes are all covered. An agent has everything needed to decide, call, and interpret the result.

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 coverage is 100%, so baseline is 3, but the description adds real meaning: changes are reported going from a to b, the redline file lands in `file`, and delivery=url yields a 24 h link. The a=older / b=newer framing is duplicated from the schema, keeping it short of a 5.

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 and resource ('Compare two PDF or Word documents') with the output artifacts named (changed paragraphs/rows, word diff, redline). It explicitly demarcates the plain-text case to a sibling 'diff_text', so an agent can route without opening either 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?

Clear routing guidance for format selection ('For two plain texts use diff_text') and for output=docx/pdf and delivery=url variants. It does not address overlap with the many other PDF siblings (e.g. extract_pdf, convert_pdf_to_word), but the intended use context is unambiguous.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true and destructiveHint=false, and the description is consistent with all of them. Beyond that, it discloses row reconciliation against the running balance, supported formats and layouts, scanned-PDF failure behavior, OFX/QIF year requirements, page and payload limits, pricing, logging/retention behavior, runtime expectations and prompt-injection caution.

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 front-loaded: purpose and sibling alternative come first, then outputs, formats, constraints and pricing. Every sentence carries operational information, and the length is justified by the tool's many behavioral constraints.

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?

An output schema exists, so return values do not need full explanation, but the description still names the key returned fields and reconciliation behavior. For a complex PDF-to-transactions tool with limits, pricing, retention and security concerns, the description covers everything an agent needs to call it correctly.

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 already 100%, so the schema does the heavy lifting for url, pages, format, output and file_base64. The description adds some useful context such as output=url retention and OFX/QIF date behavior, but it mostly restates constraints already present in the schema and does not add substantial new semantics for most parameters.

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 and resource: turn a PDF bank statement into dated transactions for bookkeeping or import. It explicitly distinguishes itself from the sibling extract_pdf_tables for other table types, so an agent can choose correctly without opening either 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?

Gives an explicit use condition (bookkeeping or import) and a direct alternative for other tables: extract_pdf_tables. It also states the prerequisite for scanned statements, namely that a 422 no_text_layer means OCR should be run first, which is exactly the kind of when-not guidance an agent needs.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds material behavior: price USD 0.005 with no free tier, 500,000-character truncation tied to a `truncated` flag, 100-page PDF cap, 415 vs 422 error mapping with no charge on failure, typical 1-5 s latency, and a prompt-injection warning about returned page text and on-chain strings. These are exactly the operational traits annotations cannot express.

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?

It is information-dense with little true padding, but the opening leads with "Price: USD 0.005; No free tier" ahead of the actual purpose, and the body is a chain of sentence fragments ("No automatic OCR.", "Unsupported: 415"). The content earns its place; the ordering and telegraphic syntax make it harder to scan than it needs to be.

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 multi-format conversion tool with five optional parameters, an output schema, and rich annotations, the description covers formats, size/page limits, truncation, error classes, latency, cost, and the OCR escape hatch. Nothing an agent needs in order to call it correctly or interpret failure is missing.

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 100%, so all five parameters including both enums are already documented in structured form. The description chiefly restates `reading_order` (auto/columns) and mentions `columns_detected` in the return, but adds little parameter meaning beyond the schema – notably it never explains `merge_mode` semantics. Baseline 3 is appropriate.

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 (convert/read a document to Markdown) and enumerates the supported input formats (Word, Excel, PowerPoint, PDF, HTML, EPUB). It also differentiates from the closest sibling by naming extract_pdf_tables for table-shaped output, so an agent can pick between them 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?

Gives an explicit use condition ("Use when an agent must read a ... file as Markdown text") plus two exclusions with alternatives: PDF tables as rows go to extract_pdf_tables, and documents with no text layer require the separate /v1/pdf/ocr route, with the explicit caveat "No automatic OCR." That is when-to-use, when-not, and where-to-go-instead in one place.

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

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

Beyond annotations, it discloses return behavior (string rows, cached values, trailing empties trimmed), formula metadata limits, sheet-index collision risk, truncation flags, cache freshness caveats, refusal of ZIP bombs/XML entities, caps, latency, pricing, and untrusted-output handling. These are substantial operational details for safe invocation.

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 purpose is front-loaded in the first sentence, and most following sentences carry useful constraints, limits, or caveats. The description is dense and somewhat run-on, but for a tool with many caps, error modes, and security notes, it is appropriately information-rich rather than padded.

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?

Although an output schema exists, the description still supplies key behavioral expectations: row stringification, formula metadata behavior, truncation and scope flags, unsupported-format errors, caps, and cost. This is complete enough for an agent to call the tool correctly and interpret the main edge cases.

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 100%, so parameter semantics are already well served by the schema. The description adds some context about url/file_base64, format, and formula_metadata, but omits output and merge_mode from its input summary, so it does not materially deepen parameter meaning beyond the schema.

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 states a specific verb and resource: reading an Excel workbook into structured rows as JSON or one CSV per sheet. It explicitly distinguishes itself from the sibling tool that creates workbooks, build_xlsx_workbook, so an agent can identify the conversion direction without opening the 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?

It names build_xlsx_workbook as the alternative for the reverse operation and clearly limits inputs to .xlsx/.xlsm with 422/415 behavior for unsupported or encrypted files. It does not comprehensively route among all conversion siblings, but it gives enough context to select this tool for workbook-to-data conversion.

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

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

Far beyond the annotations, it discloses LibreOffice rendering differences, font substitution (Liberation, DejaVu), CJK missing-glyph boxes, that macros never run, that nothing is fetched, which link schemes are stripped, output size limits (413), encrypted/damaged files (422, uncharged), typical 2-10 s latency, price USD 0.01, and an explicit prompt-injection caution about returned text. This is exactly the extra context annotations cannot carry.

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?

Purpose and the reverse-direction pointer are front-loaded, and despite being a dense block nearly every clause carries actionable facts (formats, error codes, timing, price). It is long but not padded; a slightly more scannable structure would earn a 5.

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?

Even though an output schema exists, it names the returned fields (file, format, pages, active_content_removed) and covers cost, latency, failure modes and safety caveats. An agent has everything needed to call this correctly and interpret the result.

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 100%, so the schema already documents url, output, filename and file_base64 thoroughly, including defaults and limits. The description adds little parameter-level detail — 'No options' is about conversion settings rather than the schema fields, and the format-detection behaviour is already in the schema. Baseline 3 applies.

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 and resource ('Convert a Word, Excel, PowerPoint, OpenDocument or RTF file to PDF') and names the reverse sibling convert_pdf_to_word, so an agent can separate it from convert_pdf_to_word and the many pdf_* siblings without opening any 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 enumerates the accepted input types (DOCX, XLSX, PPTX, ODT, ODS, ODP, RTF, text) and the rejected ones that return 422 (PDF, images, legacy .doc/.xls/.ppt, HTML, EPUB), and routes the opposite direction to convert_pdf_to_word. When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is known; the description nevertheless adds substantial beyond-schema context: LibreOffice-produced text-box-per-line output that is not reflowable, table/link/form fidelity loss, error mapping (422 too dense/encrypted, 413 oversized output, 503 timeout), 2-20 s latency profile, price and no free tier. It stops short of describing pagination or partial-failure semantics in the response body. With annotations already covering safety, a 3 fits.

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?

Front-loads the purpose and sibling routing, then layers limits, latency, pricing and security. Every sentence carries real information, but the middle section is dense and run-on (error codes, timing model and price chained with semicolons), which slightly hurts scanability.

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?

An output schema exists, so return values needn't be fully enumerated, yet the description still flags the crucial structural caveat (positioned text boxes, not reflowable paragraphs) that an agent must know before routing a downstream editing task here. Limits, failure modes, cost and a prompt-injection warning make it complete for a paid, open-world conversion tool.

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 100%, so the baseline is 3. The description's only parameter-adjacent additions are 'Add output=url for a 24 h link' and the 50-page/parts note for pages, both of which the schema already states (output enum documents url as 24-hour storage; pages documents 'at most 50 per call'). It adds no syntax or format meaning beyond the schema.

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 and resource ('convert a PDF to Word (.docx) for editing') and explicitly distinguishes itself from two siblings, convert_office_to_pdf (reverse direction) and convert_document_to_markdown (plain text). An agent can pick this tool without opening any 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?

Gives explicit routing rules to alternatives, states the prerequisite for scanned PDFs (OCR first) and encrypted inputs (unlock first via pdf_unlock), and names the condition that splits work across calls ('pages converts in parts'). When-to-use and when-not-to-use are both covered.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations: discloses pricing (USD 0.005), free-tier limits (5 static renders/IP/day), latency (0.5-3 s), truncation at 200k chars, 422-not-charged behavior for encrypted/non-PDF/private URLs, and the untrusted-data injection warning. This is exactly the context annotations cannot carry.

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?

Dense but front-loaded: purpose and routing come first, then input contract, then returns, then failure modes and price. Nearly every clause earns its place, though the run-on density makes it slightly harder to scan than ideal.

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 an output schema present, the description still surfaces the return fields most likely to affect downstream use (truncation flag, columns_detected, size/token estimate, empty url/final_url for inline input). Nothing an agent needs to call it correctly is missing.

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 coverage is 100%, so the baseline is 3; the description adds genuine meaning on top by stating 'exactly one of url or pdf_base64' (mutual exclusivity not obvious from the schema) and explaining column-by-column reading and reading_order effects. Not a full parameter walkthrough, but meaningfully beyond the schema.

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') and extends it with metadata. Explicitly names the sibling alternatives for tables, scans, and other formats, so an agent can route 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?

Names alternative tools with their selecting conditions (tables → extract_pdf_tables, scans → pdf_ocr, other formats → convert_document_to_markdown) and adds a fallback rule: if the URL fetch fails, send bytes as pdf_base64 rather than retrying. Effectively full routing guidance.

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

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

Far beyond the annotations: discloses page caps (200 selected / 500 total), size limit (5 MB JSON → 413), specific 422 error codes (no_text_layer, no_tables_found, pdf_too_complex, none charged), latency (1-10 s), price (USD 0.01, no free tier), and an untrusted-data warning. The header/rows separation is a genuine behavioral nuance not derivable from 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?

Front-loaded with the use case and alternatives, then limits, then pricing — a sensible order. Dense and every line carries information, though the error-code enumeration is packed tightly enough to be slightly hard to scan.

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 paid, error-prone extraction tool with an output schema, the description covers return shape, error taxonomy, cost, timing, and limits. An agent has everything needed to decide, call, and interpret failures.

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 coverage is 100%, so the baseline is 3; the description goes further by clarifying that csv yields one file per table, xlsx yields one workbook with a sheet per table, and that the detected header lives in `header` rather than `rows`. It doesn't re-explain url/file_base64 alternatives, but the schema already does that well.

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 and resource ('pull the tables out of a PDF') plus the output formats, and explicitly distinguishes itself from two named siblings (extract_pdf for running text, convert_bank_statement for bank statements). An agent can route correctly without opening any 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?

Gives explicit positive and negative routing: use this tool for tables, use extract_pdf for running text, use convert_bank_statement for statements, and run OCR first for scanned PDFs. Preconditions (text layer required) are spelled out.

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

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

Annotations only say non-read-only, idempotent, non-destructive; the description adds pricing per output format, latency expectations, size and depth limits, 422/413 failure modes with 'none charged', what happens to unfilled placeholders, and an untrusted-content warning. That is substantial value beyond the structured fields.

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?

Front-loaded with purpose, then delivery/error/pricing details in dense packed clauses with no filler sentences. It is long, but every clause carries operational information; the docs URL and cost note could arguably be trimmed.

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?

Covers input limits, templating semantics, output delivery and file naming, error behavior, cost, and timing, and an output schema exists so return values need no elaboration. An agent has everything needed to call it correctly on the first attempt.

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 coverage is 100%, so the baseline is 3, and the description still adds meaning: output=pdf is priced higher and LibreOffice-rendered, delivery=url yields a 24 h link, and the templating syntax is explained with examples. The placeholder mechanics are largely duplicated from the schema, keeping it from a 5.

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 and resource ('Fill the {{placeholders}} of a Word template with JSON data') plus the output formats, and explicitly routes slides to build_pptx_deck. An agent can distinguish this from the many sibling conversion tools without opening the 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?

Names one clear alternative (build_pptx_deck for slides) and states the DOCX-only constraint, which rules out half the sibling space. It stops short of distinguishing itself from convert_office_to_pdf or pdf_fill_form, but the context is clear enough to act on.

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

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

Annotations only declare readOnly=false, idempotent=true, openWorld=true, destructive=false; the description goes well beyond by disclosing sandbox host restrictions, 422/502/413/503 outcomes and that failures are 'not charged', plus latency and prompt-injection caution. That's rich behavioral context, though items like base64/file return shape and sizing belong to the output schema/output shape rather than pure behavior. The combination justifies a solid 3 with annotations present.

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?

Front-loads the purpose and sibling routing, then dense but relevant detail on limits and pricing. It is one long paragraph, but nearly every sentence carries actionable information; minor room to split error/limit clauses out.

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?

An agent has purpose, restrictions, cost, timing, error codes and output handling (base64 vs 24 h url, 15 MB cap) in one place. With an output schema present, remaining structural detail is already covered, so this definition is complete enough to call correctly.

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 100%, so baseline is 3; the description names paper, landscape, margin_mm, print_background, scale and wait_ms but adds little beyond the schema text itself. Useful nuance like 'wait_ms after load' and the 24 h url option roughly matches what the schema already documents.

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 and resource ('Convert a web page URL to PDF') and immediately differentiates from siblings images_to_pdf and take_website_screenshot. An agent knows exactly what this does versus the other PDF/convert tools without opening the 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 routes alternatives: images to images_to_pdf, image capture to take_website_screenshot, and constrains input to public http(s) pages. Names the conditions (private/internal targets refused 422) that would disqualify a call.

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

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

Goes far beyond the annotations: JPEG byte-for-byte embedding, EXIF orientation handling, transparency flattened on white, per-image 40 MP and 30-image caps, 413 over 15 MB and 503 over ~78 s (both uncharged), typical 1-3 s latency, USD 0.005 price with no free tier, and a prompt-injection caution on returned text. This is unusually rich operational context for a tool whose annotations only cover read/write and idempotency flags.

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?

Front-loaded with purpose and sibling routing, and nearly every clause carries real information (limits, pricing, error codes, latency). It is dense and parenthesis-heavy in one long paragraph, which slightly hurts scanability, but little is wasted.

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?

Covers input constraints, output modes, size/time failure modes with billing implications, latency expectations, cost, and a security caveat; an output schema exists so return-value detail is not required. Nothing an agent needs before calling is missing.

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 100%, so the schema already documents every parameter including nested url/image_base64 and the enum meanings. The description restates the same ground ('each `url` or `image_base64`', page_size/orientation/margin) with only the marginal addition that 'fit' means each page equals its image's size; it also omits `output` from its parameter list even though it discusses it later.

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 and resource ('Convert 1-30 images into a PDF') with scope baked in, and explicitly differentiates from siblings by naming convert_office_to_pdf and html_to_pdf. An agent can select this over pdf_to_images or html_to_pdf without opening any 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?

Provides explicit routing: Office files go to convert_office_to_pdf, web pages to html_to_pdf. That is when-to-use-this vs when-to-use-alternative guidance stated directly rather than inferred.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantial context beyond them: return fields, 422 handling without charge, 1-5 s latency, USD 0.0025 price, a free tier, and a prompt-injection warning for untrusted extracted content. This is exactly the behavioral context an agent needs before spending money.

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?

Front-loads purpose and sibling routing before pricing and latency details. It is dense with pricing/security/return info, but nearly every clause carries actionable information; only the pricing sentences run slightly long relative to the core call decision.

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?

An output schema exists, so return-value exposition is optional, and the description still names the key fields. With cost, latency, error semantics, and a security warning all present, nothing material is missing 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 100%, so the URL constraints and the lang pattern/default are already fully documented in the schema. The description adds no parameter-level detail (e.g., which languages are actually installed beyond the schema's 'eng' note), so the baseline 3 applies.

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 ('OCR the text in a public image') and immediately distinguishes itself from nearest siblings by naming pdf_ocr and read_qr_barcode with their respective conditions. An agent can select this tool without opening any 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?

Explicit routing rules: scanned PDFs go to pdf_ocr, QR/barcodes go to read_qr_barcode. It also implicitly defines the scope of use (public images only) and notes the failure classes that lead to a 422.

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

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

Goes well beyond annotations: add preserves existing attachments (non-destructive as destructiveHint=false promises), 10 MB extract / 5 MB file / 100 attachment caps, 413 for oversized results (not charged), 422 for encrypted input with the fix (unlock first), 503 after ~78 s, typical latency, and an explicit prompt-injection warning about untrusted extracted data. This is exactly the operational context annotations cannot carry.

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?

Front-loaded with the purpose and the sibling redirect in the first two sentences, then packs limits, errors, pricing, and safety in short clauses. Dense but every sentence carries callable 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 multi-action, open-world, paid tool with an output schema, the description supplies everything else an agent needs: action-specific behavior, size ceilings, failure modes with status codes and billing impact, rate limits, and the untrusted-data caveat.

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 coverage is 100%, so every parameter already documents its meaning, limits, and defaults; the description largely restates the action semantics and size caps. It adds little parameter detail the schema does not already contain, so baseline 3 applies.

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 set and resource: list, extract, or add file attachments of a PDF, and immediately distinguishes itself from pdf_inspect (the whole-file report tool). The three actions are enumerated so an agent knows the full scope before opening the 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 routes whole-file inspection to pdf_inspect and describes which `action` value serves which intent (list to discover, extract by name, add to attach). No explicit 'when not to use' for the other 38 pdf_* siblings, but the alternative routing given is clear and actionable.

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

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

Goes far beyond annotations by disclosing the no-larger-file guarantee, unchanged fallback semantics, active-content stripping, error conditions (413, 422, 503 with charging status), typical runtime, and pricing. These are exactly the behavioral traits an agent needs to plan a call.

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?

Front-loaded with purpose and alternative, then dense but relevant operational details. No sentence is clearly wasted, though the single-paragraph format could be more scannable.

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?

Despite output schema presence, the description adds crucial operational context: pricing, error handling, runtime, and output modes. Nothing an agent needs to call it correctly appears missing.

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 100%, so the schema already documents all parameters. The description repeats level semantics and clarifies output URL storage, but adds little beyond what the schema provides. Baseline 3 is appropriate.

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?

Starts with a specific verb and resource ('Compress a PDF to shrink its file size') and explicitly contrasts with pdf_rasterize for image-only output. An agent can distinguish it from all siblings without opening the 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 names pdf_rasterize as the alternative for image-only copies and gives prerequisites like unlocking encrypted inputs. It doesn't cover when not to compress broadly, but the key routing guidance is present.

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

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

Goes well beyond the annotations: discloses that active content is always stripped, encrypted input yields 422, sub-1pt crops yield 422, oversized output yields 413 (not charged), the 503 timeout threshold (not charged), pricing, and the free tier. Annotations already cover safety hints, and the description is consistent with destructiveHint=false because it notes the content is not removed. Minor deduction: it does not say whether the original file is persisted or mutated server-side, though base64/url output implies a new file.

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?

Front-loads the verb and the sibling disambiguation, then packs constraints, outputs, errors, pricing, and the safety warning into compact clauses. It is dense rather than bloated, though the error/price/free-tier tail could be slightly compressed.

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 an output schema present, the description need only clarify behavior and errors, and it does: base64 vs 24h url output, all key failure modes with charge implications, and the untrusted-content caveat. Nothing material is missing 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: margins are 'measured on the page as displayed', the at-least-one-margin rule, and the consequence of over-cropping (under 1 pt is a 422). It does not re-explain unit or pages, which the schema already covers in detail.

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 and resource ('Crop the margins of a PDF') and immediately names the sibling it is not ('To change the paper size use pdf_resize'), so an agent can separate it from pdf_resize and pdf_extract_pages 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 routes the agent to pdf_resize for paper-size changes and clarifies the operation is not redaction, since content outside the crop box stays in the file. It also states the input precondition (at least one of top/right/bottom/left) rather than leaving that to inference.

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

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

Goes far beyond the annotations (which only declare readOnly=false, idempotent, non-destructive, open-world) by disclosing out-of-range handling (422, never clamped), removal of active content, encrypted-input rejection, 15 MB 413 and 78 s 503 both 'not charged', pricing, free tier, and an untrusted-data warning. That is exactly the behavioral context structured fields cannot carry.

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?

Front-loaded with purpose and sibling routing, then limits/errors/pricing. Every clause carries payload, but the single dense paragraph packs pricing, safety, and error codes together, making it heavier than ideal to scan.

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 paid, open-world conversion tool with an output schema, this covers inputs, output modes, destructive-side behavior, all failure codes, cost, and timeout. Nothing an agent needs to invoke it safely appears to be missing.

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 coverage is 100%, so the baseline is 3, but the description adds real semantics the schema does not: output order is preserved and repeats are allowed, and out-of-range parts fail rather than clamp. It restates the page grammar already in the schema, so not a full 5.

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 and resource ('Extract pages from a PDF') and immediately differentiates from the two nearest siblings by naming pdf_remove_pages and pdf_split with their distinct purposes. An agent can route correctly without opening any 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 routes alternatives: drop pages -> pdf_remove_pages, multiple files -> pdf_split, encrypted input -> unlock first. It also names the inputs (url vs pdf_base64) and the output modes, so the when-to-use decision is fully determined.

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

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

The description adds substantial behavioral context beyond the annotations: it details error responses (422 for unknown fields, read-only, unfit values, encrypted input), notes that non-Latin text with flatten triggers a 422, mentions scripts are removed, signature validation stops, timing (1–4 s), pricing (USD 0.01, no free tier), logging and retention policies, and a security warning about untrusted data. This is rich transparency for a mutation 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?

The description is front-loaded with the core purpose and then packs in many operational details. It is dense but every sentence earns its place with useful constraints, error codes, or security notes. It could be slightly more scannable (e.g., bullet points) but remains efficient.

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's complexity (mutation, 5 parameters, nested object, output schema) and the presence of an output schema, the description covers all essential behavioral aspects: return format, error conditions, pricing, timing, security, and limitations. It leaves no significant gaps an agent would need to call the tool correctly.

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 coverage is 100%, so the schema already documents all parameters. The description nevertheless adds meaningful context: it explains that field values may be strings, numbers, booleans, options, lists, or null, and specifies that an unknown name or read-only field yields a 422. It also maps the 'names from form-fields' detail to schema descriptions, providing value beyond structured data.

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 specific verb and resource: 'Fill the form fields of a PDF from a JSON object.' It distinguishes from sibling tools by referencing pdf_flatten and pdf_form_fields, so an agent can identify when this tool is the right choice without opening the 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?

It explicitly names an alternative ('To make the values permanent use pdf_flatten') and clarifies that field names come from form-fields, giving clear context. However, it doesn't explicitly state when not to use this tool versus others like pdf_form_fields, and the presence of both the separate pdf_flatten tool and the flatten parameter could briefly confuse an agent.

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

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

Goes well beyond the annotations: signature invalidation, removal of active content (JavaScript, actions, XFA), the fact that annotations not flattened by the mode are removed, encrypted input 422, 15 MB 413, ~78 s 503, pricing, free quota, and untrusted-data warning. These are exactly the traits an agent needs for a mutation 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?

Front-loads the action, then constraints, then output/error handling. Dense semicolon phrasing but each clause carries operational meaning; no filler.

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?

Covers purpose, alternatives, error codes, timing, size limits and output shape, and an output schema exists so return values need not be spelled out. Nothing essential for correct invocation is missing.

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 coverage is 100%, so the schema already documents all four parameters including enum meanings. The description adds value by tying parameters to consequences: output=url yields a 24 h link, exceeding 15 MB returns 413, and mode governs which annotations survive.

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 (flatten) and resource (form fields and annotations into page content), and explicitly names pdf_fill_form as the sibling to use for filling instead. An agent can distinguish it from pdf_fill_form, pdf_form_fields and pdf_compress without opening schemas.

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 routes the agent: "To fill fields first use pdf_fill_form" and clarifies mode selection (all/screen/print). It gives clear usage context but does not state when not to flatten or contrast with pdf_repair/pdf_attachments.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, but the description adds substantial operational context: return format and field attributes, field-count limits (1,000 listed; >5,000 is a 422), XFA handling, encrypted-input errors, timeout behavior (503, not charged), pricing, free-tier limits, and an untrusted-data warning. This is unusually rich disclosure beyond the structured 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 front-loaded with purpose and the sibling alternative, then moves through return shape, limits, errors, and pricing. It is dense and somewhat long, but nearly every sentence carries useful information; the only minor cost is the lengthy enumeration of field attributes.

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 an output schema already exists, the description still adds enough about the return format to be helpful, and it covers errors, limits, pricing, and security warnings. An agent has everything needed to call it correctly and interpret results, with no obvious gaps.

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 100%, and the input schema fully documents the url and pdf_base64 alternatives, size limits, and mutual exclusivity. The description adds no parameter syntax or format details beyond what the schema already provides, so the baseline of 3 is appropriate.

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 a specific verb+resource: 'List the form fields of a PDF.' It also explicitly distinguishes itself from the sibling pdf_fill_form ('To fill the fields use pdf_fill_form'), making it easy to separate from other PDF tools.

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?

It names a clear alternative for the immediate follow-up action ('To fill the fields use pdf_fill_form') and gives context via error/limit notes. It does not, however, explicitly say when to prefer it over other inspection siblings like pdf_inspect or pdf_metadata, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this ("It changes nothing", "a report on one PDF (nothing changed)") while adding context annotations cannot express: exact report contents, 422 on encrypted input, 503 and no-charge behavior past ~78 s, typical <2 s latency, per-IP free tier pricing, and a prompt-injection warning about returned page text. This is unusually complete behavioral disclosure for a read-only 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?

Everything in the paragraph earns its place — limits, error codes, timing, and the untrusted-data warning — and the sibling differentiation is stated early. However, the first clause is pricing ("Price: USD 0.005; Free: 3 pdfpeek calls...") rather than the tool's action, and the content is delivered as one dense run-on, so the read is slightly front-loaded with the wrong thing.

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 inspector with an output schema and full annotation coverage, the description supplies everything an agent still needs: latency, page cap, error semantics, charging behavior, and a safety note about returned text. The minor dangling reference to `text_analysis` is the only soft spot.

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 coverage is 100% and both parameters already document size limits and the url/pdf_base64 either-or, so the description does not need to restate them. It adds only indirect input constraints (encrypted files rejected, 2,000-page cap), which is baseline-appropriate but not compensating value beyond the schema.

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 and resource ("Inspect a PDF: page sizes, text layer or scan, forms, attachments, JavaScript, bookmarks") and explicitly contrasts with the sibling pdf_metadata for title/author/date reading. An agent can distinguish it from pdf_extract, pdf_form_fields and pdf_metadata without opening any 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?

Gives an explicit alternative ("for title, author and dates, or to edit them, use pdf_metadata") plus a prerequisite for the encrypted case ("Encrypted input is a 422 (unlock it first)"), routing to pdf_unlock. It also states the operational envelope (2,000 pages, 20 s text_analysis) that determines when the call is appropriate.

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

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

Adds substantial behavior beyond annotations: output mode and 24-hour URL expiry, 15 MB 413 response, 78 s 503 timeout, active content removal, encrypted-input 422, pricing, free-tier limit, and untrusted-data warning. These details materially affect invocation and handling.

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?

Front-loads the use case and sibling differentiation, then groups input/output constraints, error behavior, pricing, and security note. Despite density, every sentence adds operational value for a complex API tool.

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?

Complete for a merge tool: covers input structure, page selection, output modes, size/timeout failures, encryption, active-content stripping, pricing, rate limits, and untrusted-data handling. Output schema exists, so return-field details need not be repeated.

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 coverage is already 100%, but the description adds useful semantics: input objects are 2-20 and each needs url or pdf_base64 with optional pages; pages format is exemplified as 1-3,5; output enum behavior and 24-hour URL lifetime are clarified. It meaningfully exceeds schema alone.

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 and resource — combine/merge several PDFs into one file — and explicitly contrasts with pdf_split for cutting one PDF apart. The scope, optional page selection, and 2-20 input constraint make it easy to distinguish from sibling tools.

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 says when to use it (combine several PDFs into one), names the alternative for the opposite operation (pdf_split), and includes practical constraints and failure cases. An agent can select this tool without consulting siblings.

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

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

Goes well beyond the annotations: 15 MB payload 413, ~78 s 503, encrypted input 422, 24 h URL expiry, always-on removal of active content (JavaScript, actions, embedded files, XFA), pricing and the free-tier quota, plus an untrusted-content warning. The one tension is `strip` deleting all metadata against destructiveHint=false, but the deletion is opt-in via an explicit parameter and is fully disclosed, so the agent is not misled.

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?

Front-loads purpose, then the sibling routing, then the mode semantics, then operational limits — a sensible order. The single dense paragraph packs a lot of clauses (pricing, free tier, latency, URL expiry) into one block, which costs a little scannability but no sentence is filler.

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 5-parameter, zero-required tool with an output schema all present, everything an agent needs to call it correctly is here: input source choice, write-vs-read semantics, output format, error codes and cost. Return values are left to the output schema, appropriately.

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 coverage is 100%, so the baseline is 3; the description still adds real meaning by explaining that "" deletes a field, that `strip` runs before any writes, and that `output` "url" yields a 24 h link. It does not restate the per-field maxLength or the base64 size ceilings, but those are already in the schema.

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 specific verbs (read, edit, strip) against a specific resource (PDF document metadata) and immediately frames scope by pointing to pdf_inspect for pages, forms and active content. An agent can route between the two siblings 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 names the alternative tool and the condition that selects it ("For pages, forms and active content use pdf_inspect"), and enumerates the three modes here: default read, `set` to write, `strip` to remove. Preconditions for encrypted input (unlock first via pdf_unlock) are also given.

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

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

Goes well beyond the annotations: documents the returned artifacts (base64 file/files or a 24 h URL), the 15 MB / 413 size failure, the 422 for encrypted input, the 503 timeout at ~78 s and that failures are not charged, plus that active content is always stripped and returned text is untrusted. With readOnlyHint=false already flagging that this produces an artifact, the description adds substantial operational context. It does not contradict the annotations, but it omits anything about rate limits or concurrency, keeping it just under the top mark.

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?

Purpose and sibling routing are front-loaded, and every clause carries information. The single dense paragraph does pack failures, pricing, and security notes into one run-on block, which is harder to scan than a short bulleted split would be.

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 7-parameter tool with an output schema, everything an agent needs is present: input modes (url vs pdf_base64), page limits and splitting, output modes and expiry, failure codes, latency, pricing, and a prompt-injection caveat. No gaps remain that would cause a wrong or failing call.

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 coverage is 100%, so the baseline is 3, and the description adds real value on top: it ties page count to price tiers, notes the 200 dpi ceiling above 5 pages, and explains the 24 h lifetime of the url output mode. It stops short of explaining the page-range syntax or lang options, which live entirely in the schema.

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 and resource ('OCR a scanned PDF into a searchable PDF') and immediately distinguishes itself from two named siblings: ocr_image for single images and extract_pdf for PDFs that already have a text layer. An agent can route correctly without opening any 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 names the alternatives and the condition that selects each, states the 10-page-per-call ceiling with an instruction to split longer documents, and explains what skip_text (default true) changes. When-to-use and when-not-to-use are both covered.

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

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

Beyond the annotations (which already cover readOnly/idempotent/destructive/openWorld), the description discloses truncation caps (1,000 bookmarks, 8 levels, `truncated`), named-destination resolution, error semantics (422 encrypted, 503 timeout, free of charge), latency, price, free-tier quota, and an untrusted-content warning. This is unusually rich behavioral context.

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?

Front-loads the verb, resource, and alternative in the first sentence, then layers limits, failure modes, cost, and a safety note compactly. The pricing/free-tier/docs tail is slightly over-stuffed but each element is actionable.

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?

Because an output schema exists, the return shape need not be spelled out, yet the description still orients the agent on the tree structure and truncation. Combined with limits, error codes, and timing, an agent has everything needed to call it correctly.

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 100% and defines the url vs pdf_base64 alternatives, so the schema carries the parameter burden. The description adds only a small note about page being 1-based and possibly referencing another file, which is return semantics rather than parameter guidance. Baseline 3 applies.

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 and resource ('Read the bookmarks of a PDF as a nested tree') and explicitly names the counterpart tool pdf_set_outline for writing, so an agent can distinguish it from the write sibling 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 routes the agent to pdf_set_outline when the goal is writing bookmarks, and notes that encrypted input must be unlocked first. It does not distinguish itself from other read-oriented siblings such as pdf_metadata or pdf_inspect, so guidance is clear but not exhaustive.

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

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

Goes well beyond the annotations: it declares payload limits (15 MB → 413), encryption failure (422), timeout (503 at ~78 s), typical latency, pricing, per-IP daily free quota, and that active content is always stripped. The safety profile is largely pre-empted by destructiveHint=false/idempotentHint=true, so the missing piece is mainly what the transformation does to existing page content, not the operational behavior, which is unusually well covered.

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?

Purpose and the sibling alternative are front-loaded, then behavior, then cost/limits, then a security note — a sensible ordering with no filler sentences. It is dense and reads as one long run-on, with pricing and quota detail that could be its own line, which keeps it just short of a 5.

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 12-parameter paid conversion tool with an output schema, the description covers the input modes (url vs pdf_base64), the transformation semantics, the output shapes, the failure modes, and cost — everything an agent needs to invoke it correctly and interpret a non-200 response. Output values themselves are handled by the output schema, so nothing material is missing.

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 coverage is 100%, so the baseline is 3; the description earns above that by explaining the `format` placeholders ({n}, {N}) and by clarifying a subtle semantic the schema does not — that with `pages` "numbering counts the stamped pages," so a skipped cover does not consume a number. `start_number`, position count (6) and the base64/url output choice are also named in prose.

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 and resource ("Add page numbers to a PDF") and immediately contrasts with the sibling that would otherwise be confused ("For a text stamp use pdf_watermark"). An agent can pick this over pdf_watermark or pdf_flatten without reading either 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 routes stamping-style needs to pdf_watermark and states the prerequisite for encrypted input ("Encrypted input is a 422 (unlock it first)"), pointing at pdf_unlock. It doesn't cover other near-neighbours (pdf_outline, pdf_metadata, pdf_fill_form) or say when not to number pages, so it stops short of a full decision rule.

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

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

Far exceeds the annotations: pre-flight validation with step-named 422 that is not charged, a single 70 s budget, output as base64 or 24 h URL, 413 over 15 MB (not charged), encrypted input rejected, active content always stripped, typical 1-10 s latency, and USD 0.01 flat pricing with no free tier. Adds a prompt-injection warning about returned text, which annotations cannot convey.

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?

Front-loads the one-sentence purpose and the single-vs-multi routing rule before limits and pricing. Information-dense with no padding, though the middle sentences stack several clauses (pricing, validation, active content, encryption) into long runs that could be split for scanability.

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?

Covers the pieces an agent needs before calling: input size limits, step ordering rules, error behaviors and their billing status, time budget, output modes, and pricing. Output schema exists, so return-value explanation is not required; nothing material is missing.

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 coverage is 100%, so the schema already documents ops, the steps array, output enum and size limits. The description's notes ('params as on that operation's own tool', inspect/outline last) largely restate the schema's own op/params descriptions, adding only marginal framing value. Baseline 3 is appropriate.

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 capability — chaining up to 10 PDF operations in sequence on one PDF in a single call — and explicitly contrasts with single-operation siblings ('For one operation use its own tool, such as pdf_rotate'). An agent can distinguish it from pdf_rotate/pdf_crop/etc. 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?

Explicit routing rule: use this tool for multiple ops, use the dedicated tool for one. Also states structural constraints — inspect/outline may come last, steps run in order with each output feeding the next. When-to-use and when-not-to-use are both covered.

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

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

Annotations mark this as non-readonly and explicitly non-idempotent, and the description explains why ('each call encrypts afresh, so the file differs every time'). It adds substantial context beyond annotations: AES-256 usage, the random owner-password trap, permission defaults, active-content stripping, passwords never logged, 413/422/503 paths, latency, and pricing.

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?

Front-loaded with purpose and sibling routing, then operational caveats. Every sentence carries information, though the second half is a dense run of error codes, price, and limits that could be split for scannability.

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 6-parameter mutation tool with nested permissions and an output schema, the description covers encryption behavior, failure modes, timing, cost, and free-tier limits. Nothing an agent needs to call this correctly is missing.

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 coverage is 100%, so baseline is 3; the description still adds meaning, explaining that user_password opens the file, owner_password lifts permissions, and that omitting owner_password produces an un-liftable random one. It does not, however, enumerate the permissions flags beyond the schema's default-everything note.

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 a specific verb+resource ('Password-protect a PDF') and immediately names the sibling tools for adjacent operations (pdf_unlock, pdf_redact), so an agent can distinguish it from the rest of the pdf_* family without opening schemas.

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?

It states explicit routing rules: use pdf_unlock to remove a password, pdf_redact to black out content, and unlock first if the input is already encrypted (422). Alternatives and preconditions are named, not implied.

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

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

Annotations already declare idempotent, non-destructive, open-world, so the bar is lower, and the description goes well beyond them: no selectable text/forms/active content, PDFium with no JavaScript, 15 MB 413 cap, 422 on encrypted input, 503 over ~78 s with no charge, and typical 1-5 s latency. It also adds a prompt-injection caution about returned text. It stops short of describing the returned JSON shape, which is left to the output schema.

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 core action and the sibling routing are front-loaded in the first sentence. The remainder is dense but every clause carries information (limits, errors, pricing, safety note); it is close to being over-packed into one block rather than structured into bullets, which costs a point.

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 paid, rate-limited conversion tool this covers what an agent needs: input sources and size caps, page limits, output modes, error codes and charges, latency, and price tiers. The return shape is handled by the output schema, so nothing material is missing.

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 coverage is 100%, so baseline is 3, and the description adds genuinely new meaning: the pricing tier hinges on whether `pages` is a closed selection of at most 5 pages, and it ties `output` "url" to a 24 h link. It restates dpi, format and grayscale only lightly, which is fine since the schema documents them.

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 and resource ('Rasterize a PDF: every page rendered to an image, rebuilt as one PDF') and immediately distinguishes itself from the two nearest siblings pdf_compress and pdf_to_images. An agent can tell exactly what transformation this performs without opening the 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 names the alternatives and the conditions that select them: 'To shrink and keep text use pdf_compress; for page images use pdf_to_images.' It also states limits (at most 20 pages, dpi 36-300) and prerequisites (encrypted input is a 422, unlock first), so the when/when-not is fully covered.

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

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

Goes well beyond the annotations: discloses that removed pages and their exclusive references are permanently gone, that active content is always stripped, that encrypted input fails with 422, that >15 MB is a 413, and that timeouts are uncharged. Adds pricing, rate-limit, and latency expectations plus an untrusted-content warning — none of which annotations convey.

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?

Front-loads purpose and the alternative, then packs operational facts into dense parentheticals. It is longer than typical but nearly every clause carries actionable information; the error-code inventory is the only slightly heavy section.

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 paid, mutating, rate-limited file API, the description covers input constraints, output modes, failure modes, cost, and even a prompt-injection caveat. With an output schema present, no return-value detail is required, so nothing an agent needs before calling is missing.

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 coverage is 100%, so the schema already documents url, pages, output, and pdf_base64. The description mostly restates the page-range grammar and the 24 h URL lifetime that the schema already provides, adding only the size-charge relationship and the either/or of url vs base64.

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?

Specific verb + resource ("Remove pages from a PDF") with an explicit statement of the inverse operation and the sibling that performs it (pdf_extract_pages). An agent can distinguish this from pdf_split, pdf_reorder_pages, and pdf_extract_pages without opening any 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 routes the inverse case ("To keep only some pages use pdf_extract_pages") and enumerates blocking conditions: encrypted input, >15 MB, 422 empty_result, ~78 s timeout. No guidance on the overlap with pdf_split or pdf_reorder_pages, which are the neighbouring page-manipulation siblings.

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

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

Goes well beyond the annotations: it names the exact error contract (422 page_out_of_range, 422 for encrypted input, 413 over 15 MB, 503 past ~78 s), says which of those are not charged, discloses pricing and the free-tier quota, and states that active content is always stripped and that bookmarks/forms/metadata are not carried over. This is a mutation-style tool (readOnlyHint=false) and the description supplies the consequences the annotations cannot.

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?

Front-loaded with the operation and the alternative, then error/limit facts in compact clauses. The pricing, quota and docs-URL tail is useful but makes the block denser than strictly needed for tool selection.

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?

An output schema exists, yet the description still correctly covers the operational envelope an agent needs before calling: input size ceilings, output mode behavior, failure codes, and the untrusted-data warning. Nothing material is left to inference for a 4-parameter, 1-required tool.

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 coverage is 100%, so the baseline is 3, but the description adds observable consequences the schema omits: a page listed twice is copied, an unlisted page is left out and reported in the reply, and pages are 1-based with a 500 cap. The `output` url mode's 24 h lifetime is restated rather than extended, which keeps it just short of a 5.

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 and resource (reorder pages of a PDF from a list of page numbers) and immediately delineates the destructive-only variant: 'To only drop pages use pdf_remove_pages.' An agent can distinguish this from pdf_remove_pages, pdf_extract_pages and pdf_merge without opening any 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 routes the agent: use pdf_remove_pages when only dropping pages, and the 'Like extract-pages' note flags a related operation with shared semantics. Prerequisites are stated too (encrypted input must be unlocked first).

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

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

Rich beyond annotations: what is stripped (JavaScript, actions, embedded files, XFA always removed), the full error taxonomy with charge status (422 unreadable/encrypted, 413 over 15 MB not charged, 503 over ~78 s not charged), pricing, free-tier quota, latency, and a prompt-injection caution. Only gap is that idempotency is left to the annotation rather than restated in the description.

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?

Front-loaded with purpose and the sibling alternative before the operational detail, and nearly every clause carries decision-relevant information. Slightly list-like and repetitive on limits (15 MB here vs 20 MB/10 MB in the schema), but no wasted sentences.

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?

Covers everything needed to call correctly: input constraints, output form, failure modes, cost, quota, and safety guidance. An output schema exists, so the return-value explanation is a bonus rather than a requirement, and the description is complete even for a mutation-adjacent tool.

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 100%, so all four parameters are already documented, and the description largely restates that (linearize → fast web view, output=url → 24 h link). It does add one fact the schema omits: the 15 MB / 413 ceiling on the resulting file. Baseline 3 is right when the schema carries the parameter load.

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 and resource ('Repair a damaged PDF') and immediately scopes it against a sibling: 'For a report on a readable file use pdf_inspect.' It also enumerates the damage classes handled (bad or missing xref, cut-off file, junk before header), so the agent can tell repairability from inspection without opening the 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?

Explicit routing rules: use pdf_inspect for readable files, unlock first for encrypted input (the pdf_unlock sibling), and it names the 'structure, not damaged page data' boundary so the agent knows when repair will not help. Exclusions and alternatives are both present.

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