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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the priority rule for QR code paths, which is useful context, but lacks critical behavioral details: it doesn't specify whether this operation modifies the original PDF or creates a new file, what permissions or prerequisites are needed, potential side effects, or error handling. For a tool that likely mutates PDFs, this is a significant gap in transparency.

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

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

The description is appropriately concise with two sentences that front-load the core purpose and include a key behavioral detail (priority rule). There's no wasted verbiage, though it could be slightly more structured by explicitly separating purpose from usage guidelines.

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 (7 parameters, likely mutates PDFs) and lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., success status, file path), potential errors, or important behavioral aspects like file handling. For a tool with this level of functionality, more context is needed to be fully helpful to 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?

The schema description coverage is high at 86%, so the schema already documents most parameters well. The description adds minimal value beyond the schema: it reiterates that QR code must be an image file (PNG/JPG) and mentions the priority rule, but doesn't provide additional semantic context like how 'friendly text' is formatted or what 'scale ratio' means practically. This meets the baseline for high 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 tool's purpose: 'Add QR code to PDF documents with friendly text below.' It specifies the resource (PDF documents) and the action (add QR code), though it doesn't explicitly differentiate from sibling tools like 'add_watermark' or 'process_pdf_post_conversion' which might have overlapping PDF modification functions.

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 some usage context by stating 'Priority: user provided path > environment variable QR_CODE_IMAGE,' which helps understand parameter precedence. However, it doesn't explicitly guide when to use this tool versus alternatives like 'add_watermark' for other PDF modifications or 'convert_document' for format changes, leaving usage decisions implied rather than clearly defined.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the priority system for watermark sources (text > image > environment variable > default), which is crucial behavioral context. However, it doesn't mention whether this operation modifies the original PDF or creates a new file, potential file size impacts, or error conditions.

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 perfectly front-loaded with the core purpose, followed by supporting details about watermark types and priority system. Every sentence earns its place by providing essential information without redundancy or fluff.

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

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

For a tool with no annotations and no output schema, the description does well by explaining the core functionality and parameter interactions. However, it doesn't describe what the tool returns (e.g., path to watermarked PDF, success/failure status) or potential side effects, leaving some gaps in completeness.

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 83% schema description coverage, the baseline is 3. The description adds significant value by explaining the priority hierarchy among watermarkText, watermarkImage, and fallback options, which clarifies the interaction between parameters beyond what the individual parameter descriptions provide in the schema.

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

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

The description clearly states the specific action ('add watermarks') and resource ('PDF documents'), and distinguishes this tool from siblings by specifying its unique watermarking functionality. Unlike sibling tools focused on conversion, reading, writing, or QR codes, this tool is explicitly for watermarking 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?

The description provides clear context about when to use this tool (for adding watermarks to PDFs) and implicitly distinguishes it from siblings that handle different document operations. However, it lacks explicit guidance on when NOT to use it or named alternatives for similar tasks.

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

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

With no annotations provided, the description carries full burden and adds valuable behavioral context: it discloses that output directory is controlled by OUTPUT_DIR environment variable, files are auto-saved with auto-generated names, and warns about conversion loops for Word documents. This goes beyond basic functionality to describe operational 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 well-structured with three focused sentences: core functionality, operational behavior, and usage guidance. Each sentence earns its place, though the warning emoji and formatting 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?

For a conversion tool with 4 parameters, 100% schema coverage, but no annotations or output schema, the description provides good completeness: it explains the core purpose, behavioral context (output handling), and clear usage guidelines. The main gap is lack of information about return values or error handling.

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 all 4 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, maintaining the baseline score of 3 for high 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 tool converts documents between formats with enhanced style preservation, providing a specific verb (convert) and resource (documents). It distinguishes from some siblings by mentioning specific alternatives, though not all sibling tools are addressed.

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 guidance on when to use alternative tools instead: 'convert_markdown_to_html' for Markdown to HTML with themes/styling and 'create_word_document' for creating Word documents from content. This clearly defines when-not-to-use scenarios with named alternatives.

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

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

With no annotations provided, the description carries full burden. It discloses that files are automatically saved to OUTPUT_DIR with auto-generated names, which is useful behavioral context. However, it doesn't mention error handling, performance characteristics, or what happens if environment variables are missing, leaving gaps for a mutation 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 appropriately sized with three sentences that efficiently cover conversion purpose, optional features, and output behavior. It's front-loaded with the core functionality, though some repetition with schema details slightly reduces efficiency.

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 5-parameter mutation tool with no annotations and no output schema, the description is moderately complete. It covers the conversion process and output location but lacks details on error cases, return values, or integration with sibling tools, leaving room for improvement.

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 all 5 parameters thoroughly. The description adds minimal value by repeating some parameter details (e.g., watermark/QR code environment variables) but doesn't provide additional semantic context beyond what's in the schema.

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

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

