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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true): it discloses non-destructive-by-default behavior, the exact overwrite escape hatch, the encryption limitation, and that the added text remains real searchable text rather than a raster overlay. These are the traits an agent actually needs before invoking.

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?

Four sentences, front-loaded with purpose and output, then alternative, then safety constraints. No filler and no repetition of schema fields.

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 no output schema, the description supplies what would otherwise be missing: the result is a new PDF, the original is preserved, the text is searchable, and encryption blocks saving. An 11-parameter mutation tool is fully covered by description plus schema.

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 value by demonstrating the format parameter with a concrete template ('Confidential - Page {n} of {total}') and clarifying placement ('chosen corner or edge'). It does not cover color, margin, font_size or page-range syntax, which the schema already handles.

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 ('write page numbers ... onto every page or chosen pages of a PDF and saves the result as a new PDF') and immediately distinguishes itself from add_watermark, the nearest sibling. An agent can tell what this produces 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 the explicit alternative for a different need ('For a large diagonal stamp across the page, use add_watermark'), and states the conditions that gate the write: original untouched, existing output replaced only with overwrite: true, encrypted PDFs cannot be saved. Routing and preconditions 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 and destructiveHint=false, but the description adds real context beyond them: the original is never modified, an existing output is only replaced with overwrite:true, and encrypted PDFs cannot be saved even with a password. The encryption limitation is partly echoed in the password parameter schema, which keeps this from being maximal.

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 and visual outcome, then the sibling alternative, then the safety caveats. No sentence is redundant and no filler is present despite covering five distinct facts.

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 10-parameter file-mutating tool with no output schema, the description covers what is produced, that the source is untouched, overwrite gating and encryption limits — the essentials an agent needs to call it safely. It stops short of describing the call's return value or the failure mode when an invalid page range is passed, which is a minor residual gap.

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 every parameter (angle, color, pages, opacity, font_size, overwrite, password) is already documented in the schema with defaults and formats. The description only alludes to rotation and transparency generically and adds no syntax, units, or constraints beyond the schema, so the baseline of 3 is correct.

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 — writing rotated, semi-transparent text across a PDF's pages and saving a new file — plus the visual result ('page content stays readable underneath'). It explicitly differentiates itself from the sibling add_page_numbers, so an agent can route between the two 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?

Explicitly names the alternative for a related need ('For small text in a corner or a footer, use add_page_numbers') and states the conditions for replacing an existing output file. It does not discuss prerequisites such as password availability until the encryption caveat, but the primary routing decision 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 only declare the safety profile (readOnly=false, destructive=false, idempotent=true); the description goes well beyond them by disclosing the lossy side effect (text is no longer selectable), the non-mutation of the original, the conditional replacement of the output file via overwrite, and the encrypted-input failure mode. It is consistent with the annotations rather than contradicting them.

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?

Effectively concise for the amount of load-bearing information: mechanism first, then suitability, then the lossy consequence and its remedy, then the sibling alternative, then file-safety semantics, then the encryption limitation. No sentence is redundant with the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description compensates by stating what is returned ('the size before and after'). Combined with the side-effect, safety, and precondition disclosures, an agent has everything needed to call this correctly on the first try.

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 path, output, quality, password and overwrite are already documented with dpi values and defaults. The description reinforces overwrite and quality behavior but adds no new parameter syntax or constraints beyond the schema, so the baseline of 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 (compress a PDF) plus the exact mechanism ('redrawing every page as a JPEG image at the chosen quality'), which tells an agent how the output differs from the input. It also names the sibling pdf_to_images as the alternative for a different output shape, so it is distinguishable 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 when-to-use ('Best for scans and photo-heavy files'), when-not ('for documents that are mostly text it usually makes the file larger'), the follow-up step ('run recognize_text on the result'), the alternative tool for a different goal (pdf_to_images), and a hard precondition (encrypted PDFs cannot be compressed). Nothing is left to inference.

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

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

Annotations only give coarse hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true); the description adds real specifics beyond them: the original file is untouched, an existing output is only replaced when overwrite is true, line-less pages fall back to whole-page reading, a text-less page is an error, and numeric parsing rules. These are consistent with, not contradictory to, the 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?

Purpose and output artifact are front-loaded in the first clause, and every subsequent sentence carries distinct information (fallback behavior, parsing rules, prerequisites, safety). It is dense and somewhat packed with semicolon-joined clauses, 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?

