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

Annotations declare a write operation that is not destructive (readOnlyHint=false, destructiveHint=false), and the description explains why: a new file is written, the input is untouched, and existing files are never overwritten. It also states what is returned (the new path). It stops short of describing error behavior, e.g. what happens with an encrypted PDF when no password is supplied.

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 tight sentences, front-loaded with the core action, then semantics, then side effects, then the sibling routing note. No filler and nothing repeated from the schema.

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 the return value (a path) and the non-destructive write contract. Combined with 100% parameter coverage, 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 100%, so baseline is 3. The description adds genuine meaning beyond the schema: pages are 1-based, and reversed ranges like "5-1" are supported — neither of which appears in the schema's page 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?

Opens with a precise verb+resource+scope: 'Write a new PDF containing only the listed pages, in the listed order.' It names the three concrete use cases (range extraction, reordering, dropping pages) and explicitly distinguishes itself from the sibling split_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 explicit when-to-use cases ('pull out a range, reorder pages, drop pages') and an explicit when-not with the named alternative: 'To cut a PDF into equal parts use split_pdf instead.' The routing decision is fully resolved without opening any schema.

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 annotations only covering the safety profile, the description adds substantial behavior: images are embedded without re-compression, unsupported formats fail with an actionable error, the tool writes a new file and returns its path, and existing files are never overwritten. This is consistent with destructiveHint=false and gives the agent real operational context.

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

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

Three tight sentences with no filler, front-loading what the tool does before constraints and return behavior. Every clause carries information (formats, embedding policy, error behavior, return value, overwrite policy).

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, and the description compensates by explaining the return value (a new PDF path) and the no-overwrite naming policy. Combined with format limits and page ordering, 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 100%, so all four parameters are already documented, including ordering for 'inputs' and the 72-points-per-inch margin convention. The description's 'in the order given' largely restates what the schema already says, 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 and resource ('Put JPG and PNG images into one PDF') plus the output structure ('one image per page, in the order given'). This clearly distinguishes it from merge_pdfs and the other PDF siblings, which operate on PDFs rather than images.

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 applicability conditions: accepted formats (JPG/PNG), rejected formats (HEIC/WebP) with a helpful error, and ordering expectations. It never names an alternative sibling (e.g. use merge_pdfs for PDFs, or a converter for HEIC), so the when-not guidance is implied 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the description's 'Read-only: nothing is written' is largely redundant. However, it adds genuine behavioral context beyond the annotations: format-specific degradation (HEIC reports EXIF only) and the set of metadata blocks it surfaces.

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

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

Three tight sentences, front-loaded with what is reported, then format edge case, then read-only guarantee and routing advice. 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?

No output schema exists, so the description compensates by enumerating the returned fields and block types. Combined with the explicit read-only statement and the sibling routing note, an agent has everything needed to select and 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?

