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

With no annotations, the description carries the full burden and does reasonably well: it discloses the compression mechanism, expected size reduction (30-80% for image-heavy files), that text remains selectable, and that incompressible files are returned unchanged rather than inflated. It omits permission/runtime details and how image quality degrades at higher levels.

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 short sentences, each earning its place, with the core purpose and mechanism front-loaded before the motivating scenario and edge-case behavior.

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 3-param mutation tool with no output schema and no annotations, the description covers purpose, effect, and the unchanged-file edge case well. Minor gaps remain around overwrite semantics and permission needs.

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 file, level, and output_path are fully documented in the schema, including the DPI mapping for each enum value. The description adds nothing beyond what the schema already provides, 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 (shrink) and resource (PDF) plus the mechanism (downsampling images), which uniquely distinguishes it from all siblings like merge_pdfs, split_pdf, and ocr_pdf.

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 clear when-to-use context ("when a PDF is too large to email or upload") and notes that already-optimized files come back unchanged, implying a no-op guard. It stops short of naming alternative siblings or explicit exclusions.

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?

With no annotations, the description carries the full burden and does disclose the key behavioral traits: the output encoding (UTF-8), the performance profile (fast and exact with a text layer), and the failure mode plus remediation for scanned PDFs. It does not mention that the default output_path causes the tool to write a file to disk rather than only returning text, nor any error/permission behavior, so it falls 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 short sentences, zero filler, and the primary capability is front-loaded ahead of the caveat and the alternative. Every sentence carries a distinct piece of information (output, success condition, failure condition + fallback).

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 2-parameter tool with no output schema and no annotations, the description covers the return value type and the critical input-quality precondition, which is what an agent needs to call it correctly. The only gap is that the file-writing side effect implied by output_path is left entirely to the 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 description coverage is 100%, so both parameters (file, output_path, including the '-papyrio.txt' default) are already documented in the schema. The description adds no syntax, format, or path-handling detail beyond what the schema provides, 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 ('Return the text of a PDF as UTF-8') and explicitly contrasts itself with the sibling ocr_pdf by naming the condition that distinguishes them (text layer vs. scanned). An agent can select this over the other eleven 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?

Gives an explicit when-to-use ('Fast and exact when the PDF already has a text layer'), an explicit when-not ('A scanned PDF has none'), and names the alternative to run first ('run ocr_pdf on it first'). The routing decision is fully resolved in the description.

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?

With no annotations, the description carries the full behavioral burden. It discloses the transformation semantic (one image becomes one PDF page) and supported formats, but says nothing about overwrite behavior, whether the source image is modified, permissions, or typical failure modes on corrupt/unsupported files.

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?

Two short sentences, zero waste, with the core action front-loaded and the use case following. Nothing to trim.

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 simple two-parameter conversion with full schema coverage, the description is nearly sufficient. Since no output schema exists, it could say more about what is returned or where the result lands, though output_path's schema description partially covers this.

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 (file, output_path, including the default '-papyrio.pdf' suffix) are already fully documented in the schema. The description's format list marginally enriches the 'file' parameter but adds no syntax beyond the 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 ('Wrap a ... image in a PDF page') and enumerates the accepted input formats (JPG, PNG, WebP). No sibling performs this direction of conversion (pdf_to_jpg is the inverse), so an agent can place it immediately.

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 a clear when-to-use trigger: 'when an image needs to be submitted or printed as a PDF.' It does not name exclusions or alternatives, but among the sibling set there is no competing tool for image→PDF, so the gap is minor.

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?

With no annotations, the description carries the full burden and does reasonably well: it discloses the input-count bounds, order preservation, the default output naming convention, and the password prerequisite. It omits error behavior (missing/corrupt files, existing output file overwrite) but covers the operationally important traits.

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?

Two short sentences, front-loaded with the core operation and count constraint, then usage context and the prerequisite. No filler or repetition.

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 two-parameter tool with no annotations and no output schema, the description covers the operation, ordering, output destination default, and a blocking prerequisite. Only return value details (e.g., whether the merged path is echoed back) are unaddressed, which is minor.

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 both parameters are already documented in the schema. The description's 'in the order given' reinforces the ordering semantics of `files` but adds no format or path syntax detail beyond what the schema provides; 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 (combine) and resource (PDFs) plus the hard constraint (2 to 10) and ordering guarantee. An agent can instantly distinguish this from split_pdf, compress_pdf, or any conversion sibling.

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 usage scenarios (scans, chapters, invoices) and a clear prerequisite ('Password-protected files must be unlocked first'), which implicitly routes to unlock_pdf. It stops short of naming that sibling or stating when not to use this tool.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the DPI quality threshold (300+ good, <150 degrades badly), but omits whether the input file is modified in place, language support, and processing-time expectations for a potentially slow operation.

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

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