The description clearly states the tool converts DOCX to PDF with style replication and Playwright integration, which is a specific verb+resource. However, it doesn't explicitly distinguish from sibling tools like 'convert_document' or 'convert_markdown_to_pdf', which appear to handle different conversion types.

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 mentions watermark and QR code capabilities but provides no guidance on when to use this tool versus alternatives like 'add_qrcode' or 'add_watermark' standalone tools. It lacks explicit when/when-not instructions or prerequisites for effective use.

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

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

With no annotations provided, the description carries full burden. It discloses key behavioral traits: the tool saves files automatically to OUTPUT_DIR with auto-generated names, which is crucial operational context. However, it doesn't mention error handling, performance characteristics, or what happens if OUTPUT_DIR isn't set, leaving gaps in behavioral understanding.

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 appropriately sized with three sentences that each serve a purpose: stating the core functionality, describing preservation features, and explaining output behavior. It's front-loaded with the main purpose, though the second sentence could be more concise by combining structure and formatting mentions.

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 conversion tool with 4 parameters, 100% schema coverage, and no output schema, the description is moderately complete. It covers what the tool does and output behavior but lacks information about return values, error conditions, or performance expectations that would help an agent use it effectively in complex workflows.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter semantics beyond the schema, mentioning 'style preservation' which relates to preserveStyles parameter, but doesn't provide additional context about parameter interactions or practical implications of the boolean flags.

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 specific verbs ('converts HTML files to clean Markdown format') and resources ('HTML files'), distinguishing it from sibling tools like convert_markdown_to_html or convert_document by specifying the exact conversion direction and format preservation features.

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 like convert_document or convert_markdown_to_html. It mentions output directory control via environment variable, but this is operational detail rather than usage context or exclusion criteria.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it preserves formatting, supports specific elements (tables, lists, headings), uses an output directory via environment variable, and auto-generates filenames. However, it does not mention error handling, file size limits, or performance considerations, leaving some gaps.

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 appropriately sized and front-loaded, starting with the core purpose and key features. However, the second sentence could be more streamlined, as it lists formatting elements redundantly (e.g., 'preserves formatting' and 'supports tables, lists, headings, and inline formatting' overlap slightly). Overall, it is efficient with minimal 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?

Given the complexity (conversion tool with multiple parameters) and no annotations or output schema, the description is moderately complete. It covers the main purpose, key features, and output behavior, but lacks details on error cases, return values, or advanced usage scenarios, which would be helpful for an AI 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?

The input schema has 100% description coverage, so the baseline is 3. The description adds minimal parameter semantics beyond the schema, mentioning theme support and output directory control, but does not elaborate on parameter interactions or provide additional context for the parameters listed in the schema.

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

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

The description clearly states the tool's purpose: converting Markdown files to DOCX format with professional styling and theme support. It specifies the exact transformation (Markdown to DOCX) and distinguishes it from sibling tools like convert_markdown_to_html and convert_markdown_to_pdf by focusing on DOCX output with styling features.

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 by mentioning theme support and output directory control, but it does not explicitly state when to use this tool versus alternatives like convert_markdown_to_pdf or create_word_document. It provides some context (e.g., for professional styling) but lacks clear exclusions or comparisons with siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: files are automatically saved to OUTPUT_DIR with auto-generated names, and it supports multiple themes. However, it doesn't cover error handling, performance, or what happens if OUTPUT_DIR is missing. It adds useful context but isn't comprehensive.

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 appropriately sized with three sentences that are front-loaded with the core purpose. Each sentence adds value: the first states the tool's function, the second details themes, and the third explains file handling. There's no wasted text, though it could be slightly more 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?

