benspdf

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

With no annotations, the description carries the behavioral burden. It discloses that the PDF pages are blank, and that omitting output_path keeps it as a temporary artifact while providing a path writes the PDF there. It doesn't mention cleanup or permissions, but for a simple test-file generator these are minor given the self-contained nature.

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 intro sentences establish purpose and limitation, then a compact Args list documents parameters. No redundant or filler sentences; the most important scoping detail ('blank pages') 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?

For a low-complexity tool with three optional parameters and an output schema, the description covers purpose, use context, behavior, and parameter semantics. There is nothing an agent needs in order to select and invoke it correctly that 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?

Although schema description coverage is 0%, the description's Args section fully explains every parameter: output_path optional path or temporary artifact, num_pages as the count of blank pages, and title as metadata. This adds meaning well beyond the bare schema properties and defaults.

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: 'Create a test PDF.' It also explains the intended niche ('handy for trying the other tools') and clarifies the pages are blank, which distinguishes this generator from the sibling PDF-analysis/processing 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 explicitly says this is for 'exercising tools' and 'rather than for anything that needs real content,' giving clear when-to-use guidance. Although it doesn't name an alternative tool, no sibling creates PDFs, so the intended 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It clearly communicates that this is a destructive deletion action, limits its scope to temporary artifacts, and emphasizes that it cannot affect the user's own files, which is essential safety information.

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?

Every sentence earns its place: the first states the action, the second explains a safety constraint, the third provides usage context, and the final line documents the parameter. No fluff or unnecessary 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 simple single-parameter destructive tool, the description provides everything an agent needs to invoke it correctly and safely: what it deletes, what it cannot delete, when it is appropriate, and how to specify the targets. The output schema exists, so return-value details are not needed.

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 0%, so the description must explain the parameter, and it does: 'refs: Artifact id, or list of artifact ids, to delete.' This adds the crucial semantic that refs are artifact ids rather than file paths, which is not present in the input 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 uses a precise verb and resource: 'Delete temporary artifacts from the workspace.' It clearly distinguishes the tool from file-related siblings by stating it only accepts artifact ids, never file paths, and therefore cannot delete the user's own files.

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

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

The description explicitly states when the tool is needed ('only needed when the user explicitly asks to clean up') and when it is not ('Artifacts expire on their own'). It also gives a hard constraint: inputs must be artifact ids, not file paths.

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 provided, the description carries the full burden, and it does so well. It discloses filesystem writes, directory creation when missing, overwrite behavior, and the default safety intent ('nothing is destroyed by accident'). It also warns about artifact expiration, which is important behavioral context for the agent.

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 usage rule, then moves to a structured Args explanation. It is longer than minimal, but every sentence earns its place: usage timing, filesystem exclusivity, artifact expiry warning, and detailed parameter instructions. The structure is easy to parse.

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 4-parameter complexity and an output schema that likely describes the return value, the description is complete. It covers when to use the tool, what it does, how parameter interactions work, directory creation, overwrite safety, and naming templating. An agent has everything needed to invoke 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 0%, so the description fully compensates. It explains each parameter in the Args section: refs as artifact id or list, dest as file path or directory, name as a filename template with placeholders like '{n:03d}{ext}', and overwrite semantics with defaults. This goes well beyond the bare 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 uses a specific verb and resource: 'Save one or more results to a real location on disk.' It also differentiates the tool from its siblings by explicitly stating it is 'the only tool that writes to the user's filesystem.' This makes the tool's purpose unmistakable.

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

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

The description gives explicit usage timing: 'call it once at the end, when they have said where the output should go.' It also provides a clear when-not-to-use rule by warning never to hand an artifact id back as a finished file and explaining that artifacts expire. This effectively distinguishes when export is needed versus when it is not.

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 provided, the description carries the full burden. It discloses that results are ordered newest first, and the term 'temporary' implies the artifacts are ephemeral. It doesn't mention side effects, but listing is inherently read-only, and the description aligns with that expectation. It adds useful behavioral context beyond a generic 'list' 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?

