pdf-mcp

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

Annotations indicate a mutating operation (readOnlyHint false) that is idempotent (idempotentHint true). The description adds a small amount of behavioral scoping by specifying 'text watermark' and 'one PDF', but it does not disclose whether the original file is preserved, what the output format is, or the temporary URL requirement (the latter is in the schema). No contradiction exists between description and annotations.

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

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

The description is a single 8-word sentence with no filler or redundancy. It is front-loaded with the action and object. While a bit more guidance would be useful, the structure is appropriately minimal for a clear purpose.

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 moderate complexity (8 parameters, 3 required) and the presence of an output schema, the description is minimally adequate. It mentions the single-PDF scope but does not explain the operational flow (download, watermark, return) or usage relative to sibling tools. This leaves gaps that an agent might need to fill by inspecting the schema or 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?

All 8 parameters are documented in the schema with 100% coverage, so the description does not need to explain them. The description contains no parameter-specific details, but it also does not conflict with schema descriptions. Baseline 3 is appropriate because the schema carries the burden.

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 ('Add') and a specific resource ('text watermark to one PDF'), making the tool's function unambiguous. It clearly differentiates from siblings like merge_pdfs and split_pdf by focusing solely on watermarking. There is no ambiguity about what action is performed.

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 no information about when to choose this tool over alternatives such as merge_pdfs, split_pdf, or conversion tools. It neither states typical use cases nor excludes scenarios where another tool would be more appropriate. An agent is left to infer usage solely from the tool name and sibling list.

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 indicate readOnlyHint=false and idempotentHint=true, so the description doesn't need to restate them. The description adds little beyond the core conversion behavior and doesn't disclose side effects, failure behavior, or async behavior. Still, nothing contradicts the annotations, and the 'directly' phrasing gives a small behavioral hint.

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 a single, front-loaded sentence that wastes no words. It conveys the action, input type, output format, and one-step nature 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?

Given the simple two-parameter schema and the presence of an output schema, the description covers the essential need-to-know information. It doesn't mention limitations like file size or unsupported formats beyond PDF/image, but those are reasonable gaps for a straightforward conversion tool.

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

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

Schema description coverage is 100%, with both file_url and idempotency_key already well-described. The tool description adds no parameter-level detail, so it appropriately relies on the schema. This matches the baseline expectation for full coverage.

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 ('Convert'), a specific input ('one PDF or image'), and a specific output ('Excel workbook (XLSX)'). This clearly distinguishes it from siblings like convert_file_to_markdown and convert_file_to_word, and the word 'directly' adds a meaningful one-step nuance.

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 makes the tool's use case obvious: choose this when you need an XLSX result from a PDF or image. It does not explicitly exclude alternatives or name sibling tools, but the output-format framing provides clear contextual guidance.

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

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

Annotations already cover the safety and idempotency profile (readOnlyHint=false, idempotentHint=true), and the description adds only 'directly' and 'one' as behavioral nuance. It does not disclose the task-based flow strongly implied by the required idempotency_key and the sibling get_pdf_task/list_pdf_tasks, so the agent must infer that conversion may be asynchronous.

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

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

A single, front-loaded sentence with zero filler — verb, resource, and output format arrive in the first six words. It is efficiently structured, though slightly under-sized given it omits the async workflow context that would make it complete.

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 and both parameters are fully documented, so inputs and return values are covered. The clear gap is workflow context: the sibling get_pdf_task and the required idempotency_key suggest this initiates an asynchronous conversion, yet the description never signals that the Markdown result may need to be fetched via a follow-up call.

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

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

Schema description coverage is 100%, so file_url and idempotency_key are already fully documented with meaningful descriptions. The tool description adds no parameter-level meaning beyond restating that a PDF or image is the input, 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?

The description states a specific verb (Convert), a resource (one PDF or image), and a target output format (Markdown). Naming 'Markdown' directly distinguishes it from the sibling converters convert_file_to_excel and convert_file_to_word, and 'one' sets it apart from merge_pdfs/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?

