KDAN PDF

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

Beyond the annotations, the description discloses key behavioral details: it downloads each PDF from its signed URL, stores it, returns session_id/job_ids, and warns against inventing download_url/file_id. It also states the preconditions and the follow-up action, giving a clear operational model without contradicting 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 well-structured with clear sections and front-loaded purpose. It is verbose but each sentence adds value, especially the mandatory workflow. Minor redundancy exists in the opening two sentences (function statement and usage context), preventing a perfect score.

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

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

Given the tool's complexity and the presence of an output schema, the description is thorough. It covers host restrictions, the required pre-step (check_upload_status), how to handle already-uploaded files, and the post-condition (call compare_pdfs if needed). This is complete for an agent to invoke 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 the baseline is 3. The description adds extra semantics by instructing 'Never invent or guess a download_url or file_id' and emphasizing that only files confirmed absent from check_upload_status should be included. This provides practical meaning beyond the field descriptions.

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 with a specific verb and resource: 'Upload multiple PDF files from ChatGPT file attachments.' It distinguishes itself from upload_pdf and create_upload_page by noting host-specific compatibility, which clarifies its unique scope.

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?

Explicit usage guidance is provided: use it when the user supplies multiple file attachments in ChatGPT, and use create_upload_page on non-ChatGPT hosts. The MANDATORY WORKFLOW precisely instructs to call check_upload_status first, skip if all files are already uploaded, and reuse job_ids, with strict warnings against direct invocation.

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

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

The description discloses key behaviors beyond annotations: it creates a new job_id with parent_job_id linking to the source, and instructs to use the new job_id for viewing the result. While annotations declare non-read-only and non-destructive, the description adds valuable context about the job lifecycle. It does not mention potential side effects like whether the old password remains valid, but the provided behavioral details are substantive.

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 (three sentences) and well-structured: the first sentence states the purpose, the second explains the job_id behavior and follow-up action, and the third gives an explicit exclusion. Every sentence earns its place without redundancy.

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

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

With 5 required parameters, an output schema, and a sibling set_password, the description covers the essential workflow: it explains the new job_id creation, how to view the result, and when not to use the tool. It omits details like error handling or whether the operation requires the old user password, but the presence of the output schema and schema descriptions reduces the burden. Overall, it is nearly complete for its complexity.

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

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

The schema has 100% description coverage for all 5 required parameters, so the baseline is 3. The description does not add new parameter-level details beyond the schema, but it does clarify the operational sequence (e.g., old_password is the current user password) implicitly through context. No additional compensation is needed.

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: 'Change the password of an already-protected PDF file.' It specifies the target (PDF) and differentiates from sibling set_password by explicitly mentioning 'already-protected' and instructing to use set_password for unprotected PDFs.

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

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

Provides explicit usage guidance: tells the user to call view_pdf after completion to display the result, and explicitly warns not to use this tool on unprotected PDFs, directing to set_password instead. This is a clear when-to-use and when-not-to-use with an alternative named.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral context: it explains session_id generation when omitted, the exact meaning of 'already_uploaded' vs 'needs_upload', and that when pending_filenames is omitted those fields are meaningless and you must read 'jobs' instead. This goes well beyond the annotation safety 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 longer than average but structured and front-loaded with the core purpose. Some redundancy exists (e.g., 'You MUST call this tool before any upload' appears in both the opening and the instructions), but the detailed guidance is relevant and organized by return field, making it navigable.

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

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

Despite having an output schema, the description goes beyond it by explaining how to interpret the outputs in different call scenarios (with/without pending_filenames) and what actions to take on each result. It covers all necessary behavior for a tool that orchestrates uploads, so nothing is missing for correct use.

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 baseline is 3. The description adds value by clarifying the semantics of omitting pending_filenames (fields become empty and meaningless) and reinforcing that session_id must be stored, which is not in the schema. It doesn't over-explain the parameters but provides enough extra context to earn a 4.

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

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

The description states a specific verb and resource ('Check existing uploads and determine which files still need uploading') and clearly distinguishes it from siblings by positioning it as a prerequisite to upload_pdf and create_upload_page. It also names the exact result fields, leaving no ambiguity about what the tool does.

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

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