The description is two sentences plus a one-line Args section. The purpose is front-loaded, the usage scenario follows immediately, and the parameter explanation is concise. No wasted words.

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 format is covered. The description explains what the tool does and when to use it, and the parameter is documented. It lacks only minor details like whether the list is exhaustive or paginated, but for a simple list with a limit, this is adequate.

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 0%, so the description must explain parameters. It explicitly states 'limit: Maximum number of artifacts to return,' which adds meaning beyond the schema's simple integer type and default value. This fully compensates for the lack of schema description.

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 verb 'list', the resource 'temporary artifacts', and the ordering 'newest first'. It distinguishes itself from the sibling PDF tools and other operations like discard/export by specifying exactly what it does and the context of workspace artifacts.

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

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

The description provides a clear scenario for when to use this tool: when you've lost track of an artifact ID and want to find it again. While it doesn't explicitly name alternatives or say when not to use it, the context is specific enough to guide an agent effectively.

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 provided, the description carries the full behavioral burden and does so thoroughly. It explains the distinct meanings of encrypted and needs_password, defines permissions vs. restrictions, covers the unencrypted case, and clarifies that restrictions are statements of intent rather than enforced barriers. It also notes that it can answer even when pages cannot be read.

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 longer than average but every section earns its place: purpose, key distinctions, interpretation guidance, and when-to-use context. The main purpose is front-loaded in the first two sentences, and the argument documentation is cleanly separated at the end.

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 conceptual complexity of PDF encryption, the description is complete. It explains edge cases, defines the output semantics without relying on the output schema, gives usage context relative to other tools, and documents the single parameter. Nothing an agent needs to decide whether and how to call this tool 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?

The input schema only describes ref as a string with no explanation, and schema coverage is 0%. The description compensates fully by stating 'ref: PDF file path, or a workspace artifact id,' which gives the agent the two acceptable forms of the argument. This is exactly the guidance the schema lacks.

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 action and resource: 'Check a PDF's encryption and what it permits: printing, copying, editing.' It also gives the core question it answers, 'is this locked, and what am I allowed to do with it?', which clearly separates it from metadata or text extraction siblings. The nuance about encrypted vs. needs_password further sharpens its identity.

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 says when to reach for this tool: when another tool reports a file as encrypted, this one still works because the encryption dictionary is readable. It also connects to pdf_extract_text to warn that denied permissions are not enforcement, teaching the agent how to use the result correctly in a multi-tool workflow.

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 provided, the description carries the full burden, and it does so exceptionally. It discloses the sampling behavior (up to 10 pages), what a 'sampled' verdict means, the meaning of each verdict value, and that it returns per-page evidence such as image_coverage.

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 purpose consuming no fluff. Every sentence adds meaningful detail — verdicts, sampling, output evidence, and exclusions — while staying compact and 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?

The description covers the decision this tool answers, the important caveat about sampling, the shape of the result, and the clear boundary against text extraction and OCR. An agent has everything it needs to select and invoke this tool correctly, and the output schema covers the remaining return details.

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 0%, but the description fully compensates by defining `ref` as 'PDF file path, or a workspace artifact id.' For a single-parameter tool, this is sufficient and adds exactly the semantic meaning the schema lacks.

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 and resource: 'Check whether a PDF has a text layer, looks scanned, or needs OCR.' It clearly distinguishes itself from siblings like pdf_extract_text and pdf_ocr by stating what it does not do.

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 says when to run the tool: 'Worth running before extracting text from a file you have not seen.' It also names the alternative for text extraction (pdf_extract_text) and states that it does not run OCR, giving clear 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses performance characteristics (milliseconds per page), exactness of characters, truncation behavior around ~50,000 characters, what `truncated` means, artifact-writing behavior for output='txt', and the text_suspect caveat about undecodable fonts. This is exemplary behavioral disclosure.

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 detailed but every sentence earns its place: each clause either defines a behavior, gives usage guidance, or explains a parameter. The first sentence is a clear one-line purpose, and the nuanced details are logically organized.

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, the description is complete: it covers how to invoke it, what to expect, how to handle truncation, when to choose alternatives, and how to handle suspicious output. 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 description coverage is 0%, so the description must compensate. The Args section adds meaningful semantics for all four parameters: ref accepts a file path or artifact id, pages gives concrete syntax examples, output enumerates valid values and their effects, and layout explains when it matters. This fully compensates for the bare 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 opens with a specific verb and resource: "Read the text of a PDF... page by page." It clearly differentiates the tool from pdf_ocr, pdf_render_pages, and pdf_check_text, so an agent knows exactly what this tool does and what it does not do.

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?