Three tight sentences, front-loaded with the core action and effect, followed by usage and constraint. No redundancy or 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, but the description plus the schema's output_path default adequately convey the write-and-return-a-file behavior. The main remaining gap is language handling and whether the source file is left untouched.

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 both parameters are fully documented there, so the baseline is 3. The description adds contextual input framing ('scanned PDF', quality constraints) but no syntax or format detail 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 precise verb+resource+effect: 'Add a searchable text layer to a scanned PDF, making it selectable and searchable.' This clearly separates it from siblings like extract_pdf_text or pdf_to_word, which consume text rather than generate it.

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 guidance ('Use this before extracting text from a scan or a photographed document'), including a quality precondition tied to DPI. It implies extract_pdf_text as the follow-on step but does not name it as an alternative or state when-not to use OCR.

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?

No annotations are provided, so the description carries the full disclosure burden. It does disclose a real behavioral trait — that fonts, tables, images and page layout are preserved, implying high-fidelity conversion — but says nothing about overwrite behavior, failure on unsupported formats, password-protected inputs, or size limits.

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?

Two tightly written sentences: the capability and its supported formats come first, the motivation second. No filler, no restatement of the tool name, and every clause earns its place.

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 two-parameter tool with full schema coverage and no output schema, the description supplies the essentials: what converts, what fidelity to expect, and the purpose. It is only marginally incomplete in that it does not mention the return value or where errors surface, which matters somewhat given there is no output 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 description coverage is 100%, so both 'file' and 'output_path' are already fully documented, including the default '-papyrio.pdf' suffix rule. The description adds no parameter-level detail beyond what the schema provides, which is the expected baseline when the schema does the heavy lifting.

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 concrete verb+resource ('Convert ... to PDF') and enumerates the accepted input formats (.doc, .docx, .odt, .ppt, .pptx, .xls, .xlsx), which effectively separates it from image_to_pdf, webpage_to_pdf and pdf_to_word. It does not name any sibling, so the differentiation is implied via format scope rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The sentence 'Use this to turn an Office file into something fixed and shareable' gives a general context, but there are no explicit when/when-not rules and no alternatives named (e.g., use image_to_pdf for bitmaps, webpage_to_pdf for URLs). Usage is implied rather than guided.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that every page is rendered and results are packaged as a ZIP, but omits image resolution/quality controls, behavior on encrypted PDFs, and any filesystem write implications beyond the schema note.

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?

Two sentences with no filler; the output contract is front-loaded before the usage hint. Every clause earns its place.

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 simple two-parameter transform with fully covered schema and no output schema, the description conveys the essential return shape (ZIP of per-page JPGs) and the intended use. Only finer details like DPI or page ordering are missing, which is minor here.

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 'file' and 'output_path' are already documented with their defaults. The description adds no parameter-level detail (e.g. what output_path accepts when it names a directory), matching the baseline 3 when the schema does the heavy lifting.

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 (Render), resource (every page of a PDF), output format (JPG) and container (ZIP archive). This clearly separates it from the reverse-direction sibling image_to_pdf and from text-oriented siblings like extract_pdf_text and ocr_pdf.

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 use-case context ('when the pages are needed as pictures, for a thumbnail, a slide or an image pipeline'), which tells the agent the intended scenario. It stops short of naming alternatives or exclusions, so an agent must still infer when ocr_pdf or image_to_pdf is the better pick.

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?