The selection criterion is implied: use this tool when Markdown output is desired, since no other sibling produces Markdown. However, there is no explicit when-to-use or when-not-to-use guidance, and no routing to related workflow tools such as get_pdf_task for retrieving a conversion result.

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 and idempotentHint=true. The description adds that it converts 'directly' and handles one file, but does not disclose details about file creation, input preservation, or potential side effects. This is acceptable given the annotations cover the safety/idempotency profile.

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 zero superfluous content. The core action is front-loaded, followed by a targeted usage guideline. The missing space after 'DOCX).Use' is a minor typo that does not affect clear understanding.

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 simplicity, full schema coverage, output schema presence, and annotations, the description covers purpose and usage adequately. It could mention limitations like file size or accepted image formats, but these are not essential for safe invocation.

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

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

Schema description coverage is 100%: both file_url and idempotency_key are fully described in the schema. The description adds no parameter-specific meaning, so the baseline of 3 applies.

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

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

States the exact function: converts a PDF or image directly to a DOCX. The specific verb 'Convert', the resource 'PDF or image', and target 'Word document (DOCX)' make it clearly distinguishable from sibling conversion tools like convert_file_to_excel and convert_file_to_markdown.

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 instructs when to use this tool ('whenever mathematical or table formulas must be extracted') and provides a when-not by warning against manual transcription. This gives an agent a concrete decision rule without needing to inspect 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?

The readOnlyHint=true annotation already covers safety, and the description adds the 'current user's' authorization scope, which is useful. It does not disclose polling/readiness semantics (e.g., that the task may still be processing or the result absent), but this is not a contradiction with annotations.

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

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

A single sentence with no filler; the action and resource are front-loaded. Nothing extraneous is included.

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 one well-described parameter, an output schema, and a read-only annotation, the definition is largely adequate. The main gap is the lack of guidance distinguishing it from list_pdf_tasks, but complexity is low enough that an agent can call it correctly with a task_id.

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

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