Usage guidance is explicit and actionable: prefer this over pdf_ocr for pages with text, over pdf_render_pages when exact cheap text is needed, consult pdf_check_text to choose a path, use output='txt' for long books, and use pdf_render_pages for text_suspect pages. This leaves no ambiguity about when to select 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 provided, the description carries the full burden. It discloses the dual-storage nature (Info vs XMP), the normalized output with sources and conflicts, and the presence of has_conflicts. It even instructs the agent on how to behave when conflicts exist, which is beyond typical transparency.

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

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

The description is well-structured: a clear purpose sentence, a negative definition that routes to alternatives, a detailed but necessary explanation of the output behavior, and a final args block. It is efficient and front-loads the most important information without fluff.

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 (metadata conflicts) and the existence of an output schema, the description still adds critical context about how to interpret the returned data (sources, conflicts, has_conflicts). It covers what the tool returns, how conflicts are resolved, and the dual stores. 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?

The only parameter ref is explained as 'PDF file path, or a workspace artifact id.' This adds semantic meaning beyond the schema's bare 'string' type. Since schema coverage is 0%, this explanation fully compensates for the absence of parameter descriptions 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?

The description opens with a specific verb and resource: 'Read a PDF's document properties: title, author, dates, producer, keywords.' It clearly distinguishes itself from siblings by naming pdf_page_count and pdf_check_text as alternatives for different tasks, so an agent can immediately tell what this tool does and what it does not.

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

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

The description explicitly states when NOT to use this tool: 'It does not count pages (use pdf_page_count) and says nothing about whether the pages hold readable text (use pdf_check_text).' It also gives operational guidance on how to handle conflicting metadata, advising to report has_conflicts rather than quoting a single value as fact. This covers both exclusions and usage context.

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 provided, the description carries the full behavioral burden and does it well: it discloses Tesseract system dependency and error handling, warns that OCR can be confidently wrong, explains confidence reporting, notes that text pages are skipped unless force, and describes early-stop/truncation 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?

The description is detailed but every sentence serves a purpose. It front-loads the core action, then provides targeted caveats, usage routing, and parameter semantics. No wasted words, and the structure makes the content easy 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 complex OCR tool with no annotations, the description is complete: it addresses external dependencies, failure modes, confidence interpretation, edge cases (text pages, truncation), and all parameters. The output schema presumably covers return values, so the description does not need to duplicate that.

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

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

Schema description coverage is 0%, so the description must fully compensate. The Args section explains every parameter: ref format, pages syntax and default, lang format, dpi range and suitability, output options, and force semantics. This goes well beyond the bare 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 clear verb and resource: 'Read a scanned PDF with OCR, and optionally add a real text layer to it.' It also differentiates from siblings by saying to prefer it to pdf_render_pages for reading and to run pdf_check_text when unsure, so an agent can distinguish it 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?

The description explicitly says when to use this tool ('a scan, or an export that lost its text') and gives direct alternatives: 'Prefer it to pdf_render_pages for reading; run pdf_check_text when unsure.' This gives the agent clear routing guidance relative to sibling tools.

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 provided, the description carries the full burden. It discloses that it reads only the page tree, stays cheap on large files, and lists what it does not read. It does not mention error conditions or explicitly state read-only behavior, but the phrasing implies no side effects. This is adequate for a simple count 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?