With no annotations, the description carries the behavioral burden and does disclose the key trait: success depends on the PDF being text-based rather than a scan, with the failure path and its remedy stated. It stops short of covering output fidelity caveats, failure modes for malformed files, or the '-papyrio.docx' naming behavior (left to the 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?

Three short sentences, front-loaded with the core action, then the compatibility qualifier, then the remedy. No filler and nothing that could be cut without losing routing 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, but the tool's contract is simple (input file, output path) and fully specified in the schema, while the description supplies the one non-obvious operational condition (scanned input requires OCR first). Minor gap: no statement of what the returned result is or how failures surface.

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 both parameters (file, output_path) are already fully documented including the default suffix. The description adds no parameter-level syntax or constraint beyond what the schema provides, 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 and resource ('Convert a PDF into an editable Word document') plus a fidelity qualifier about which source PDFs convert cleanly. It also names the sibling ocr_pdf for the scanned case, so an agent can distinguish it from the other 11 conversion/manipulation 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 states when it works well (PDFs exported from Word, Google Docs, InDesign) and when it will not (scanned PDFs), and routes that case to a named alternative with the exact prerequisite action ('run ocr_pdf on it first'). This is a complete when/when-not/alternative statement.

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?

With no annotations, the description carries the full burden. It discloses the encryption standard (AES-256) and the access consequence, which is useful. It does not address whether the original file is preserved or overwritten, password strength/format constraints, or failure behavior, leaving meaningful gaps 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?

Two tight sentences: the capability first, the actionable motivation second. No filler, no redundancy, and the key fact (AES-256) is front-loaded.

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 and no annotations, but the description plus a fully-covered 3-param schema give the agent enough to invoke correctly. The main omission is whether the source PDF is left intact or modified in place, which the description could state.

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 three parameters (file, password, output_path) are fully documented in the schema, including the default output suffix. The description adds no parameter-level meaning beyond that, 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 (encrypt) and resource (PDF) plus the concrete mechanism (AES-256) and resulting effect (cannot be opened without the password). This cleanly distinguishes it from the inverse sibling unlock_pdf without needing 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?

"Use this before sending a document that contains anything private" gives an explicit when-to-use trigger tied to a real scenario. It stops short of naming the alternative (unlock_pdf) or stating when not to use it, so it is strong context rather than 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?

No annotations exist, so the description carries the full burden. It usefully discloses the return artifact (a ZIP of per-page files), which is real added value, but says nothing about whether the source PDF is modified, how files inside the ZIP are named, or failure behavior on encrypted/corrupt PDFs.

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?

Two short sentences, output behavior front-loaded before the use case. Every clause earns its place with 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?

With no output schema and no annotations, the description adequately covers the essential contract: input is a PDF path, output is a ZIP of single-page files. Remaining gaps (source file preservation, in-ZIP naming, error cases) are minor for a simple utility.

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 (file, output_path) and the default '-papyrio.zip' naming are already fully documented in the schema. The description adds no syntax or format detail beyond that, 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 ('Separate every page of a PDF into its own file') and names the exact output form (ZIP archive). No sibling in the list does anything similar, so an agent can route to it unambiguously.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence gives a concrete use case: pulling single pages out of a long document. It does not name an alternative or a when-not condition (e.g., use extract_pdf_text to read pages without splitting), but the sibling set is non-overlapping so ambiguity is low.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that decryption uses the supplied password and will not attempt cracking, and the schema covers the output default, but it says nothing about what happens on a wrong password, whether the input file is ever modified in place, permission requirements, or error behavior.

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?

Two tight sentences, zero filler, with the core action and its scope limitation front-loaded. Every clause earns its place.

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 three-parameter tool with no annotations and no output schema, the definition covers the essential semantics and defers output-path behavior to the schema. Minor gaps remain around failure modes and whether the source PDF is left untouched.

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%, with all three parameters documented in the schema including the output_path default naming convention. The description adds no parameter-level 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 precise verb (remove/decrypt) and resource (password-protected PDF) and clarifies scope by ruling out cracking or guessing. An agent can tell instantly how this differs from protect_pdf and from any hypothetical password-recovery tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'a PDF you already know the password for' gives a clear precondition for use, and 'does not break or guess encryption' is an explicit when-not. It does not name a sibling alternative, but for this operation none is really needed since protect_pdf is the inverse rather than a substitute.

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?

No annotations exist, so the description carries the full behavioral burden. It usefully discloses the headless-browser mechanism and the 'public URL' constraint (implying authenticated pages will fail), but says nothing about timeouts, JavaScript rendering limits, failure behavior, or what is returned beyond the written PDF.

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 short sentences, front-loaded with the core action and with no filler. The final sentence partially duplicates the schema's required marker on output_path, a minor redundancy keeping it shy 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 simple two-parameter conversion tool with no output schema or annotations, the description covers the essentials: what it does, the input type, and the required output path. Only edge-case behavior (rendering fidelity, failures on non-public URLs) is absent, which is acceptable at this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in the schema; baseline 3 applies. The sentence 'output_path is required' merely restates the schema's required list and parameter text rather than adding format or constraint 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 chain (fetch a public URL, render to PDF in a headless browser) and the resource (web page). It also implicitly separates itself from file-based siblings like image_to_pdf and office_to_pdf by noting it 'takes a URL rather than a file', so an agent can route 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?

'Use this to archive or print a web page' gives clear intended-use context, which is stronger than most siblings. It stops short of explicit when-not guidance (e.g., non-public, auth-walled, or JS-heavy pages, or when the sibling pdf_to_jpg etc. would be more appropriate).

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