Schema coverage is 100% and the task_id property is described as 'task identifier returned by a PDF tool.' The tool description adds no parameter-level meaning beyond this, so it meets the baseline without enhancing it.

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 names a specific action ('Get'), a resource ('the current user's PDF task status and result'), and a singular task scope. It is clear but does not explicitly contrast itself with list_pdf_tasks, so an agent must infer that this is the single-task retrieval counterpart.

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?

There is no statement about when to call this tool rather than list_pdf_tasks or when to poll. The only contextual clue is the schema's task_id description ('returned by a PDF tool'), which lives outside the description, so the description itself offers no usage routing.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful context by enumerating exactly what information is returned: supported formats, file-count limits, and size limits. No contradiction exists between description and annotations.

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

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

The description is a single, direct sentence with no filler or redundant words. It front-loads the action 'Get' and immediately specifies the resource and the exact information returned.

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 has no parameters, a read-only annotation, and an output schema, the description fully covers what an agent needs to know. It is complete for a simple capability-inquiry tool.

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

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

The tool has zero parameters, and the schema confirms this with an empty object. With no parameters to document, the description cannot add parameter meaning, so the baseline score of 4 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 clearly states the tool gets the PDF Toolkit's supported formats and file-count/size limits. This is specific and distinct from the sibling tools, which all perform file transformations or task management operations.

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 purpose is unambiguous, and no sibling tool overlaps with this capability, so the usage context is clear even though alternatives are not explicitly mentioned. It does not state when-not-to-use, but such exclusions are unnecessary given the unique role of 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?

Annotations already indicate idempotentHint=true and readOnlyHint=false, so the safety profile is known. The description adds the behavioral guarantee that image order is preserved, which is useful context beyond the schema. However, it does not disclose any other runtime behavior such as output handling or failure modes.

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

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

A single, focused sentence with no filler. The core action and the ordering constraint are front-loaded, making it easy to parse quickly.

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 3-parameter tool with a fully documented schema, idempotency annotation, and an output schema present, the description covers the essential behavior. It lacks usage differentiation, but that is a separate dimension and not critical to invoking this tool correctly.

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

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

Schema description coverage is 100%, so parameters are already well documented. The description's 'supplied order' note aligns with the schema's image_urls description but adds no new meaning beyond it.

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?

Description clearly states a specific action ('Combine images') and resource ('into a PDF'), plus the key constraint of preserving supplied order. It is easily distinguished from sibling tools like merge_pdfs (PDFs as input) and file conversion 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?

No guidance is given about when to choose this tool over alternatives such as merge_pdfs or convert_file_to_pdf-style tools. The intended use is implied by the name and description, but there are no explicit conditions, exclusions, or alternative routing.

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 carry readOnlyHint=true, and the description adds the scoping constraint that tasks belong to the current user and that results are paginated. It does not disclose ordering, status filtering, or auth requirements, but with annotations covering the safety profile this is adequate.

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

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

A single ten-word sentence, front-loaded with the verb and resource. No filler or repeated schema 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 paginated list with an output schema and readOnly annotation, the description states the essential scope (current user) and behavior (pagination). Missing details like ordering are not necessary for correct invocation given the output schema and optional parameters.

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 covers 100% of parameters with descriptions for limit and cursor, so the description need not repeat them. 'with pagination' loosely hints at the two parameters but adds no semantic 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?

The description names a specific verb ('List'), a resource ('the current user's PDF tasks'), and a mode ('with pagination'). This clearly separates it from sibling get_pdf_task, which targets a single task.

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 implies a list scenario but never states when to prefer it over get_pdf_task or how it relates to other sibling tools. No exclusions or alternative routing is provided, so usage guidance is only implied.

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

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

Annotations already communicate idempotency and non-read-only behavior. The description adds the ordering behavior, which is useful, but it does not disclose potential side effects such as whether the original PDFs are modified or whether a new file is created.

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 a single, focused sentence that avoids filler. The key ordering constraint is included immediately, making it 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?

For a straightforward single-purpose tool, the description plus rich input schema and output schema covers the essential invocation details. It does not provide explicit routing to alternatives, but that gap is already reflected in the usage_guidelines score.

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 parameters are already well documented. The description adds no parameter-level detail beyond what the schema provides, matching the baseline for fully-covered schemas.

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 the exact verb ('merge'), the resource ('PDFs'), and a meaningful constraint ('in the supplied order'). This clearly distinguishes it from siblings like split_pdf, add_pdf_watermark, and conversion 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?

The description implies when to use the tool: when multiple PDFs need to be combined in a given order. However, it does not explicitly state when not to use it or name alternative tools, leaving the usage guidance 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 provide idempotentHint=true and readOnlyHint=false, and the description adds no behavioral context beyond the core operation. It does not mention output side effects, task submission, or what happens to the original file, so it adds little beyond the structured annotations.

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

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

The description is one short, front-loaded sentence with no filler. Every word contributes to the meaning, and the core operation is immediately clear.

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 a fully described schema, an output schema, and idempotency annotations, the one-line description covers the essentials of invoking the tool. However, it does not mention the task-based workflow suggested by sibling tools like get_pdf_task and list_pdf_tasks, leaving some operational context implicit.

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 all three parameters already described clearly, including the 1–50 range for pages_per_file and the purpose of idempotency_key. The phrase 'by page count' loosely reinforces pages_per_file but does not add meaningful semantics beyond the schema.

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

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

The description states a specific verb-resource pair ('Split ... PDF') and the splitting criterion ('by page count'), making the operation unambiguous. It distinguishes itself from siblings like merge_pdfs and images_to_pdf without requiring 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?

The description implies the use case—splitting a single PDF into chunks of a given page count—but never explicitly says when to choose this over alternatives like merge_pdfs or convert tools. There is no when-not-to-use guidance, so it earns only implied-usage credit.

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