No output schema exists, yet the description covers the return value ('returns the rows found as a preview'), the failure mode, prerequisites, and file-safety behavior. For a 6-parameter write tool with nested area and an encrypted-PDF caveat, nothing an agent needs 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 coverage is 100%, so the schema already documents area, page, path, output, password, and overwrite, making 3 the baseline. The description adds behavioral meaning for area (auto-detection of a lined table vs whole-page reading when omitted) and for overwrite, which goes beyond the structured field text.

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 ('reads the table on one page of a PDF') plus the concrete artifact produced ('writes it as an .xlsx workbook'), and explicitly differentiates itself from extract_text. An agent can distinguish it from extract_text, pdf_to_images, and get_pdf_info 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 selection rule ('Use it for tables you want to calculate with; for plain text use extract_text') and a prerequisite ('Scanned pages need recognize_text first'). Both the when-to-use and the when-not-to-use cases are named.

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 the write/idempotent/non-destructive profile, but the description adds real value beyond them: the original file is untouched, an existing output is only replaced with overwrite:true, and it fails on invalid/out-of-range pages and encrypted PDFs. It doesn't say what error text or return value looks like, so it stops short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, front-loaded with the core behavior and ordering example before routing and failure modes. Every clause carries information; 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?

For a local write tool with no output schema, the description covers mutation scope, overwrite semantics, ordering, sibling routing and failure modes such as encrypted PDFs. 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 coverage is 100%, so the schema already documents all five parameters including the pages syntax and overwrite default. The description reinforces ordering with the "3,1" example but adds no syntax or format detail the schema lacks, 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 and resource ('Writes the chosen pages of a PDF to a new PDF') plus the ordering semantics, and explicitly contrasts itself with the sibling split_pdf. An agent can distinguish it from merge_pdfs, rotate_pages and split_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?

Gives the positive use case ('use it to pull out or reorder pages') and names the exact alternative with its selecting condition ('to cut a whole document into equal parts, use split_pdf'). Nothing is left to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint, but the description adds substantial behavioral detail: the exact output framing, empty results for scanned pages with the recovery path, the ~400,000-character truncation cap with a note, and that encrypted files need a password. That 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?

Four dense sentences, zero filler, with the core purpose front-loaded and alternatives, edge cases, and limits following in a logical order. Every sentence carries actionable 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?

There is no output schema, so the description must describe the return value — and it does precisely, including per-page delimiters ordering, the empty-page marker, and the truncation behavior. Edge cases (scanned, encrypted, oversized) are all covered.

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 path, pages range syntax, and password behavior are already fully documented in the schema; the baseline is 3. The description reinforces password semantics ('encrypted PDFs need their password') but adds no syntax or format detail beyond what the schema provides.

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 (extracts the text layer of a PDF) plus the return format (plain text, '--- Page N ---' sections, reading order). It explicitly distinguishes itself from siblings search_pdf and export_table, so 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 when-to-use ('read, summarize or quote a document') and names the alternatives with their selecting conditions (search_pdf for locating words, export_table for tables). It also documents the prerequisite for scanned files (run recognize_text first) and the password requirement for encrypted PDFs.

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=true and openWorldHint=false, and the description reinforces read-only while adding real context: encrypted PDFs require a password, missing/damaged files surface as errors, and scanned pages without a text layer are flagged as needing recognize_text. It doesn't describe output formatting or pagination, but for a read-only inspector this is well beyond the annotation baseline.

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 what it returns, then routing guidance, then behavioral notes. Three dense sentences with semicolon-delimited lists; every clause carries distinct information and nothing 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?

With no output schema, the description must convey the return payload, and it does so field by field. It also covers the password requirement, the error case for missing/damaged files, and downstream routing, leaving no gap an agent needs before calling it.

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 both parameters are already documented in the schema. The description's remark that an encrypted PDF needs its password restates the schema text rather than extending it, 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?