The description is concise, with a clear first sentence stating the purpose, followed by a brief explanation of scope and the parameter. No redundant or filler content.

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 tool with one parameter and an output schema, the description covers the core behavior and scope. It could mention potential errors (e.g., invalid file path) or the exact return format, but the output schema likely handles return details. Overall, it is sufficiently complete for an agent 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?

The schema provides only the parameter name 'ref' with no description, and schema coverage is 0%. The description compensates fully by explaining that 'ref' is a PDF file path or a workspace artifact ID, adding essential 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 clearly states the tool counts pages in a PDF and explicitly distinguishes it from siblings by noting it reads only the page tree, not text, sizes, or properties. This makes the purpose unambiguous and separates it from pdf_metadata, pdf_extract_text, and pdf_page_layout.

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

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

The description gives clear context on what the tool does and does not do ('does not read page text, page sizes, or document properties'), which implies when not to use it. However, it does not name specific alternative tools like pdf_metadata or pdf_extract_text, so the guidance is implicit rather than 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?

With no annotations, the description carries the full behavioral burden, and it does so thoroughly. It explains that only page geometry is read, that pages are grouped by shape with page-range notation, that sizes are computed by clipping CropBox to MediaBox and applying /Rotate, and that a 3pt tolerance is used for grouping. It also discloses that per-page output is capped at 100 rows.

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 delivers dense, useful details about behavior, grouping, parameter formats, and alternatives. Each sentence contributes necessary information, and the final Args block cleanly summarizes the two parameters without redundancy.

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?

The description covers what the tool returns conceptually, how it handles real-world page size variance, how rotation affects reported sizes, how to request per-page details, and what to use instead for text content. Since an output schema is present, the absence of exhaustive return-field documentation is not a 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 0%, so the description must compensate, and it does. It explains that 'ref' accepts either a PDF file path or a workspace artifact id, and it defines 'pages' with concrete range formats like '1-20', '3', '1,5,9-12', or 'all', plus the 100-row cap.

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 and resource: 'Measure a PDF's page sizes, orientation and rotation.' It also frames the tool around concrete questions, which makes its purpose unmistakable. It further distinguishes itself from text-related siblings by explicitly stating it does not look at page content and points to pdf_check_text for that.

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

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

The description clearly states when to use this tool: for page geometry and understanding inconsistent sizes or rotation, while noting it stays cheap on long documents. It also gives a direct alternative, pdf_check_text, for readable-text questions, which is an explicit when-not-to-use condition.

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 provided, the description carries the full burden. It discloses that every page is saved as a PNG artifact, that with view=true images are returned, that limits exist (20 pages per call), and that resolution reduction is reported. It even explains why images are expensive in context. This is highly transparent.

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

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

The description is well-structured and front-loaded. It starts with the core purpose, then usage guidance, then behavioral details, then parameter explanations. Each sentence adds value; there is no redundancy or fluff.

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 having no output schema and no annotations, the description is complete: it covers what the tool does, when to use it, how it behaves (including limits and side effects), and all parameters with defaults and examples. 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 0%, so the description must compensate. It explains each parameter: ref (file path or artifact id), pages (formats like '1-20', 'all', defaults to all), dpi (range 36-600, suggests 150), and view (returns images vs ids). This adds significant meaning beyond the bare 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 clearly states the verb (Render) and resource (PDF pages to images) and explains the purpose: to look at a page rather than read it. It distinguishes from siblings by explicitly naming pdf_ocr as the alternative for reading, and gives concrete use cases (checking redaction, split, handwriting, signatures, charts).

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

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

The description explicitly says when to use this tool ('Use it to see what a page looks like') and when not ('For reading a scan prefer pdf_ocr'), with conditions (when OCR is unavailable or would mangle). This is clear guidance with alternatives.

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