The description explicitly says when to call ('Call this BEFORE upload_pdf or create_upload_page', 'Also call it after the user uploads via the widget') and when not to ('needs_upload is empty → skip uploading entirely'). It also names the next tools to call (upload_pdf, batch_upload_pdf) and how to act on the result, providing strong usage guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral detail: it describes the interactive side-by-side widget, color coding for differences (red=deleted, yellow=replaced, green=inserted, blue=moved), and mandatory post-return instructions (report spot counts, don't list individual differences). This goes well beyond the annotations and provides the agent with a clear behavioral model.

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

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

The description is longer than average but every sentence serves a purpose: mandatory usage, prerequisite, widget explanation, and post-return steps. It is well-structured with clear sections (MANDATORY, Before calling, After returns). Slightly verbose, but justified given the tool's complexity and interaction requirements.

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

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

Given the tool's complexity (interactive widget, mandatory post-processing, prerequisite checks), the description is complete. It covers both preconditions (job_ids exist) and postconditions (report spot counts, follow cta_instruction), which is essential for correct invocation. The output schema exists, so return value details are not required in the description.

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% (all three parameters have clear descriptions), so the schema already documents the parameters. The description does not add parameter-specific semantics, but it does clarify the role of job_id_a as 'original' and job_id_b as 'modified' indirectly via the comparison context. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description clearly states the tool compares two PDFs side-by-side, with a specific verb ('Compare') and resource ('PDFs'), and explicitly distinguishes it from analysis-based comparison by mandating its use for all document comparison requests. The title and description align, and it prevents misuse by warning against text analysis alternatives.

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 explicit when-to-use guidance ('When the user asks to compare, diff, or find differences between two PDFs, you MUST call this tool') and excludes alternatives ('NEVER attempt to compare documents using text analysis'). It also includes a prerequisite step (confirm both job_ids exist via check_upload_status) and post-call behavior, making usage unmistakable.

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

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

Description states 'Each call creates a NEW job_id', implying non-idempotent behavior, but annotation declares idempotentHint=true. This is a direct contradiction, requiring score 1 per rubric.

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

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

Every sentence serves a purpose: core action, mandatory prerequisite, versioning behavior, and post-compression step. No wasted 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?

Comprehensive coverage: prerequisites, versioning, and follow-up actions. Output schema exists, so return values are not needed. Complete for this tool's complexity.

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

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

Schema coverage is 100%, baseline 3. Description adds usage context for job_id (use latest from check_upload_status), improving semantics beyond 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?

Clear verb and resource: 'Compress a PDF to reduce its file size and return a new versioned file.' Distinguishes from siblings by specifying compression and versioning behavior.

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?

Explicit prerequisite: mandatory call to check_upload_status before using this tool. Also states that each call creates a new job_id, guiding proper usage sequence.

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

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

Beyond annotations, the description details widget behavior: automatic upload handling, inline rendering, spinner management, and user notification protocol. 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?

Well-structured with front-loaded purpose and clear sections. Slightly verbose but every sentence earns its place. Could be slightly more concise.

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

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

The description covers the entire workflow: when to use, what it does, what not to do, and what to do next. Given the complexity and presence of output schema, it is fully complete for correct tool invocation.

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

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

The description adds practical context for the session_id parameter: 'Always pass the same session_id throughout the entire conversation to keep all files grouped together.' Schema coverage is 100% but description enhances understanding.

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 purpose: 'Display an interactive PDF upload widget directly in the chat.' It distinguishes from sibling tools like upload_pdf and view_pdf by explicitly instructing not to call them.

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?

Explicit usage guidance: 'Use this when the user wants to upload a local PDF file from their device.' Includes clear 'do NOT' instructions for sibling tools and post-usage steps like calling check_upload_status.

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

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

Despite annotations already indicating non-destructive behavior, the description goes far beyond by explaining the versioning mechanism (new job_id, parent_job_id), confirming the source file remains untouched, and even specifying policy on deletion of the last page. This is extremely reassuring and contradicts no 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 longer than average, but every sentence serves a purpose: purpose statement, mandatory pre-step, safety explanation, policy guidance, and follow-up. It is well-structured and front-loaded, though slightly verbose in the safety explanation sections. Still, it earns a 4 for being appropriately sized for the tool's complexity.

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 an output schema present, the description does not need to explain return values. It covers prerequisites, the versioning outcome, restrictions (at least one page must remain), and the follow-up action. Given the tool's high-risk appearance and multiple contextual nuances, this description is fully 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?

The input schema provides 100% coverage, including descriptions of job_id, session_id, and page_numbers with details like '1-based' and 'duplicates ignored.' The description adds no extra parameter semantics beyond reinforcing the use of the latest job_id, which is already in the schema. 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 opens with a precise verb+resource+outcome: 'Delete one or more pages from a PDF and return a new versioned file.' This clearly distinguishes it from sibling PDF tools like compress_pdf or redact_by_text_range, which serve different purposes.

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 explicit usage guidance: a mandatory pre-check with check_upload_status, a clear prohibition against skipping it, and a follow-up instruction to call view_pdf. It also names the alternative tool for status checking, making the workflow unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations by framing this as a recovery re-run, explaining the widget's call pattern, and contrasting it with compare_pdfs. It does not describe edge cases like missing comparisons, but the annotations and output schema reduce the burden.

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 tightly packed sentences: first states purpose, second scopes usage, third gives an alternative. No filler or redundant information. 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?

For a simple tool with one param, full annotations, and an output schema, the description fully explains what, when, and why. It names the only required input, the trigger scenario, and the preferred alternative, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with a single parameter (session_id) whose description is self-explanatory: 'Session ID whose latest comparison should be returned.' The description reinforces that only session_id is needed but does not add new semantic detail beyond the schema. 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 opens with a specific verb and resource: 'Re-run the most recent PDF comparison for a session.' It clearly distinguishes the tool from its sibling compare_pdfs by noting that this tool only needs session_id, and it is scoped to widget recovery.

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

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

Explicitly states when to use: 'For widget recovery only' and describes the triggering condition ('when the host did not hand it the comparison payload'). It also names an alternative and when to prefer it: 'Prefer compare_pdfs when both job_ids are known.'

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety profile is covered. Description adds value by specifying the concrete output (page count, text previews) and the text-only scope, which is useful behavioral context beyond 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 three sentences, front-loaded with the core purpose, followed by return details and a direct alternative. Every sentence earns its place with no fluff or repetition.

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

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

For a simple 2-parameter tool with strong annotations and an output schema, the description covers purpose, output, and alternative. It is complete for the tool's complexity, and no critical gaps are apparent.

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 clear descriptions for both job_id and session_id. The description does not add parameter-level details, but given the high schema coverage, baseline 3 is appropriate; it provides no extra parameter meaning beyond what schema already gives.

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

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

Description clearly states the tool reads text content of each page and returns page count plus previews. It explicitly distinguishes from get_pdf_page_images for visual content, so it is unambiguous and well-differentiated.

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 explicit when-to-use guidance ('when you need to read the text content of each page to decide which pages to delete') and an explicit alternative ('For visual content... use get_pdf_page_images instead'). This fully addresses usage context and exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds significant behavioral context: returns rendered JPEG screenshots, caps at 10 pages per call, requires pagination via 'has_more' and 'next_start_page', and mandates scanning all pages before answering. It also notes the pip install prerequisite, which is useful for runtime setup.

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 dense but front-loaded with the primary use case. It uses a clear structure: when to use, what it returns, limitations, and a mandatory workflow. Every sentence serves a purpose, and the critical pagination rule is highlighted with 'ALWAYS' and 'MUST.' No filler 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?

Given the complexity of paginated rendering, the description fully covers the required workflow, including the loop condition, how to read structuredContent, and the requirement to complete scanning before any action. The output schema is not displayed here, but the description compensates by explaining the response semantics (has_more, next_start_page).

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 all parameters. The description adds operational semantics by explaining how to use start_page and count in the pagination loop (start from 1, use next_start_page, respect the 10-page cap). This goes beyond the schema's simple default and type info.

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 purpose with a specific verb+resource: 'visually inspect PDF pages to identify content that cannot be detected from text alone.' It explicitly differentiates from siblings like view_pdf and get_pdf_info by focusing on visual elements (logo, photograph, watermark, QR code).

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 explicit 'when to use' context ('Use this when you need to visually inspect PDF pages...') and gives detailed step-by-step pagination instructions. It does not explicitly name alternative tools or when-not-to-use scenarios, but the context strongly implies the tool is for visual content only, so it earns above baseline.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the tool's safety profile. The description adds minimal behavioral context beyond purpose, but it does not contradict 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 consists of two concise sentences, with the primary action front-loaded. There is no redundant or unnecessary wording.

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 status check with schema-covered parameters and an output schema present, the description adequately covers purpose and usage context. It could potentially mention side effects, but the annotations already cover that.

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

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

The input schema provides full descriptions for both parameters (job_id and session_id) with 100% coverage. The description adds no additional parameter semantics, so 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 tool's function: returning the current status of a PDF viewer job. It uses a specific verb and resource, and the mention of 'PDF viewer job' distinguishes it from sibling tools like check_upload_status.

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

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

The phrase 'Used internally by the viewer widget' provides clear context about when the tool is intended to be used. However, it does not explicitly mention alternatives or when not to use it, leaving some room for interpretation.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description reinforces 'Read-only: does not modify job state' and adds crucial details: 'The returned text field... is the source of truth — you MUST use it to count exact character positions. Character positions within each line are 0-based from the start of that line.' This exceeds annotation coverage. 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?

Five sentences, all relevant and front-loaded. No fluff. Immediately states purpose, then read-only hint, usage order, and data semantics. 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?

Covers purpose, behavior, usage order, and key data semantics (0-based indexing, source of truth). Output schema exists but not shown; description mentions 'text' field. Minor lack of handling for edge cases like empty results, but overall complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add extra semantics beyond the schema. The schema already includes guidance like 'use the latest job_id' for the job_id parameter.

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 'Return per-page, per-line text for identifying redaction targets.' This clearly specifies the verb (return) and resource (per-page, per-line text). It distinguishes from sibling tools like redact_by_text_range which performs actual redaction.

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

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

Explicitly says 'ALWAYS call this before redact_by_text_range,' providing clear usage ordering. Also states 'Read-only: does not modify job state,' implying safe to call anytime. No explicit when-not, but the sibling tools cover different actions.

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

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

The description discloses important behavioral details beyond the annotations: exact substring matching requirements, whole-word vs. substring behavior for non-CJK vs. CJK text, the creation of a new job_id with parent_job_id linkage, and a mandatory verification loop. These are significant operational traits that an agent would not know otherwise.

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 long but well-structured, with a clear step-by-step workflow and an illustrative example. Every section adds necessary operational detail; however, some repetition around verification could be tightened without losing value.

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 complexity of the tool, the description is remarkably complete: it covers the full workflow, matching rules, example payload, job_id behavior, verification requirements, and the follow-up view_pdf step. Since an output schema exists, the description does not need to explain return values, and it thoroughly covers all other 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?

Although schema coverage is 100%, the description adds crucial meaning: page_index is 1-based, line_index comes from list_redactable_line_text, the text must match verbatim, and the content structure groups targets by page. This enrichment goes well beyond the bare schema definitions and ensures correct payload construction.

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: 'Redact PDF text by specifying the exact text to remove on each line.' It distinguishes itself from siblings like list_redactable_line_text (which retrieves text) and delete_pdf_page (which removes pages) by focusing on text-level redaction per line.

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

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

The description provides a mandatory workflow with explicit steps: call list_redactable_line_text first, build the payload, then verify by calling list_redactable_line_text again and re-redact if needed. This clearly instructs when to use the tool and how it relates to sibling tools, leaving no ambiguity about prerequisites or follow-up actions.

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

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

Discloses that the operation creates a new job_id with a parent_job_id linking to the source, exceeding the baseline set by annotations. It also indicates that the result should be viewed via view_pdf, adding behavioral context not present in 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 three sentences, front-loading the primary action, then adding critical usage notes and an exclusion. Every sentence is purposeful and concise, with no filler.

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

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

Given the availability of annotations and an output schema, the description covers the tool's purpose, preconditions, post-operation steps, and distinction from related tools. It is complete for the tool's complexity without redundant 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 input schema already provides 100% parameter coverage with clear descriptions for all four parameters. The description does not add significant meaning beyond the schema, so 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 tool's function ('Add password protection to an unprotected PDF file') and distinguishes it from the sibling tool change_password by explicitly noting when not to use it. This meets the highest standard for purpose clarity.

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 explicit usage guidance: do not call on already-protected PDFs, use change_password instead, and instructs to call view_pdf with the new job_id after completion. This fully addresses when and when not to use the tool.

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

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

The description adds critical behavioral context beyond empty annotations: it mandates a pre-check, forbids direct invocation if job exists, prohibits inventing download URLs, and clarifies that it only works on ChatGPT hosts. It also provides fallback behavior for when the tool is unavailable, which is not visible from 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 longer than average, but every sentence earns its place: front-loaded core action, numbered mandatory workflow, explicit prohibitions, and fallback notes. The structured layout with bolded steps aids comprehension and makes the complexity manageable.

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's complexity (host attachment resolution, mandatory pre-check, alternative tools) is fully covered. It explains the relationship with check_upload_status and create_upload_page, and notes return values (session_id, job_id). Since an output schema exists, lack of detailed return descriptions is acceptable.

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?

With 100% schema coverage, the baseline is 3, but the description adds meaning by explaining that pdf_file comes from the host-resolved attachment and instructing the agent to pass it straight through without constructing or inspecting download URLs or file_ids. This goes beyond the schema's basic field definitions.

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

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

The description opens with 'Upload a PDF from a ChatGPT file attachment,' a specific verb+resource. It further distinguishes from siblings by noting it only works on ChatGPT hosts and mentioning create_upload_page as an alternative for other clients, and check_upload_status for existing jobs. Its purpose is unmistakable.

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

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

Explicit when-to-use and when-not-to: 'Use this when the user provides a file attachment in ChatGPT'; 'If you do not have a real attachment... this is not the right tool'; 'On every other MCP client... call create_upload_page instead.' It also mandates calling check_upload_status first and reusing existing job_id, avoiding redundant uploads.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context not available in annotations: the upload tools show nothing and require this call, create_upload_page self-renders and must not be followed by view_pdf, the job_id must originate from specific tools, and there are mandatory post-conditions (render download link, follow cta_instruction). This goes well beyond the annotation safety profile.

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

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

The description is longer than average but well-structured with clear sections, bolded emphasis, and bullet points. Each paragraph serves a distinct purpose: core definition, usage triggers, upload caveat, job_id constraints, and post-conditions. While lengthy, the information density is high and layout improves scannability; a slight trim could make it a 5.

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

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

Given the tool's complexity (interaction with upload flow, job_id provenance, post-conditions), the description covers all necessary context. It addresses common mistakes (forgetting to call after upload, inventing job_id), specifies the exact call sequence, and provides mandatory follow-up actions. The output schema exists, so return value details are not needed in the description.

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 describes both parameters with 100% coverage, giving names and brief descriptions. The description adds critical semantics for job_id: it must come from upload_pdf, batch_upload_pdf, or check_upload_status; never invent or use a filename. This is valuable beyond the schema, though session_id receives no additional detail. With high schema coverage, baseline 3, and added job_id guidance, a 4 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 opens with 'Display an already-uploaded PDF in an interactive viewer widget,' which uses a specific verb ('display') and resource ('already-uploaded PDF') and clearly differentiates from siblings like upload_pdf and create_upload_page. It explicitly notes the upload tools show nothing, reinforcing the unique 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 explicit when-to-use guidance: after delete_pdf_page, set_password, change_password, redact_pii, redact_by_text_range, and when the user asks to re-display. It also covers when NOT to call (after create_upload_page) and warns that after upload_pdf/batch_upload_pdf you MUST call view_pdf, giving clear conditional logic and alternatives.

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