Specific verb+resource (reads a PDF's overview, returns text) followed by an explicit enumeration of what the overview contains (page count, sizes in mm, metadata fields, encryption status, pages lacking a text layer). This clearly separates it from extract_text and search_pdf, which it names.

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 when-to-use rule ('Call it first on an unknown file to decide what to do next') and routes to alternatives with conditions ('for the text itself use extract_text, to find a word use search_pdf'). Exclusions and alternatives 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 the non-destructive, idempotent, closed-world profile, but the description adds substantial context on top: inputs are left unchanged, an existing output is replaced only with overwrite:true, non-PDF/image entries are silently skipped, and it fails on unreadable paths, all-invalid lists, and encrypted PDFs. These failure modes and side effects are exactly the behavioral detail 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?

The core operation is front-loaded in the first clause, followed by layout rules, alternatives, and failure modes in one dense paragraph. Every clause carries information, though the single block is slightly long for easy scanning.

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 no output schema, the description still covers ordering, layout, side effects, overwrite gating, skip behavior, and error conditions. An agent has everything it needs to invoke this correctly without guessing.

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 would be 3, but the description adds meaning for paths by specifying ordering is significant and that non-PDF/image entries are skipped rather than erroring, and it clarifies the existence/overwrite interaction for output. Only minor overlap with what the schema already says about overwrite keeps this 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 (joins) and resource (PDFs and images into one new PDF), plus the exact ordering and image-to-A4-page layout semantics. It also names the sibling tools for the inverse operations (extract_pages, split_pdf, pdf_to_images), so an agent can place it precisely in the toolset.

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 when-to-use ("combine documents or turn photos and scans into a PDF") and explicit when-not, routing removals to extract_pages/split_pdf and page-to-image conversion to pdf_to_images. The alternatives are named with the condition that selects them.

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 declare idempotentHint=true and destructiveHint=false, and the description adds real context beyond them: the source PDF is not modified, existing images are only replaced with overwrite: true, and encrypted PDFs cannot be converted. It also describes the return (files listed with pixel sizes) despite having no 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?

Front-loaded with the core action and output convention, then use cases, then alternatives, then caveats. The opening sentence is dense and long, but each clause carries information an agent needs; there is 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 output format/naming, return summary, mutation semantics, overwrite behavior, and the encryption limitation. With no output schema, the description still supplies everything needed to invoke 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 baseline is 3, but the description adds semantics beyond the schema: the page selection maps to the <base>-NN naming convention, and overwrite is tied explicitly to replacement of existing images. It adds some meaning without restating every field.

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 (saves PDF pages as PNG/JPEG images) and even specifies the output naming pattern. It explicitly distinguishes itself from extract_text (read text) and compress_pdf (smaller PDF), so an agent can route correctly 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 concrete use cases (share a page as a picture, insert into a slide or chat, inspect layout) and names the alternatives for the adjacent intents: extract_text for text and compress_pdf for shrinking. Both when-to-use and when-to-use-something-else are 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: offline/no-upload operation, language coverage, that low-DPI scans are skipped unless force is true, runtime of seconds per page, that the original is unchanged, and that an existing output is only replaced with overwrite: true. This is exactly the extra context annotations can't 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?

Purpose is front-loaded and every following clause carries new operational information — trigger condition, follow-up tools, skip rule, timing, and file-safety semantics. No sentence is 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?

With no output schema, the description still defines the return artifact (a new PDF with a searchable text layer), the safety model, and the downstream workflow, which is everything an agent needs to invoke and chain this 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 baseline is 3, but the description adds real meaning: the rationale for force (low-resolution scans are mostly misread) and the destructive condition gated by overwrite. Minor parameters like pages and password are left entirely to 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 ('recognizes the text of scanned pages or images') plus the concrete artifact produced ('writes a copy of the PDF with an invisible text layer'), which cleanly separates it from sibling read-only tools like extract_text and get_pdf_info.

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 trigger ('use it when get_pdf_info lists pages without text or extract_text returns them empty'), names the follow-up tools to run on the output, and states the exclusion that pages already containing text are left untouched. Alternatives and conditions are all 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?

Adds substantial context beyond annotations: text is removed from the file (not just visually covered), the original is untouched, an existing output is replaced only with overwrite:true, encrypted PDFs cannot be saved, the occurrence count is returned, and nothing is written on a zero-match run. These are real behaviors an agent must know before calling. No contradiction with annotations - destructiveHint=false and idempotentHint=true are consistent with writing a new copy.

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 destructive outcome and the new-copy semantics are front-loaded in the first sentence, and the follow-up clauses each carry distinct operational information. It is a dense paragraph, though, and could be broken into shorter sentences for faster scanning.

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 an 8-parameter write tool with no output schema, the description closes the important gaps: return value (occurrence count), failure/edge cases (encrypted PDFs, existing output file, zero matches), and the handling of uncuttable content. An agent has enough to invoke this 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 already 88%, so the schema carries most parameter meaning, but the description adds genuinely useful semantics: flatten_unsafe converts uncuttable image/scan pages to images versus leaving them hidden and reported, and overwrite governs replacement of an existing output. It does not explain match_case's default or matching behavior, which is the one remaining gap.

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 ('Permanently blacks out ... every occurrence of the given words or phrases in a new copy of a PDF') and immediately distinguishes the operation from nearby siblings by naming remove_metadata for hidden content and search_pdf for previewing matches.

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 when-to-use and when-not rules: use for visible page content, use remove_metadata for hidden metadata ('often both before sharing'), and use search_pdf first to check what will be hit. Alternatives and sequencing are stated 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses non-obvious behavior: the original is never modified, an existing output file is only replaced with overwrite: true, and encrypted PDFs cannot be saved this way. These are exactly the failure modes an agent needs to know before calling a write tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no filler, front-loaded with the operation and the list of removed data, then routing to alternatives, then the mutation/encryption caveats. Every sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter tool with no output schema, the description covers what is produced (a copy at the output path), what is left untouched, overwrite semantics, and the encryption limitation. An agent has everything needed to invoke it correctly and to anticipate failure conditions.

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 nonetheless adds real meaning by tying overwrite to file replacement behavior and clarifying the encryption nuance — a password allows reading but not saving a new PDF. It reinforces rather than duplicates the schema, though it does not extend the path/output 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 ('Writes a copy of a PDF') and then enumerates precisely what hidden information is stripped: author, title, subject, keywords, creating program, dates, XMP, comment authors, edit leftovers, and photo location/camera data. This lets an agent distinguish it from every sibling, including the close ones (redact_pdf, get_pdf_info), 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 case ('Use it before sharing a file') and names two alternatives with the condition that selects each: redact_pdf for visible text, get_pdf_info to only read the information. This is a complete when-to-use / when-not-to-use / alternative map.

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 the annotations: rotation is additive to existing page rotation, content is not altered, the original is untouched, an existing output is replaced only with overwrite:true, and it fails with a message for invalid page ranges and encrypted PDFs. This is exactly the mutation-safety context the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) cannot convey on their own.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three front-loaded sentences with zero filler: purpose and parameter range first, then the use case and rotation semantics, then side effects and failure modes. Every clause carries information an agent needs.

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 mutation tool with no output schema, the description covers side effects, overwrite behavior, additive rotation, encryption limits, and error conditions. The only gap is what the call returns on success (e.g. the new file path), which the agent must infer.

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 all six parameters are documented in the schema, including the enum and the overwrite/password semantics. The description's parameter-level statements (added rotation, invalid page range error, overwrite-only replacement) largely restate the schema rather than adding new syntax or format detail, 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 (rotates), resource (pages of a PDF), scope (all pages or a chosen subset), parameter range (90/180/270 clockwise), and the outcome (writes a new PDF). Nothing among the siblings overlaps: none of merge/split/extract/compress rotate pages.

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 trigger scenario: 'Use it for sideways or upside-down scans'. That tells the agent when the tool applies. It stops short of naming alternatives or exclusions (e.g. when not to use it vs. pdf_to_images or extract_pages), so it lands at 4 rather than 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?