A single required 'path' parameter at 100% schema description coverage, so the schema already documents the input fully. The description adds no syntax, format, or constraint detail about the path (e.g., relative vs absolute, remote URLs), which matches 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 ('Report') and resource (photo metadata) and enumerates exactly what is reported: GPS, camera make/model, capture time, editing software, and present blocks. It also scopes supported formats (JPG/PNG/WebP, with HEIC limited to EXIF), which cleanly separates it from the write-side sibling strip_image_metadata.

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 workflow: 'Use before strip_image_metadata to see what would be removed.' The condition that selects this tool over its sibling is stated outright rather than 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); the description adds real behavioral detail beyond them: inputs are never modified, an existing output file is never overwritten (a free name is chosen instead), and a password is required for encrypted inputs. It also discloses the return value (the new PDF's path).

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, front-loaded with what the tool does and the ordering rule, followed by output/return behavior and the encrypted-input caveat. 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?

With no output schema, the description correctly supplies the return value (a path), the non-destructive guarantee, the overwrite policy, and the password prerequisite — everything needed to invoke this tool safely and correctly. Nothing material is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters including ordering and the no-overwrite default. The description restates ordering and adds a usage condition for the password ('if an input is encrypted'), but adds no syntax or format detail beyond the schema, 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 ('Combine several PDFs ... into one') plus the ordering constraint, and names the sibling tool (extract_pdf_pages) relevant to a related-but-different need. An agent can distinguish it from split_pdf or images_to_pdf without opening any schema.

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

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

Explicitly routes the page-subset case to extract_pdf_pages ('To combine only some pages, run extract_pdf_pages first'), which is a concrete alternative with a selecting condition. It does not spell out when-not to use merge_pdfs itself (e.g. vs. split_pdf), but the primary ambiguity is resolved.

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 (readOnlyHint=false, destructiveHint=false), and the description usefully adds that a new PDF is written, its path is returned, the input is untouched, and existing files are never overwritten. The 'Text only, in Helvetica' constraint is a valuable behavioral detail, though return-format specifics beyond 'path' remain thin.

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, then template syntax, then write semantics. No sentence is wasted and the most important constraint (non-destructive output) is clearly stated.

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 correctly notes the return value (the new file path) and the non-overwrite guarantee. For an 8-parameter stamping tool this is nearly complete, though edge cases like password-protected inputs are only covered by the schema field itself.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real value by explaining the {n} and {total} placeholders in template, which the schema only labels as 'Text to print'. It does not expand on start, first_page, or position beyond what the schema states.

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 ('Stamp page numbers on a PDF'), making the operation unambiguous. However, it never names or contrasts with siblings like split_pdf, merge_pdfs, or rotate_pdf, so there is no explicit differentiation for an agent choosing among PDF tools.

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

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

Usage is only implied by the purpose; there is no statement of when to prefer this over alternatives or any prerequisite context. An agent can infer intent from the verb, but the description offers no routing guidance or 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so 'nothing is written' is largely redundant. The description does add genuine value beyond the annotations: the readable-error failure mode for non-PDFs/password-locked files and the assurance that a supplied password is used only locally.

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 with the primary action and return fields front-loaded, followed by usage routing and failure behavior. 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?

With no output schema available, the description compensates by listing the returned fields (page count, page sizes, title, encryption) and the error behavior. It covers everything an agent needs to select and 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%, with both parameters documented in the schema itself. The description only implies the password parameter's purpose ('needs a password') without adding format, source, or handling detail beyond what the schema states, 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?

The description states a specific verb (read/report) and resource (PDF) and enumerates exactly what is reported: page count, page sizes, title, encryption status. This clearly separates it from mutation siblings like split_pdf and rotate_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?

It explicitly tells the agent when to use it ('before split_pdf, extract_pdf_pages or rotate_pdf to learn the page count') and names the concrete downstream tools that depend on this information. The failure conditions (non-PDF, password-protected) further define its operating envelope.

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 valuable context beyond annotations: states input is not modified, existing files are never overwritten, and returns a new path. Annotations declare non-destructive and non-readOnly, but the description clarifies safety and output 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?

Single sentence, front-loaded with core action and constraints, no wasted words. Efficiently communicates scope, limits, and output 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?

Covers key behavioral aspects like input preservation and output path creation. Lacks details on error handling or password usage, but with no output schema and full schema coverage, it is nearly complete for an agent's 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 coverage is 100%, so parameters are fully documented in schema. Description adds no new parameter details beyond what schema provides, such as defaults or format examples. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (rotate) plus resource (PDF pages) with details on scope (all pages or listed ones), rotation values, and permanent save. Clear enough to distinguish from siblings like split_pdf or merge_pdfs.

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?

Implies use for permanent page rotation, but doesn't explicitly name alternatives or when not to use it. Sibling tools handle different operations, so context is clear, but no exclusions are provided.

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, destructiveHint=false and openWorldHint=false, so safety is partly covered. The description adds genuinely useful context beyond that: the input is not modified, existing files are never overwritten, and the return value is a list of files (important since there is no output schema). No auth or size-limit caveats, but the important destructive-behavior questions are answered.

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 what the tool does, then safety behavior, then the sibling alternative. No filler and no redundancy with the schema.

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

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

Covers the operation, the chunking control, the output location and format, the non-destructive/no-overwrite guarantee, and the competing tool. With only 4 simple parameters and no output schema, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description earns above that by interpreting pages_per_file ('N pages each, 1 = one file per page') and describing the output folder destination. It does not add format detail for input/password, 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 (split a PDF), the exact chunking semantics (N pages each, 1 = one file per page), and where output lands. It also differentiates itself from the sibling extract_pdf_pages, so an agent can route between them without reading other schemas.

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

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

Explicitly names the alternative tool and the condition that selects it: 'To keep a custom page range as one file use extract_pdf_pages instead.' That is a concrete when-not-to-use rule, not implied guidance.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description goes well beyond that by disclosing that a copy is written, the original is untouched, existing files are never overwritten, the operation is lossless (no re-encode), HEIC fails, and what the call returns. That is exactly the extra behavioral context the 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 tight sentences, front-loaded with what the tool does and what it preserves, then side effects, then return value, then the routing hint. No filler and nothing repeated from structured 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 carries the burden of explaining the return ('the new path and what was removed') and does so, plus covers failure mode, overwrite behavior, and format limits. 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 100%, so all three parameters (input, output, keep_color_profile) are already documented including the default naming pattern and default true for keep_color_profile. The description adds only the supported-format constraint relevant to input, which the schema does not state; otherwise it does not extend parameter meaning.

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?

Names a precise verb+resource (remove metadata from a photo copy) and immediately scopes the supported formats and the lossless behavior. It also names the sibling inspect_image_metadata, so an agent can distinguish this from the read-only inspector without opening either schema.

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

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

Gives an explicit prerequisite ('Use inspect_image_metadata first to see what is there') and a clear when-not (HEIC is rejected with an error). This routes the agent to the right sibling and prevents a doomed call.

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