One key for the document-to-web pipeline: scrape, AI-extract, build & edit PDFs, fill forms.
Scored across 29 tools
Most tools have a distinct source/output combination, so an agent can usually tell them apart (e.g. read_url vs scrape_page vs crawl_site differ by output and scope). A few pairs, such as docx_to_text vs file_to_markdown and select_pages vs split_pdf, have overlapping boundaries, but the detailed descriptions largely resolve the ambiguity.
All names are snake_case and readable, and many follow verb_object (crawl_site, merge_pdfs, rotate_pdf) or source_to_target (docx_to_pdf, url_to_screenshot) patterns. However, the two naming families are mixed inconsistently, and outliers like pdf_info, batch_scrape, and render_html_to_pdf break the dominant conventions.
At 29 tools, this set is over the recommended ceiling and will noticeably increase an agent's tool-selection burden. The domain is broad, but several tools are close variants of each other (read_url, batch_scrape, crawl_site, scrape_page), and the server could be trimmed without losing core capability.
The PDF lifecycle is well covered: creation, text extraction, form reading/filling, metadata, page operations, merging, splitting, and watermarking. Web fetching, document conversion, and AI extraction/summarization also cover the main workflows; notable gaps like OCR, PDF compression/encryption, and Office document editing are outside the apparent core purpose.
Answer a question grounded ONLY in a source document — a web page, PDF, Office file, or raw text. Provide 'question' plus ONE source: 'url', 'pdf', 'file' (base64), or 'text'. Says so when the answer isn't in the document.
| Name | Required | Description | Default |
|---|---|---|---|
| No | A file_id from a prior tool, or a base64-encoded PDF. | ||
| url | No | A public http/https URL to read. | |
| file | No | A base64-encoded .docx, .xlsx or .csv file. | |
| text | No | Raw text to answer from directly. | |
| question | Yes | The question to answer from the document. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and open-world. The description adds valuable behavioral context: answers are grounded only in the provided source, and the tool explicitly reports when the answer is absent. No 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?
Two tight sentences with no filler. The purpose is front-loaded, followed by the input rule and the key behavioral caveat. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all essential information an agent needs: what it does, accepted source types, the one-source requirement, and the behavior when the answer is missing. Output format is not described, but no output schema exists and the return is self-evident from 'Answer a question'.
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 each parameter is already documented. The description adds the critical 'ONE source' exclusivity constraint, which is not encoded in the schema, and clarifies that pdf can be an id or base64.
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: 'Answer a question grounded ONLY in a source document' with enumerated source types. The 'grounded ONLY' phrasing differentiates it from extraction, summarization, and scraping siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear usage pattern: provide 'question' plus exactly ONE source selected from url, pdf, file, or text. It also states the tool will say when the answer isn't in the document. It does not name sibling alternatives explicitly, but the input contract is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch up to 10 public URLs and return each as clean Markdown, in one call — for research/RAG over several pages at once. Private/internal hosts are blocked.
| Name | Required | Description | Default |
|---|---|---|---|
| urls | Yes | 1–10 http/https URLs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it only accepts public URLs and returns clean Markdown, which aligns with the readOnlyHint annotation. It also explicitly states that private/internal hosts are blocked, providing behavioral constraints beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences to convey the core functionality, use case, and a key limitation. No redundant or extraneous information is present, making it efficient and 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?
While there is no output schema, the description clearly states the return format (clean Markdown). It also notes the URL limit (up to 10) and the restriction on private/internal hosts. It lacks details on error handling or response structure, but for a tool with a single input array, this is largely sufficient.
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 single parameter 'urls' is described as 'public URLs' and the schema already specifies 'http/https URLs' with a minimum and maximum. The description adds clarity by reinforcing the 'public' aspect and the output format (clean Markdown), but does not introduce additional parameter details 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?
Clearly states it fetches up to 10 public URLs and returns clean Markdown in one call, explicitly distinguishing itself from single-page tools like scrape_page and read_url. The mention of 'research/RAG over several pages at once' further clarifies its intended use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides implicit guidance by noting it handles multiple pages at once and blocks private/internal hosts, but does not explicitly compare with sibling tools like scrape_page or read_url. The context of 'several pages' implies when to choose this over single-URL tools, though a more explicit recommendation would strengthen this dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a URL plus up to 7 more same-origin pages it links to (≤8 total), each as clean Markdown. Bounded and synchronous. Private/internal hosts are blocked.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The root http/https URL. | |
| limit | No | Max pages incl. root (default 5, max 8). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and openWorldHint already present, the description adds useful non-obvious behaviors: same-origin crawling, an 8-page bound, clean Markdown output, and blocking of private/internal hosts. It does not cover every edge case but is transparent about core 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 two sentences and conveys all essential information without redundancy, filler, or unnecessary detail. It is well structured and 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?
Despite lacking an output schema, the description clarifies the return format as clean Markdown and the bounded nature of the crawl. It does not specify failure behavior, but the given constraints and annotations provide sufficient operational context.
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 descriptions cover both parameters with 100% coverage. The tool description reinforces the limit semantics by explaining the 8-page total and same-origin scope, adding value beyond the schema's brief text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific action ('Fetch a URL plus up to 7 more same-origin pages it links to'), the output format ('clean Markdown'), and key constraints ('bounded and synchronous', 'Private/internal hosts are blocked'). This distinguishes it from sibling tools like scrape_page or batch_scrape.
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 it by noting it is bounded, synchronous, and limited to same-origin pages, plus the private-host restriction. It does not explicitly name alternatives, but the behavioral constraints provide enough guidance for typical selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn rows of data into a downloadable XLSX (default) or CSV. 'rows' is an array of objects (keys → header row) or an array of arrays (first row is the header). Returns a file_id (for chaining) and a ~1h download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| rows | Yes | Array of objects (keys→columns) or array of arrays (first row = header). | |
| format | No | Output format (default xlsx). | |
| sheet_name | No | Worksheet name (default 'Sheet1'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the sparse annotations (readOnlyHint=false, destructiveHint=false), the description discloses useful behaviors: it creates a downloadable file, returns a file_id for chaining, and provides a ~1h download URL. This adds meaningful insight into output behavior and temporary link availability.
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 compact sentences deliver the primary purpose, input format explanation, and return behavior with no wasted words. The most important information is front-loaded in the first sentence.
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 no output schema, the description covers input structure, output formats, default format, and return values (file_id and download URL). The only missing pieces (sheet_name, required rows) are already provided by the schema, so nothing an agent needs is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents each parameter. The description adds minor clarifications such as object keys becoming the header row and arrays-of-arrays using the first row as header, but these largely mirror the schema text. Baseline 3 is appropriate because 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?
Description states a specific verb ('Turn rows of data into') and resource ('downloadable XLSX or CSV'), making the tool's function immediately clear. The purpose is also distinct from all sibling tools, which are PDF/document/URL operations, so an agent can differentiate without needing explicit comparison.
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 implies when to use the tool: when you have rows of data that need to become a spreadsheet file. No explicit when-not-to-use or alternatives are mentioned, but no sibling tool offers spreadsheet creation, so this is sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a .docx document (base64) to a PDF. Returns a file_id and a ~1h URL.
| Name | Required | Description | Default |
|---|---|---|---|
| docx | Yes | Base64-encoded .docx file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits beyond the annotations. It mentions the output (file_id and URL) but nothing about side effects, authentication requirements, rate limits, or whether the input file is consumed or deleted. The annotations are minimal and not contradicted, but no extra behavioral context is added.
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 front-loads the primary action and immediately states the output. No unnecessary words or filler, making it easy for an agent 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?
Given the simplicity of the tool, the description provides the essential output information (file_id and a ~1h URL) and hints at the URL's temporary nature. It does not explain how to use the file_id or potential error cases, but for a basic conversion tool this is largely sufficient.
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 parameter schema already describes the 'docx' parameter as 'Base64-encoded .docx file,' and the description repeats the base64 detail without adding new meaning. Since schema coverage is 100%, the baseline score of 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?
The description clearly states the action (convert) and the resource (.docx to PDF), which effectively distinguishes it from sibling tools like docx_to_text and images_to_pdf. The one-sentence definition leaves no ambiguity about the tool's function.
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 guidance on when to use this tool instead of alternatives such as markdown_to_pdf or url_to_pdf. There is no mention of use cases, prerequisites, or conditions that would favor this conversion method.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract the text of a .docx document (base64). Returns the text inline.
| Name | Required | Description | Default |
|---|---|---|---|
| docx | Yes | Base64-encoded .docx file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already covers the read-only nature, and the description adds the behavior of returning text inline. This is sufficient for a simple tool, though it doesn't describe potential edge cases or error handling.
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, concise sentence with no redundant words. It front-loads the core action and resource, 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?
The description fully explains the tool's purpose, input format, and output format. Given the simplicity of the operation, it provides all necessary context without needing an output schema or additional 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?
The parameter 'docx' is fully described in the schema as 'Base64-encoded .docx file.' The description repeats this information without adding extra meaning, so it meets the baseline but does not exceed the schema 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 clearly states the specific action (extract text), the resource (.docx document), and the output (text inline). This distinguishes it from sibling tools like docx_to_pdf or extract_pdf_text, making its purpose unambiguous.
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 its usage by specifying it handles .docx files, which is clear in the context of sibling tools. However, it does not explicitly exclude alternatives or provide when-not-to-use guidance, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract specified fields from a web page, PDF, or Office file as JSON, using AI. Provide 'fields' plus ONE source: a 'url', a 'pdf' (file_id or base64), or a 'file' (base64 .docx/.xlsx/.csv). Returns a JSON object mapping each field to its value, or null when absent.
| Name | Required | Description | Default |
|---|---|---|---|
| No | A file_id from a prior tool result, or a base64-encoded PDF. | ||
| url | No | A public http/https URL to read. | |
| file | No | A base64-encoded .docx, .xlsx or .csv file (converted to text first). | |
| fields | Yes | Field names to extract, e.g. ['invoice total','due date']. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns a JSON object mapping each requested field to its value, with null for absent fields. This adds useful behavioral detail beyond the readOnlyHint and openWorldHint annotations, though it does not mention potential model limitations, latency, or cost.
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 brief, well-organized, and free of redundant detail. It conveys the core behavior, required inputs, and output format in two clear sentences.
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 and lack of an output schema, the description provides enough context for an agent to call the tool correctly: which sources are supported, how to specify fields, and what the response will look like. Error cases like multiple sources are not mentioned, but the 'ONE source' instruction mitigates that 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?
The schema already covers 100% of parameters, and the description reinforces the meanings by specifying that 'pdf' can be a file_id or base64, 'file' is base64 for Office formats, and 'fields' are the names to extract. It adds valuable one-of guidance not fully captured by the schema's structure.
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 a specific action: extract specified fields from a web page, PDF, or Office file and return them as JSON. It distinguishes this tool from sibling tools focused on scraping, conversion, or full-text extraction by emphasizing custom field-level extraction using AI.
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 explains that users must provide 'fields' plus exactly one source, and it enumerates valid source types. It does not explicitly name alternative tools or state when not to use this tool, but the 'using AI' and custom-field wording makes the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract the text content of a PDF — for RAG, summarization, or search. Accepts a file_id (from a prior tool) or a base64-encoded PDF, and returns the text inline. Not OCR: a scanned/image-only PDF returns little or no text.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | A file_id from a prior tool result, or a base64-encoded PDF. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=false, which the description does not contradict — text extraction is consistent with read-only. Beyond the annotations, the description adds genuinely useful behavior: it discloses the OCR limitation (scanned/image-only PDFs return little or no text) and that results are returned inline. This enriches the safety and outcome expectations beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero filler: purpose and use cases lead, input format follows, and the OCR caveat closes. Every sentence earns its place, and the most decision-relevant information (purpose, not-OCR warning) is front-loaded before implementation details.
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 single-parameter extraction tool whose annotations already carry the read-only safety profile, the description covers input (file_id or base64), output (inline text), and the key failure mode (scanned PDFs). Minor gaps like response size limits and encoding specifics are absent, but 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 100%, so the schema already documents the single 'pdf' parameter (file_id or base64). The description restates the input options and adds the return-format detail (text inline), but that concerns output rather than parameter meaning. Per the rubric, high schema coverage warrants a baseline of 3, and the marginal added value is modest.
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 ('Extract the text content of a PDF') plus concrete use cases (RAG, summarization, search). It also distinguishes itself from siblings by declaring it returns text inline and is not OCR, which separates it from read_pdf_form (form fields), extract_data (structured data), and docx_to_text (different format) 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 gives clear context for use (RAG, summarization, search) and states the accepted inputs (file_id from a prior tool or base64). The 'Not OCR' caveat is an implicit when-not-to-use signal for scanned PDFs, but it never names a specific alternative tool, so the routing guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a Word (.docx), Excel (.xlsx) or CSV file (base64) into clean Markdown — for RAG, agents and pipelines. DOCX keeps headings/lists/tables; spreadsheets become Markdown tables (one per sheet). Returns Markdown inline. Optional 'format' (docx|xlsx|csv) overrides auto-detection.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Base64-encoded .docx, .xlsx or .csv file. | |
| format | No | Optional format hint; auto-detected if omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it returns Markdown inline, how different input types are handled (DOCX keeps structure, spreadsheets become tables), and that format overrides auto-detection. This goes beyond the readOnlyHint annotation by providing concrete output behavior, though it does not mention potential errors or limitations.
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 compact and well-structured: a single opening sentence states purpose and use case, followed by a concise second sentence detailing output behavior and the optional override. No unnecessary words or 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?
For a simple 2-parameter tool with no output schema, the description covers the core functionality, input format, output format, and the special behavior of the optional parameter. It does not mention edge cases or limitations, but these are not critical for basic usage, so it is reasonably complete.
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 descriptions cover all parameters (100% coverage), so baseline is 3. The description adds value by explaining that 'file' is base64-encoded and that 'format' overrides auto-detection, which is not fully explicit in the schema's enum description alone.
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 'Convert' and the resource 'Word/Excel/CSV file' to 'clean Markdown'. It distinguishes itself from sibling tools like docx_to_text and docx_to_pdf by specifying the Markdown output and noting the preservation of headings/lists/tables for DOCX and table conversion for spreadsheets.
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 context for use ('for RAG, agents and pipelines') and explains the optional 'format' parameter as an override for auto-detection. However, it does not explicitly compare with alternative tools (e.g., docx_to_text) or state when not to use it, so it falls short of explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fill a PDF's form fields from a map of field -> value; optionally flatten. Returns a file_id and a ~1h URL.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | A file_id from a prior tool result, or a base64-encoded PDF. | ||
| fields | Yes | Map of field name to value. | |
| flatten | No | Flatten the form after filling (default false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the return value but omits important behavioral details such as whether the original PDF is modified or a new file is created, how missing or invalid fields are handled, and what 'flatten' actually does. Annotations indicate non-destructive, but this is not conveyed in the description.
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?
One sentence with no filler. Conveys the core action, input, optional flag, and output efficiently.
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?
Within the context of many PDF tools, it distinguishes from reading but not from merging or other modifications. No output schema, so response structure is unclear. Does not mention error behavior or edge cases, making it only partially complete for an agent.
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 fully documents all three parameters. Description adds 'field -> value' for fields and 'optionally flatten' for the boolean, but does not define flatten's effect or the expected value types in the map, leaving some ambiguity.
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?
Clearly states the action (fill form fields), the input mapping (map of field -> value), optional flattening, and the return value (file_id and ~1h URL). Distinct from sibling tools like read_pdf_form which reads forms.
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?
Lacks explicit guidance on when to use this tool versus reading or editing PDFs, though the function name and description make the primary use case obvious. No mention of when to prefer read_pdf_form or other PDF tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Combine PNG/JPEG images (base64) into a PDF, one image per page. Returns a file_id and a ~1h URL.
| Name | Required | Description | Default |
|---|---|---|---|
| images | Yes | Base64-encoded PNG/JPEG images, one per page (max 20). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions the return value (file_id and ~1h URL) but does not disclose whether input images or the generated PDF are stored, how long the file persists, or any side effects beyond creating a PDF. The annotations are not contradicted.
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, consisting of two short sentences that directly convey the action and the return value. No unnecessary words or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and single parameter, the description is largely complete: it explains the input, output, and page arrangement. It could mention whether the file_id can be used with other tools, but that is not essential for invoking this 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 schema description for the single parameter is detailed: it specifies base64-encoded PNG/JPEG images, one per page, with a max of 20. This gives an agent clear guidance on the accepted input format and limits.
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 combines PNG/JPEG images into a PDF with one image per page, which is a specific verb and resource. It also distinguishes itself from sibling PDF tools by focusing on image input.
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 use case is implied by the description, but it does not explicitly state when to choose this tool over alternatives like markdown_to_pdf or url_to_pdf, nor does it mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover the same-origin URLs linked from a page — the site map, with no page content fetched. Private/internal hosts are blocked.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The http/https URL to map. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint annotation by stating that page content is not fetched and that private/internal hosts are blocked. This gives useful behavioral expectations without needing to inspect implementation details.
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, well-structured sentence that efficiently communicates purpose, scope, and a key constraint. There is no redundant or extraneous text.
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 one-parameter tool with no output schema, the description covers the main contextual points: what it does, what it does not fetch, and blocking behavior. It is complete enough for an agent to decide and call the tool, though an explicit note about the return format would be a minor enhancement.
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 already provides a clear description for the url parameter ('The http/https URL to map') with 100% coverage, so the baseline applies. The tool-level description adds the same-origin context but does not significantly expand parameter semantics 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?
The description clearly states the tool discovers same-origin URLs linked from a page and calls it a site map. It also explicitly notes no page content is fetched and private/internal hosts are blocked, which distinguishes it from content-scraping tools like scrape_page or read_url.
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 that this tool is for link discovery and not for page content retrieval, and the blocking note helps set expectations about when results may be limited. It does not explicitly name alternative tools, but the context is strong enough to guide selection among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render Markdown to a clean, print-styled PDF. Returns a file_id and a ~1h URL.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Document title. | |
| markdown | Yes | The Markdown to render. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide minimal safety info (not read-only, not destructive). Description adds return format (file_id and ~1h URL) and styling hint, disclosing output behavior beyond annotations. No contradiction.
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 concise sentences, front-loaded with the action, then output. No waste.
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 properly specifies the return format and URL expiry. It's adequate for a simple conversion tool, though it could mention what 'print-styled' implies or any limitations.
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 both parameters with descriptions, so description adds no additional meaning. Baseline 3 is appropriate given 100% schema 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?
States a clear verb (render) and resource (Markdown to PDF), with a distinguishing qualifier ('clean, print-styled'). Clearly distinguishes from sibling render tools like docx_to_pdf and render_html_to_pdf.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to choose this over sibling tools. Doesn't mention scenarios or exclusions, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Combine 2+ PDFs into a single PDF, in the order given. Inputs are file_ids (from prior tools) or base64 PDFs. Returns a file_id (for chaining) and a ~1h download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| pdfs | Yes | 2+ PDF sources. Each: A file_id from a prior tool result, or a base64-encoded PDF. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly=false, destructive=false), the description transparently explains the mutation (combining PDFs), the return type (file_id), and the time-limited download URL ('~1h download URL'). This goes beyond the minimal annotation coverage and gives the agent a clear model of the tool's 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 two concise sentences. The first states the core function, and the second clarifies inputs and outputs. There is no redundant or extraneous information, 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?
Given the single parameter and lack of output schema, the description covers all necessary information: inputs, output format, ordering, and the chaining capability. It is complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'pdfs' is fully described in both the schema and the description: it must contain 2+ items, each being a file_id or base64 PDF. The description and schema are consistent, leaving no ambiguity about what values are accepted.
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's action: 'Combine 2+ PDFs into a single PDF, in the order given.' It also specifies input types (file_ids or base64 PDFs) and output format (file_id and download URL), leaving no ambiguity about the tool's purpose.
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 usage context by specifying that inputs can be 'file_ids (from prior tools) or base64 PDFs' and that the output file_id is 'for chaining'. It does not explicitly contrast with sibling PDF tools (e.g., split, rotate), but the merge purpose is so distinct that an agent can reliably select it without further guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stamp a page number on every page. position: bottom-center (default) | bottom-left | bottom-right | top-center | top-left | top-right. format supports {n} and {total}. Returns a file_id + ~1h URL.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | A file_id from a prior tool result, or a base64-encoded PDF. | ||
| start | No | First page's number (default 1). | |
| format | No | e.g. '{n}' or '{n} / {total}' (default '{n}'). | |
| position | No | Where to place it (default bottom-center). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is not read-only and not destructive, which matches the described mutation. The description adds useful context: it returns a file_id and a ~1h URL, implying a new file is produced and that the link expires. This goes beyond the schema and annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, and every clause adds relevant detail. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description states the return type (file_id + URL) and its lifetime. For a simple stamping tool, the essentials are covered: input format, parameters, and output. Minor omissions like error handling are not critical for this use case.
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%, but the description adds value by enumerating the allowed position values and explicitly stating that format supports {n} and {total}. This is more than the schema's generic examples, so it compensates well beyond the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Stamp a page number') and resource ('every page'), and provides concrete configuration details (position and format tokens). It clearly distinguishes itself from a generic PDF manipulation tool and is not a tautology.
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 it clear this is for adding page numbers to PDFs, with position and format options. It does not explicitly name alternative tools or exclusion cases, but the context is unambiguous enough that an agent would know when to select this over siblings like watermark_pdf.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a PDF's metadata (title, author, subject, keywords, creator, producer, dates) plus page count and page size, as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | A file_id from a prior tool result, or a base64-encoded PDF. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, confirming this is a safe read operation. The description adds useful context by enumerating exactly which metadata fields are returned and noting the JSON output format, providing specificity beyond the annotation without contradicting it.
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 with no filler. The main action and output are front-loaded, and every phrase earns its place by defining scope and return format.
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, read-only, one-parameter tool, the description is complete: it states input requirements through the schema, the operation itself, the specific output fields, and the return format. No output schema exists, but the description compensates by naming what is returned. No critical information 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 schema provides 100% coverage for the single 'pdf' parameter, describing it as a file_id or base64-encoded PDF. The description adds no additional parameter-level detail, so the baseline 3 applies: 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?
The description states a specific action ('Read') and a specific resource ('a PDF's metadata (title, author, subject, keywords, creator, producer, dates) plus page count and page size'), and specifies the return format ('as JSON'). This clearly distinguishes pdf_info from text extraction, form reading, and metadata-writing siblings.
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 tool is for retrieving metadata and page-level information, which provides clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a PDF's form fields (name, type, value, options) as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | A file_id from a prior tool result, or a base64-encoded PDF. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the read-only nature is already disclosed. The description adds that the output is JSON and lists specific fields (name, type, value, options), which is useful context. However, it does not mention what happens when the PDF has no form fields or when the input is invalid, though this is acceptable given the read-only annotation and simplicity.
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 sentence that is clear and front-loaded with the action and target. It has no redundant words or filler, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description and schema cover the necessary information. The only minor gap is the absence of error behavior or edge cases, but for this complexity level, it is complete enough.
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 a full description of the pdf parameter, including accepted formats (file_id or base64-encoded PDF). The tool description does not add any additional parameter guidance, but since schema description coverage is 100%, the baseline of 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?
The description clearly states the tool lists a PDF's form fields, naming the fields (name, type, value, options) and output format as JSON. This distinguishes it from sibling tools like extract_pdf_text (which extracts text) and fill_pdf_form (which writes fields), making the purpose unambiguous.
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 guidance on when to use this tool versus alternatives. It does not mention when to prefer this over extract_pdf_text or fill_pdf_form, nor does it specify any exclusions or context. There is no information about use cases or prerequisites, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a public http/https URL and return its main content as clean Markdown — ideal for giving an agent readable web content for research or RAG. Private/internal hosts are blocked.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The http/https URL to read. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral constraint — 'Private/internal hosts are blocked' — which the agent needs to predict failures. It stops there, though: no disclosure of timeouts, redirect handling, JS-heavy page behavior, or content-size limits, which are relevant for an open-world fetch tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler. The purpose is front-loaded in the first sentence and the blocking constraint follows in the second. Efficient and well-ordered, though the use-case phrase could arguably be trimmed without loss.
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?
Adequate for a single-parameter, low-complexity fetch tool: schema covers the URL, annotations cover safety, and the description covers purpose plus the private-host constraint. What's missing is sibling differentiation (scrape_page does an overlapping job) and edge-case behavior for dynamic or large pages, which a research/RAG use case is likely to encounter. No output schema exists, so return-format nuance could also be spelled out more.
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 url parameter is already documented as 'The http/https URL to read.' The description adds marginal value by clarifying only public URLs work and that private/internal hosts are rejected, which supplements the schema slightly. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds only minor extra 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?
States a specific verb (fetch), resource (public http/https URL), and output format (clean Markdown). The 'main content' phrasing signals extraction/deduplication, which distinguishes it from raw-fetch tools. However, it does not explicitly name its nearest sibling scrape_page, so an agent must infer the differentiation rather than being told.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear use case ('ideal for giving an agent readable web content for research or RAG'), which implies when to use it. But it never says when not to use it or names alternatives such as scrape_page for structured extraction or url_to_pdf for PDF output — the sibling set contains several web-fetching tools with no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a structured document to a PDF from a named template (invoice, receipt, report). Money/totals are computed for you. Returns a file_id (for chaining) and a ~1h download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Template data. invoice/receipt: {seller:{name,address?,email?,logo_url?(data: URI)}, buyer?:{name,address?,email?}, number?, issued?/date?, due?, currency?, items:[{description,qty,unit_price}], tax_rate?, notes?, terms?}; receipt also takes amount_paid?, payment_method?. report: {title, subtitle?, author?, date?, sections:[{heading?,body?}]}. Money is computed server-side. | |
| template | Yes | Document template. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions that it returns a file_id and a ~1h download URL, which helps set expectations. However, with readOnlyHint false and destructiveHint false, it does not disclose whether file creation has persistent storage or cleanup side effects beyond the temporary URL.
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 and well-structured, using two sentences with parenthetical examples for templates. It front-loads the core action and includes the key return information without unnecessary detail.
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 provides the essential return behavior (file_id and download URL) and notes chaining capability. Since there is no output schema, this is sufficient for basic usage, though error cases or validation requirements are not mentioned.
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%: both template and data are described in the schema, including the enum values and nested data structure. The tool description adds little beyond the schema, though it reinforces that totals are computed automatically.
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 that the tool renders a structured document to a PDF from a named template, naming invoice, receipt, and report. This specific behavior distinguishes it from sibling tools like markdown_to_pdf or render_html_to_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 use case is clear from 'named template' and 'Money/totals are computed for you', implying it is for templated documents with automatic totals. It does not explicitly name alternatives or exclusions, but the context makes the intended use understandable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a full HTML document to a PDF. External subresources are blocked for safety — inline images/fonts as data: URIs. Returns a file_id (for chaining) and a ~1h download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| html | Yes | The complete HTML document to render. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description proactively discloses that external subresources are blocked for safety and explains how to include inline resources. It also mentions the output returns a file_id and download URL. However, it does not explicitly discuss side effects or file persistence, and annotations do not provide clear read-only or destructive hints.
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 and information-dense, with no fluff. Both sentences serve a purpose: the first states the core function, and the second clarifies resource constraints and output expectations.
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 simple input and lack of an output schema, the description sufficiently explains what the caller can expect: a rendered PDF, a file_id for chaining, and a time-limited download URL. No critical context appears 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 schema covers the single 'html' parameter, and the description adds practical guidance by explaining that external subresources are blocked and that images/fonts should be inlined as data URIs. This goes beyond the schema's basic parameter 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 tool's action and resource: 'Render a full HTML document to a PDF.' It also distinguishes itself from sibling tools by emphasizing full HTML input and the external subresource restriction, which differentiates it from url_to_pdf and markdown_to_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 description provides important constraints (external subresources blocked, data URIs for inline resources) but does not explicitly state when to prefer this tool over alternatives such as url_to_pdf, markdown_to_pdf, or images_to_pdf. 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.
Rotate every page of a PDF by 90, 180, or 270 degrees (clockwise). Returns a file_id (for chaining) and a ~1h download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | A file_id from a prior tool result, or a base64-encoded PDF. | ||
| degrees | Yes | 90, 180, or 270. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only operation (readOnlyHint=false). The description adds useful behavioral detail: it returns a file_id for chaining and a ~1h download URL, which hints at the output being a new file with a time-limited link. It does not contradict the annotations and adds context about the result format.
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, compact sentence that front-loads the core action and includes the essential return information. No redundant words or filler; every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rotation tool with full schema coverage and no output schema, the description covers the core behavior and return values (file_id and URL). It does not mention potential edge cases like file size limits or whether the original is modified, but these are minor for the operation's simplicity. Overall, it is sufficient for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already described in the schema. The description does not add any extra semantic detail beyond what the schema provides (e.g., it repeats the degrees values but does not explain the pdf parameter further). Baseline 3 is appropriate given full schema 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 clear verb ('Rotate'), the specific resource ('every page of a PDF'), and the exact degrees (90, 180, 270 clockwise). It is immediately obvious what the tool does and it is distinct from sibling PDF operations like merge or split.
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 implies the tool is used when rotation is needed, but it does not explicitly state when to prefer this over alternatives, nor does it mention any exclusions or prerequisites. No explicit routing to other tools is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a public http/https URL and return its rendered HTML, the links on the page, and page metadata (title/description/OpenGraph/canonical/favicon) — in one render. For clean Markdown use read_url instead. Private/internal hosts are blocked.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The http/https URL to scrape. | |
| formats | No | Which representations to return (default: all three). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds valuable context by stating that private/internal hosts are blocked, and clarifies the return includes rendered HTML, links, and metadata in one render. This goes beyond the structured data without contradicting it.
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 exactly two sentences. The first sentence front-loads the core function and outputs; the second provides an alternative and a constraint. Every word earns its place, with no fluff or repetition. It is highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description is fairly complete. It specifies the input (public URL), the outputs (HTML, links, metadata), the exclusion (private hosts), and the alternative (read_url for Markdown). It does not mention rate limits or response format details, but given the simplicity and the annotation coverage, the description covers the essential information an agent needs to decide and 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 both 'url' and 'formats' are already documented in the schema, including the default of returning all three formats. The description's mention of 'rendered HTML, links, and metadata' mirrors the schema's enum values without adding new meaning. It does not introduce any format-specific nuances beyond what the schema provides, so the 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?
The description clearly states the tool fetches a public http/https URL and returns rendered HTML, links, and page metadata in one render. It names the exact resource and verb, and explicitly distinguishes itself from read_url for Markdown, making its purpose unambiguous even among similar sibling 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 provides an explicit alternative: 'For clean Markdown use read_url instead.' This gives clear when-not-to-use guidance. It also states 'Private/internal hosts are blocked,' which informs constraints. It doesn't cover all sibling tools (e.g., url_to_pdf, url_to_screenshot), but the main use case and a key exclusion are addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keep only the specified pages of a PDF (e.g. [1,3,5]) and drop the rest, preserving order. Returns a file_id (for chaining) and a ~1h download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | A file_id from a prior tool result, or a base64-encoded PDF. | ||
| pages | Yes | Pages to keep, e.g. '1,3,5-7'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description does not need to restate that. It adds meaningful context beyond the annotations: it specifies that the operation preserves order, that it returns a file_id for chaining, and that the download URL expires in ~1 hour. These details help the agent anticipate side effects and output format, which is valuable for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is dense but free of filler. It front-loads the core action, then states the output and the expiry time. Every word earns its place, and it is immediately scannable by an agent.
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 tool is simple with only two parameters and no output schema. The description explains what it does, the order preservation, and the return format (file_id and download URL). It does not mention edge cases like invalid page numbers or the behavior when pages are out of range, but for a basic selection tool this is not critical. Given the low complexity and high schema coverage, the description is sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both 'pdf' and 'pages' have descriptions in the input schema). The description adds no new semantic information about the parameters; it repeats the example '1,3,5' which is already in the schema. Since the schema fully documents the parameters, the description contributes little beyond what is already structured. 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?
The description states a specific verb ('Keep only the specified pages') and resource ('a PDF'), with an explicit example ('[1,3,5]') and the effect ('drop the rest, preserving order'). It clearly differentiates the tool's function from siblings like split_pdf or merge_pdfs by specifying that it outputs a single PDF with selected pages rather than splitting or merging.
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 usage: use this when you need to extract a subset of pages from a PDF while preserving order. However, it does not explicitly mention when NOT to use it or name any alternative tools (e.g., 'for splitting into multiple PDFs, use split_pdf'). It provides no exclusionary guidance, so the agent must infer usage from the action described.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a PDF's title, author, subject, keywords (array or comma string) and/or creator. Only the fields you provide change. Returns a file_id + ~1h URL.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | A file_id from a prior tool result, or a base64-encoded PDF. | ||
| title | No | ||
| author | No | ||
| creator | No | ||
| subject | No | ||
| keywords | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the operation and return value (file_id + URL), implying a new PDF is created, but it does not explicitly mention whether the original is preserved or if any side effects occur. However, the annotations (readOnlyHint=false, destructiveHint=false) align with a non-destructive write, so no contradiction exists.
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, concise sentence that conveys the essential information without redundancy. It is well-structured and 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?
The description fully explains the tool's function and return value, which is sufficient for an agent to call it correctly. It does not provide an output schema, but for a simple metadata setter, the return format is adequately described.
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 description mentions all parameters (title, author, subject, keywords, creator) and specifically clarifies that keywords can be an array or comma string, matching the schema. The only param with a schema description (pdf) is also well-defined. This compensates for low schema 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 clearly states the action (set), the target resource (PDF), and the specific fields (title, author, subject, keywords, creator). It also clarifies the behavior that only provided fields are changed, leaving no ambiguity about the tool's purpose.
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 a direct usage hint by specifying that only supplied fields change, guiding the agent on partial updates. It does not mention alternative tools or contextual triggers, but the action is straightforward enough that an agent can infer when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Split a PDF into multiple PDFs — one per page by default, or by page ranges like '1-3;4-6'. Returns a file_id + URL per part.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | A file_id from a prior tool result, or a base64-encoded PDF. | ||
| ranges | No | e.g. '1-3;4-6'. Omit to split every page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only and not destructive. The description adds behavioral details beyond that: it clarifies the output format (returns a file_id + URL per part) and the default behavior (one per page). It does not discuss side effects on the original file or any auth/rate limits, but given the simple nature, this is sufficient.
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, information-dense sentence. It front-loads the core purpose, includes the default behavior, a range example, and the return format, with zero filler. It is well-structured and easily parseable.
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 tool, the description covers all essential aspects: the operation, the default behavior, the range syntax, and the output format. The schema covers parameters, and there is no output schema, but the description explicitly states what is returned. No critical information is missing for an agent 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%, and the description does not add substantial meaning beyond the schema. It reiterates the range format and the default behavior, which are already in the schema descriptions. Since the schema fully documents parameters, a baseline of 3 is appropriate; the description adds marginal value.
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 action 'split', the resource 'a PDF', the output 'multiple PDFs', and gives the default behavior plus an example of page ranges. It is clearly distinct from siblings like merge_pdfs and select_pages, which perform different 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 description implies usage context (splitting a PDF) and shows the range syntax, but it does not explicitly mention when to use this tool instead of alternatives, nor does it state any exclusions or prerequisites. The sibling set includes select_pages, which might overlap, but no differentiation is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize a web page, PDF, Office file (.docx/.xlsx/.csv), or raw text using AI. Provide ONE source: 'url', 'pdf' (file_id or base64), 'file' (base64), or 'text'. Optional 'max_words'. Returns the summary.
| Name | Required | Description | Default |
|---|---|---|---|
| No | A file_id from a prior tool, or a base64-encoded PDF. | ||
| url | No | A public http/https URL to read. | |
| file | No | A base64-encoded .docx, .xlsx or .csv file. | |
| text | No | Raw text to summarize directly. | |
| max_words | No | Approximate target length in words. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's job is to add context beyond that. It adds that the operation uses AI and returns a summary, which is minimal but consistent. It does not disclose potential cost, latency, or failure modes, but the safety profile is covered by 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 two sentences long, front-loaded with the core action and source types, and avoids redundancy with the schema. It is efficient, though the second sentence could be integrated to save a line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must clarify what is returned; it says 'Returns the summary' but not the format or structure. It covers the input constraints well, but lacks details on output format, error handling, or edge cases. For a moderately complex tool with 5 optional parameters, this is adequate but not rich.
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 fully documented. The description adds the constraint that exactly one source must be provided, which is useful guidance beyond the schema. However, it does not clarify parameter formats (e.g., base64 encoding) beyond what the schema already 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?
The description states a clear verb ('Summarize') and specifies the resource types (web page, PDF, Office file, raw text), distinguishing it from sibling tools like extract_text or extract_pdf_text by focusing on summarization via AI. It is unambiguous and specific.
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 states that exactly one source must be provided and lists the four source parameter types. However, it does not name alternative tools or explicitly state when not to use it, though the purpose is distinct enough that an agent can infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a public http/https URL and render the live page to a PDF. Returns a file_id (chainable into the PDF tools) and a ~1h download URL. Private/internal hosts are blocked.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The http/https URL to snapshot. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description adds value beyond this by disclosing the private-host blocking behavior, the returned file_id being chainable into PDF tools, and the ~1h download URL expiry. This behavioral detail complements the annotations and does not contradict them — 'render' is consistent with the non-read-only flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler. The core action is front-loaded, followed by return-value info and then the access constraint. Every sentence earns its place with distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema present, the description correctly covers the return format (file_id, ~1h download URL). For a single-parameter tool with 100% schema coverage and annotations carrying the open-world/side-effect profile, the description is adequately complete. Minor omissions like rate limits or auth requirements are not material for this simple fetch-and-render 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 coverage is 100%, so the schema already documents the single url parameter; baseline is 3. The description adds slight value by specifying the URL must be public and http/https, which is a meaningful constraint on the input value, but it doesn't add format or syntax details beyond that.
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 ('Fetch a public http/https URL and render the live page to a PDF') and distinguishes the output (PDF) from siblings like url_to_screenshot. It names the chainable file_id output, which further separates it. It doesn't explicitly contrast with render_html_to_pdf, but the core purpose is unambiguous.
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 usage context by stating 'public http/https URL' and 'Private/internal hosts are blocked', which tells an agent when the tool will reject a call. However, it never names alternatives (e.g., read_url, scrape_page, url_to_screenshot, render_html_to_pdf) or gives when-to-use vs when-not-to-use guidance against the 21 siblings. Usage context is implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a public http/https URL and capture a PNG screenshot. Set full_page for the entire scroll height. Returns a file_id and a ~1h download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The http/https URL to capture. | |
| full_page | No | Capture the full scroll height (default: viewport). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavior beyond annotations: it notes the URL must be public, the full_page behavior, and the return of a file_id and a ~1h download URL. While annotations provide openWorldHint and non-destructive hints, the description enriches with operational details without contradiction.
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 with zero redundancy. The primary action is front-loaded, and the optional parameter and return format are clearly mentioned. Every word contributes to understanding, making it highly efficient.
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 two parameters and no output schema, the description covers the core behavior, the optional full_page parameter, and the return payload (file_id and download URL). It does not address error handling or edge cases, but for the tool's simplicity, the information is sufficient.
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 descriptions for both parameters. The description echoes the schema's parameter descriptions (e.g., 'Set full_page for the entire scroll height') without adding new semantic meaning. It does not go beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Fetch a public http/https URL and capture a PNG screenshot.' This specifies the verb (capture), the resource (URL), and the output format (PNG), distinguishing it from siblings like url_to_pdf (PDF) and read_url (text content).
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 explicit guidance on when to use this tool versus alternatives. The description does not mention sibling tools or conditions for selection. It only states the action and the full_page option, leaving the agent to infer when a screenshot is preferred over PDF or text extraction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stamp a diagonal grey text watermark (e.g. "DRAFT", "CONFIDENTIAL") across every page of a PDF. Returns a file_id (for chaining) and a ~1h download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | A file_id from a prior tool result, or a base64-encoded PDF. | ||
| text | Yes | The watermark text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description does not need to restate those. It adds useful behavioral context: that the watermark is diagonal grey, that it returns a file_id for chaining, and that the download URL expires in ~1h. This goes beyond the annotations and gives the agent practical information about the result and its lifecycle.
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 with no fluff. It front-loads the action and key examples, then states the output format. Every word adds value, making it efficient and easily 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?
For a simple two-parameter tool with no output schema, the description covers the essential aspects: what it does, the output, and the time-limited URL. It does not mention error conditions or file size limits, but these are not critical for a watermark operation. The description is sufficiently complete for an agent to call 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?
The input schema already fully describes both parameters (pdf as file_id or base64, text as watermark text) with 100% coverage. The description only adds examples of text (DRAFT, CONFIDENTIAL) which are illustrative but not necessary. It does not clarify any additional semantics beyond the schema, so it meets the baseline of 3.
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 'Stamp' with a clear resource 'PDF' and describes the action in detail ('diagonal grey text watermark across every page'). It also names the return value (file_id and download URL), which distinguishes it from any sibling tool. No other sibling performs watermarking, so it is clearly unique.
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 the purpose and output, implying when to use it (when you need to watermark a PDF). However, it does not explicitly mention alternatives or when not to use it, such as comparing to number_pdf or set_pdf_metadata. The context is clear enough for an agent to infer usage, but it lacks explicit exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
answer_from_documentdata_to_spreadsheetsummarize_documentbatch_scrapecrawl_siteextract_data1 field changedInput schema / properties / fileAdded value: +{
+ "description": "A base64-encoded .docx, .xlsx or .csv file (converted to text first).",
+ "type": "string"
+}map_sitefile_to_markdownnumber_pdfpdf_inforender_document2 fields changedInput schema / properties / data / descriptionPrevious value: -"Template data. invoice: {seller:{name,address?,email?,logo_url?(data: URI)}, buyer?:{name,address?,email?}, number?, issued?, due?, currency?, items:[{description,qty,unit_price}], tax_rate?, notes?, terms?}. Money is computed server-side."New value: +"Template data. invoice/receipt: {seller:{name,address?,email?,logo_url?(data: URI)}, buyer?:{name,address?,email?}, number?, issued?/date?, due?, currency?, items:[{description,qty,unit_price}], tax_rate?, notes?, terms?}; receipt also takes amount_paid?, payment_method?. report: {title, subtitle?, author?, date?, sections:[{heading?,body?}]}. Money is computed server-side."Input schema / properties / template / enumPrevious value: -[
- "invoice"
-]New value: +[
+ "invoice",
+ "receipt",
+ "report"
+]set_pdf_metadatarender_documentdocx_to_pdfdocx_to_textextract_dataextract_pdf_textfill_pdf_formimages_to_pdfmarkdown_to_pdfmerge_pdfsread_pdf_formread_urlrender_html_to_pdfrotate_pdfscrape_pageselect_pagessplit_pdfurl_to_pdfurl_to_screenshotwatermark_pdfTurn documents into structured data: parse, extract, classify, split, and fill PDF forms.
Turn any PDF into structured JSON via AI + OCR: invoices, bank statements, contracts.
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
Web extraction, OCR (Japanese-strong), invoice and company data for AI agents. x402, no API key.
Add one secure layer between your agents and this server.