Given no annotations and no output schema, the description is moderately complete. It covers the tool's purpose, themes, and file-saving behavior, but lacks details on output format, error cases, or prerequisites. For a conversion tool with 4 parameters, it's adequate but has gaps in behavioral 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 description coverage is 100%, so the schema fully documents all parameters. The description adds minimal value beyond the schema, mentioning theme support and OUTPUT_DIR (which isn't a parameter but an environment variable). It doesn't explain parameter interactions or provide additional semantics, 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's purpose: 'Enhanced Markdown to HTML conversion with beautiful styling and theme support.' It specifies the verb ('conversion'), resource ('Markdown to HTML'), and distinguishes from siblings like 'convert_markdown_to_docx' or 'convert_markdown_to_pdf' by focusing on HTML output with styling features.

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 clear context for when to use this tool: for converting Markdown to HTML with styling and theme options. It doesn't explicitly state when not to use it or name alternatives, but the context implies it's for HTML output specifically, not other formats like DOCX or PDF offered by siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: automatic file saving to OUTPUT_DIR with auto-generated names, dependencies on environment variables (WATERMARK_IMAGE, QR_CODE_IMAGE, OUTPUT_DIR), and the requirement for playwright-mcp. However, it doesn't mention error handling, performance characteristics, or whether the operation is idempotent.

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 appropriately sized and front-loaded, starting with the core purpose. However, it could be more structured—environment variable details are scattered throughout, and the sentence about output directory placement feels tacked on. Most sentences earn their place, but minor reorganization would improve clarity.

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 conversion tool with no annotations and no output schema, the description does well to cover key behaviors like file handling and dependencies. It explains what happens to the output (saved automatically) and prerequisites (playwright-mcp). The main gap is lack of information about return values or error responses, which would be helpful given the absence of an output schema.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema—it repeats watermark and QR code environment variable details but doesn't provide additional context about parameter interactions or usage examples. Baseline 3 is appropriate when the schema does most of the work.

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: converting Markdown to PDF with enhanced styling and theme support. It specifies the exact transformation (Markdown→PDF) and distinguishes itself from siblings like convert_markdown_to_docx or convert_markdown_to_html by focusing on PDF output with specific features like watermarks and QR codes.

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 clear context for when to use this tool: for PDF conversion with styling options. It mentions alternatives implicitly by noting requirements like playwright-mcp and environment variables, but doesn't explicitly compare to siblings like convert_docx_to_pdf or convert_markdown_to_docx, which would have strengthened the 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?

No annotations are provided, so the description carries the full burden. It discloses that files are automatically saved to OUTPUT_DIR with auto-generated names, which is useful behavioral context. However, it lacks details on permissions, error handling, rate limits, or what happens if OUTPUT_DIR is missing. The description doesn't contradict annotations (none provided).

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

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

The description is front-loaded with the main purpose and key features (HTML support, automatic formatting). It uses four sentences efficiently, with no redundant information. However, the last sentence about OUTPUT_DIR could be integrated more smoothly, and it's slightly verbose in explaining file saving.

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 no annotations and no output schema, the description provides basic purpose and behavioral details (auto-saving, HTML support). It covers the core functionality but lacks information on return values, error cases, or advanced usage scenarios. For a creation tool with 3 parameters, it's adequate but has clear gaps in completeness.

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 all parameters. The description adds that content supports HTML and mentions automatic styling/formatting, which aligns with the schema's preserveFormatting parameter. It doesn't provide additional syntax or format details beyond the schema, so 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 creates Word documents from content with formatting, specifying it's for creating from scratch and supports HTML. It distinguishes from siblings like convert_document or write_document by emphasizing direct creation without conversion loops. However, it doesn't explicitly contrast with all siblings (e.g., convert_markdown_to_docx).

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 for creating Word documents from scratch with HTML content, avoiding conversion loops. It doesn't explicitly state when not to use it or name alternatives among siblings, though the context suggests it's for direct creation rather than conversion tools. No prerequisites or exclusions are mentioned.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates critical behavioral traits: the mandatory sequencing requirement ('MUST be executed BEFORE'), the workflow nature ('get the optimal conversion plan, then follow the plan's steps exactly'), and integration dependencies ('playwright-mcp integration is required for final PDF generation'). However, it doesn't mention rate limits, error handling, or performance characteristics.

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 appropriately front-loaded with the critical 'MANDATORY FIRST STEP' information, but contains some redundancy (e.g., repeating format conversion examples) and could be more streamlined. The emojis and formatting add visual emphasis but don't necessarily improve conciseness. Most sentences earn their place, but some phrasing could be tightened.

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 a 7-parameter planning tool with no annotations and no output schema, the description does a good job explaining the tool's role in the workflow, mandatory sequencing, and integration points. However, it doesn't describe what the output plan looks like or how to interpret it, which is a significant gap since there's no output schema to compensate.

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 coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema descriptions and enums. It mentions format conversion generally but provides no additional syntax, format details, or parameter usage guidance beyond the structured schema.

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

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

The description explicitly states the tool's purpose as a 'Smart Document Conversion Planner' that must be executed before any document conversion operation. It specifies the verb ('plan') and resource ('conversion'), and clearly distinguishes it from sibling tools by emphasizing it's a mandatory first step rather than a direct conversion tool like convert_document or convert_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 explicit usage guidelines: 'MUST be executed BEFORE any document conversion operation' and 'When users request any format conversion... you MUST call this tool first.' It also mentions specific follow-up tools for PDF conversions (playwright-mcp integration and process_pdf_post_conversion), giving clear alternatives and sequencing instructions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's workflow dependencies, mandatory sequencing, and three core behaviors (move, add features, clean up). However, it doesn't mention potential side effects like file overwriting, permission requirements, or error handling for missing environment variables.

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 appropriately sized and front-loaded with the most critical information (workflow dependency). However, the emoji usage and formatting (🔧, ⚠️) add visual noise without semantic value, and the numbered feature list could be more concise. Every sentence earns its place by conveying essential workflow 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?

Given the tool's complexity (14 parameters, no annotations, no output schema), the description provides good contextual completeness by explaining the mandatory workflow sequence and core operations. However, it doesn't describe the return value or error conditions, which would be helpful given the absence of an output schema and annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description doesn't add meaningful parameter semantics beyond what's already documented in the schema - it mentions watermarks and QR codes generally but provides no additional details about parameter interactions, defaults, or environment variable precedence that aren't already in the schema 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 purpose as a 'necessary follow-up step' that performs three specific functions: moving PDFs, adding watermarks/QR codes, and cleaning temporary files. It explicitly distinguishes this from sibling tools by mentioning it's specifically for post-processing PDFs generated by playwright-mcp, unlike general conversion or watermarking tools in the sibling list.

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: it must be called 'immediately' after playwright-mcp's browser_pdf_save command, creating a clear workflow dependency. It also distinguishes when to use this tool versus alternatives by positioning it as a required follow-up to a specific playwright-mcp command, not as a standalone watermarking or QR code 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions reading various formats but doesn't specify what 'read' entails (e.g., returning text content, handling errors for unsupported formats, or performance considerations). It lacks details on permissions needed, rate limits, or output behavior, which is a significant gap for a tool with no annotation coverage.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action ('read') and resource ('various document formats'), and the list of formats is concise. Every part of the sentence earns its place by clarifying scope.

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 no annotations, no output schema, and a tool that reads documents (which could involve complex format handling), the description is incomplete. It doesn't explain what the tool returns (e.g., text content, metadata structure), error conditions, or limitations (e.g., file size constraints). For a tool with 3 parameters and potential format-specific behaviors, more context is needed.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (filePath, extractMetadata, preserveFormatting). The description adds no additional meaning about parameters, such as format-specific behaviors or how 'preserveFormatting' interacts with different file types. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the verb 'read' and the resource 'various document formats', listing specific file types (DOCX, DOC, TXT, MD, HTML, etc.). It distinguishes from sibling tools like 'write_document' and 'convert_document' by focusing on reading rather than writing or conversion. However, it doesn't explicitly differentiate from all siblings (e.g., 'process_pdf_post_conversion' might also involve reading).

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 doesn't mention when to choose this over 'convert_document' for format handling, or when to use it in conjunction with other tools like 'add_watermark'. There's no context about prerequisites, such as file accessibility or format limitations beyond the listed types.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that files are automatically saved to OUTPUT_DIR with auto-generated names and supports format detection, which is helpful. However, it lacks critical details: it doesn't specify whether this is a write-only operation (no read-back), what happens if OUTPUT_DIR doesn't exist, potential file overwriting risks, or error handling. For a file-writing tool with zero annotation coverage, this leaves significant gaps.

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 appropriately concise with three sentences that efficiently cover the core functionality, output behavior, and format support. It's front-loaded with the main purpose and avoids unnecessary repetition. However, the third sentence about 'intelligent format detection' could be integrated more smoothly, slightly affecting flow.

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 (file writing with multiple parameters), lack of annotations, and no output schema, the description is moderately complete. It covers the basic operation and output directory behavior but misses key contextual details like error handling, file naming specifics, or interaction with sibling tools. It's adequate for a simple write operation but lacks depth for robust agent 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 description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds marginal value by mentioning 'auto-generated names based on content type' and 'intelligent format detection,' which loosely relates to the 'format' and 'title' parameters but doesn't provide additional syntax or format details beyond what the schema specifies. This meets the baseline for high 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 tool's purpose: 'Write content to document files in specified formats.' It specifies the action (write), resource (document files), and scope (multiple formats). However, it doesn't explicitly differentiate from sibling tools like 'create_word_document' or 'convert_document', which reduces it from a perfect score.

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 minimal usage guidance. It mentions that files are saved to OUTPUT_DIR with auto-generated names, but offers no explicit advice on when to use this tool versus alternatives like 'create_word_document' or 'convert_document' from the sibling list. There's no mention of prerequisites or when-not-to-use scenarios.

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