Despite readOnlyHint already covering safety, the description adds substantial behavior: literal-only matching (no wildcards/regex), case-insensitive default with Turkish İ/ı awareness, phrase matching constrained to a single line, a 500-match cap, and the scanned-page limitation. These are non-obvious traits that materially affect expectations.

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?

A single dense paragraph, front-loaded with what the tool returns, followed by matching semantics and then routing to siblings. Every clause carries information an agent needs; nothing is redundant 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?

With no output schema, the description steps in to describe the return values (count, page number, line, capped at 500) and covers the encrypted-PDF password caveat via the schema. Nothing essential to calling 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 the baseline is 3. The description nonetheless adds meaning: it clarifies the default case-insensitivity that the match_case parameter toggles, states query is plain literal text, and explains matching is line-bounded, which the schema does not convey.

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 ('Finds every occurrence of a word or phrase in a PDF') and even specifies the return shape (count plus page number and line per match). It is immediately distinguishable from extract_text (reading pages) and redact_pdf (blacking out matches) which it names directly.

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 it to locate something without reading the whole document; to read pages use extract_text, and to black out what was found use redact_pdf with the same words.' It also flags the when-not case for scanned pages, which require recognize_text 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?

Annotations only declare the safety profile (readOnly false, idempotent, non-destructive); the description goes well beyond that by disclosing that the original is unchanged, that nothing is written if any target file exists unless overwrite is true, and that encrypted PDFs cannot be split. These are exactly the failure/idempotency behaviors an agent needs.

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 core action and keeps the alternative-tool guidance and the caveats in compact clauses. It is dense but every clause carries information; only the parenthetical about the shorter last file borders on the obvious.

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 write tool with no output schema, the description covers what is produced (named files and a listing), where it goes, the overwrite/atomicity rule, and the encryption limitation, leaving no material gap 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; the description adds value by clarifying the naming derivation (base-01, base-02, ...) and tying overwrite to the all-or-nothing write behavior, though it does not elaborate on password or pages_per_file 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 (splits a PDF), plus the exact output shape (new files of N pages each, last may be shorter) and even the naming convention <base>-01.pdf. It explicitly contrasts itself with the sibling extract_pages, so an agent can distinguish the two without opening the 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?

Names the scenario it is for ('cut a long document into equal parts') and the alternative for a different need ('for chosen pages or a different order, use extract_pages'), plus the precondition that the output folder must already exist.

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