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

Strong supplemental context: while annotations confirm read-only/idempotent safety, the description details the specific JSON structure returned (listing 13+ distinct metrics like heading counts, code block counts, reading time). This compensates for the missing output schema.

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?

Optimal structure: Two sentences, front-loaded with action ('Analyze...'), followed by output specification. Zero redundancy—every word earns its place.

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

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

Complete for the tool's complexity: despite lacking an output schema, the description enumerates return values in detail. With rich annotations (4 boolean hints) and 100% parameter coverage, this adequately equips the agent.

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

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

Schema coverage is 100% ('markdown' parameter fully described), so the description does not need to add parameter semantics. Baseline 3 is appropriate as the schema carries the semantic 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?

Excellent specificity: 'Analyze' (verb) + 'Markdown document' (resource) + 'return comprehensive statistics' (output). Clearly distinguishes from conversion siblings (convert_to_*) and extraction siblings (extract_*) by focusing on statistical analysis rather than format transformation or content isolation.

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?

Implied usage is clear (analysis vs conversion), but lacks explicit guidance on when to choose this over extraction tools like extract_code_blocks or extract_links, or generator tools like generate_toc which overlap conceptually with document analysis.

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 cover idempotency and safety (readOnlyHint=false, destructiveHint=false). The description adds valuable transformation semantics: specific mappings for headers, code blocks, links, and images. It does not explicitly mention file I/O behavior, though output_path schema covers this.

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

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

Two sentences total. First establishes purpose; second provides concrete syntax examples. Zero filler content. Every word earns its place by conveying AsciiDoc-specific formatting rules.

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 straightforward conversion purpose, rich annotations, and comprehensive schema, the description is complete. It explains the transformation semantics adequately without needing to elaborate on return values (handled by 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 coverage is 100% with detailed parameter descriptions (markdown supports GFM/KaTeX, output_path creates parent directories). Description focuses on transformation logic rather than repeating parameter specs, which is appropriate given the rich schema documentation.

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 opens with specific verb 'Convert' and target format 'AsciiDoc', immediately clarifying scope. The detailed syntax transformations (= headers, ---- code blocks) distinguish it from siblings like convert_to_html or convert_to_rst that would produce different markup.

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

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

No explicit 'when to use' or comparison with alternatives is stated. However, the specific AsciiDoc syntax examples (image::url, url[text]) implicitly signal this tool's domain versus other conversion siblings, providing contextual hints for selection.

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 establish safety profile (idempotent, non-destructive). The description adds valuable behavioral context by enumerating the specific BBCode tags supported and target forum platforms, which is critical information not present in structured fields.

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 constructed sentences with zero waste: first establishes conversion direction, second details supported formatting tags, third provides platform context. Front-loaded with the essential action.

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 100% schema coverage and comprehensive annotations, the description adequately covers the conversion domain. Mention of specific BBCode tags and forum platforms provides sufficient context. Could benefit from explicit mention of dual return modes (string vs JSON summary), though the schema handles this.

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 comprehensive parameter descriptions already provided in the schema (markdown content details, output_path file behavior with return value semantics). Baseline 3 is appropriate as the description focuses on conversion behavior rather than repeating schema details.

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

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

The description states a specific verb (Convert) and resources (Markdown to BBCode), and distinguishes from siblings by specifying the target format (BBCode) and supported tags ([b], [i], etc.), clearly positioning it among the many conversion tools available.

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 clear contextual guidance by specifying the target use case ('forum posts on phpBB, vBulletin, and similar platforms'), which helps distinguish it from other converters like convert_to_html or convert_to_docx. Lacks explicit 'when not to use' 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 declare idempotentHint=true and non-destructive behavior. Description adds value by specifying exact output format quirks ({info}, {note}, {code} macros) that pure schema doesn't cover. Does not address file I/O side effects (covered in schema) or error behaviors.

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

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

Two sentences, zero waste. First_sentence establishes operation, second_sentence provides critical sibling differentiation and output format specifics. Every word earns its place.

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

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

Adequate for a conversion utility with simple I/O. Covers core functionality and format-specific features. Lacks error handling documentation or edge case notes (e.g., unsupported Markdown extensions), but acceptable given idempotentHint and full schema coverage.

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 detailed descriptions for both 'markdown' (GFM support details) and 'output_path' (file vs return behavior). Description provides no additional parameter syntax guidance, meeting baseline expectation when schema is comprehensive.

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 specific verb 'Convert' + resource 'Markdown/Confluence wiki markup'. Explicitly distinguishes from sibling 'convert_to_jira' by contrasting Confluence-specific panels vs JIRA syntax, preventing selection errors.

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?

Implicitly guides selection by stating 'Similar to JIRA but includes Confluence-specific...' which signals the differentiation point. However, lacks explicit 'use when targeting Confluence vs JIRA' directive 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?

Beyond annotations (which only declare idempotency/safety), the description details critical behavioral specifics: dual return modes (string vs JSON object), file system side effects (creates parent directories, overwrites existing files), and content handling (multiple tables concatenated with blank lines, non-table content ignored, no-tables returns empty string).

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?

Six sentences covering distinct aspects: conversion logic, content handling, side effects, return values, and usage recommendations. Every sentence provides unique information not redundant with the schema or annotations. Slightly dense but appropriate for the complexity of dual-output behavior.

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

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

Without an output schema, the description fully compensates by detailing return structures (CSV string vs JSON object with specific fields), edge case behaviors (empty input handling), and side effect warnings necessary for safe invocation.

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

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

With 100% schema coverage, baseline is 3. The description adds value by connecting output_path to behavioral outcomes (overwriting existing files) and explaining the conditional return type logic tied to this parameter, though it doesn't significantly expand on the markdown parameter semantics.

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-resource combination ('Extract tables from Markdown and convert them to CSV format') and explicitly distinguishes from siblings by naming 'convert_to_xlsx' and 'convert_to_json' as alternatives for different use cases.

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 ('lightweight tabular export or when downstream tools expect CSV') and provides clear alternatives ('Prefer convert_to_xlsx for Excel-compatible spreadsheets... or convert_to_json for structured data'), guiding the agent away from incorrect selections.

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 declare idempotent/non-destructive, but description adds valuable behavioral specifics: headers become bold/underline, code blocks are preserved, and basic formatting is maintained. This disclosure of specific transformation logic is exactly the context annotations cannot provide. No contradictions 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?

Three sentences with zero waste: purpose statement, specific transformation detail, preservation guarantee. Every sentence earns its place. Well front-loaded with the core action in sentence one.

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?

Appropriate for a format-conversion tool with 2 parameters and no output schema. Covers input expectations and transformation behavior. Missing only documentation of the return value duality (file vs. string) which is a significant behavioral gap given the output_path parameter exists.

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, baseline is 3. Description implicitly reinforces the 'markdown' parameter by mentioning GFM features (tables, headers) but does not explicitly walk through parameters or add syntax guidance beyond the schema. Notably omits mention of the output_path parameter's dual-behavior (file write vs. string return).

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

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

Clearly states the verb (Convert), source (Markdown), and target format (Discord-compatible). The mention of 'headers to styled bold/underline' specifically signals Discord's limitations, distinguishing it from siblings like convert_to_html or convert_to_slack. Could be 5 if it explicitly contrasted with the many other conversion tools available.

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

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

Provides implicit usage guidance by specifying 'renders correctly in Discord messages,' which signals when to select this over other converters. However, lacks explicit when-not-to-use guidance or sibling comparisons despite having 20+ conversion alternatives. Does not clarify when to use output_path vs. receiving direct string output.

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?

Excellent disclosure beyond annotations: details side effects (writes binary to disk, creates directories, overwrites files), explains dual return modes (JSON confirmation vs JSON binary-guidance with base64_preview), and clarifies the re-call pattern when output_path is omitted. Complements annotations (readOnly=false, destructive=false) with specific I/O 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?

Well-structured progression: purpose → output characteristics → side effects → return values → usage comparisons. Each sentence provides distinct value. Minor verbosity in return value explanation could be tighter, but front-loading is strong and scannable.

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

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

Despite no output schema, comprehensively documents both return structures (write-confirmation and binary-guidance objects). Adequately covers binary conversion complexity, file system interactions, and sibling tool landscape. No gaps given the tool's scope.

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 has 100% coverage with detailed parameter descriptions. Description adds critical usage context beyond schema: emphasizes that output_path is nearly mandatory for binary formats and explains the functional difference between providing vs omitting the parameter. Slight deduction for not adding semantic nuances to the 'markdown' parameter beyond schema definition.

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 specific verb ('Convert') with source and target resources (Markdown to DOCX). Explicitly distinguishes from 21 sibling conversion tools by specifying 'Word-compatible documents' and contrasting with RTF, PDF, and HTML 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?

Provides explicit guidance on when to use ('Word-compatible documents') and clear alternatives ('Prefer convert_to_rtf for legacy... convert_to_pdf for read-only... convert_to_html for web'). Also specifies critical behavioral guidance that 'output_path should almost always be provided' for binary formats.

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 declare idempotent/non-destructive, but description adds crucial output characteristics: 'all styles inlined', 'responsive email table layout', and specific client compatibility. Explains the 'email-safe' HTML generation behavior that annotations cannot capture.

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

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

Four sentences, zero waste. Front-loaded with core function (conversion + inlining). Each subsequent sentence adds distinct value: client compatibility, CSS constraints, layout structure. No filler or redundant restatements.

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?

Strong coverage for a conversion tool. Despite no output schema, description characterizes the HTML output sufficiently (inlined styles, table layout, client compatibility). Schema handles parameter mechanics. Minor gap: doesn't mention the dual return modes (string vs file summary), though schema covers this.

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%, providing excellent parameter documentation (markdown format support, output_path behavior). Description references no parameters specifically, relying entirely on schema—a valid pattern when schema coverage is comprehensive. Baseline score applicable.

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?

Excellent specificity: verb 'Convert' + source resource 'Markdown' + target 'email-optimized HTML'. Critically distinguishes from sibling 'convert_to_html' via 'email-optimized' qualifier and specific compatibility claims (Outlook, Gmail, Apple Mail).

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?

Clear contextual signals for when to use: 'email-optimized', 'compatible with Outlook, Gmail...', and 'no external CSS dependencies' clearly indicate this is for email delivery vs web publishing. Lacks explicit sibling comparison (e.g., 'use convert_to_html for web pages'), but usage context is 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 indicate non-readOnly and idempotent behavior; the description adds critical side effect disclosure (file writes to disk, directory creation, overwriting behavior) and documents the dual return format (string vs JSON object) depending on output_path. Does not mention auth needs or rate limits, but covers the primary behavioral traits.

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 earns its place: opens with core function, details features, explains document structure, discloses side effects, specifies return values, and closes with usage guidance. No redundancy despite covering multiple output modes and sibling comparisons.

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 no output schema, the description fully specifies return behaviors (HTML string vs JSON structure), explains the complete document structure produced (<!DOCTYPE html> with CDN links), and contrasts with relevant siblings. Complete for a dual-mode conversion tool.

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

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

With 100% schema coverage, baseline is 3. The description adds semantic value by explaining the implications of providing vs omitting output_path (side effects vs direct return) and elaborating on markdown capabilities (GFM tables, task lists, strikethrough) beyond the schema's basic description.

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

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

The description clearly states the tool converts Markdown to a complete, styled HTML document, specifying support for GFM and KaTeX. It distinguishes from sibling `generate_html` by emphasizing this produces a full document with file I/O capabilities, while implying `generate_html` is for string-only output.

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?

Excellent guidance: explicitly states 'Use this when you need a file saved to disk' and provides named alternatives with conditions ('Prefer generate_html if you only need the HTML string...', 'Prefer convert_to_pdf for print-ready output'). This creates a clear decision tree against 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?

Substantially augments annotations by detailing: external dependency requirements (Puppeteer, Chrome executable), runtime side effects (transient browser process, CDN fetching), file system behavior (creates parent directories, overwrites existing), and dual return modes (disk write vs JSON binary-guidance). No contradictions 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?

Information-dense and front-loaded (purpose first). Length is justified by complexity (browser dependencies, binary output, two return paths). Minor deduction for slight verbosity in implementation details, but structure is logical: purpose → mechanism → prerequisites → side effects → returns → usage guidance.

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?

Excellent coverage given high complexity and missing output schema. Compensates for no output_schema by exhaustively documenting both return variants (JSON confirmation vs base64_preview object), external system requirements, and behavioral side effects. Sibling differentiation is thorough among 24+ conversion tools.

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, baseline is 3. Elevated to 4 by adding critical usage context: 'binary format — output_path should almost always be provided' and explaining the conditional return behavior based on output_path presence, neither of which is obvious from schema alone.

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

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

Opens with specific verb+resource ('Convert Markdown to a PNG image') and explicitly distinguishes from siblings ('Prefer convert_to_pdf... or convert_to_html'). Clearly defines scope (GFM tables, KaTeX math) and mechanism (headless Chromium).

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 ('when you need a visual snapshot... for embedding in chat, previews, social cards') and named alternatives ('Prefer convert_to_pdf for paginated print output'). Also specifies prerequisites (locally installed Chrome/Edge/Chromium).

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 indicate idempotent=true and readOnly=false; the description adds valuable behavioral context that the tool conditionally writes files to disk when output_path is provided, versus returning content directly, and details the exact transformation logic for content conversion.

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

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

Two well-structured sentences front-load the core purpose first, followed by specific syntax transformations. Efficient length with minimal redundancy, though the second sentence is dense with multiple examples.

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 2-parameter conversion utility with good annotations and no output schema, the description adequately covers transformation behavior, dual output modes, and input expectations. Could benefit from mentioning error handling or character encoding.

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 met, but the description adds meaningful context about supported Markdown syntax (tables, task lists) that clarifies valid input for the 'markdown' parameter beyond the schema's technical description.

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

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

Description clearly states 'Convert Markdown to JIRA wiki markup' with specific verb and resource. The detailed syntax examples (h1./h2., {code} blocks, [text|url] links) explicitly distinguish this from sibling converters like convert_to_confluence or convert_to_bbcode.

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 specificity of 'JIRA wiki markup' provides implicit guidance for when to use this tool versus the 20+ other conversion siblings, but lacks explicit when-to-use guidance or comparisons like 'use when targeting Atlassian JIRA vs other wiki formats'.

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 indicate readOnly=false and idempotent=true; the description adds valuable behavioral context including side effects (writes to disk, creates parent directories, overwrites files) and return value variations (JSON string vs summary object based on output_path). Could mention error handling or permissions for a 5.

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?

Logically structured with zero waste: purpose statement, structural details, use case, side effects, return values, when-to-use guidance, and alternatives. Each sentence earns its place despite the length, with clear transitions between concepts.

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?

Excellent completeness for a conversion tool with no output schema: fully documents return value structures for both paths (direct return vs file write), explains disk side effects, and differentiates from extensive sibling tool set. No gaps given the 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% with detailed descriptions for all 3 parameters (markdown, title, output_path). The description references parameters behaviorally ('when output_path is provided') but does not add semantic constraints, formats, or validation rules beyond what the schema already documents. Baseline 3 appropriate given 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 explicitly states 'Convert Markdown to a structured JSON representation' with specific details about the output structure (document title as root key, arrays of section objects containing headings, paragraphs, lists, etc.). It clearly distinguishes this from siblings by specifying JSON/AST-like output versus tabular or XML formats.

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 ('Use this when you need a machine-readable AST-like representation') and names specific alternatives ('Prefer convert_to_xml for XML-based interchange, or convert_to_csv/convert_to_xlsx for tabular data extraction'), giving clear guidance among the 20+ conversion 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?

Annotations indicate idempotentHint=true and readOnlyHint=false, but the description adds critical behavioral context: it discloses file system side effects ('writes the .tex file to disk'), directory creation behavior ('creates parent directories'), and overwrite behavior ('overwrites existing files'). It also explains the dual return mode (string vs JSON object) which annotations do not cover.

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?

Six sentences covering purpose, output format specifics, side effects, return values, and usage guidelines. Every sentence provides distinct information not replicated elsewhere. Slightly dense but necessary given the tool's conditional behavior (file write vs. string return).

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 for a conversion tool: input format details (GFM, KaTeX), output structure (specific LaTeX environments like itemize, verbatim), side effects (file I/O), return value schemas for both branches, and sibling alternatives. No output schema exists, and the description adequately compensates by documenting both possible return structures.

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?

While schema coverage is 100% (baseline 3), the description adds significant behavioral meaning to output_path by explaining that its presence triggers file write side effects and changes the return type from string to JSON object. This contextualizes the parameter beyond the schema's functional definition.

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 ('Convert Markdown to LaTeX source code') and immediately distinguishes from the sibling tool convert_to_pdf by stating 'For direct PDF output... use convert_to_pdf instead.' It clearly scopes the conversion domain (Markdown→LaTeX) amidst a large family of conversion tools.

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

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

Explicitly states when to use ('when you need to embed content in a LaTeX workflow or compile to PDF via pdflatex/xelatex externally') and provides a clear alternative for the opposite case ('For direct PDF output without a LaTeX toolchain, use convert_to_pdf instead'). This directly addresses sibling selection.

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 indicate write capability (readOnlyHint=false) and idempotency, but description adds crucial behavioral details: file system side effects (creates parent directories, overwrites), dual return modes (string vs JSON), and specific normalization rules applied (ATX headers, fenced code blocks).

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 clear information hierarchy: core purpose → parameter behavior → side effects → return values → usage guidance. Every sentence earns its place; no redundancy despite length.

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?

Excellent completeness given no output schema exists. Describes both return formats (string vs JSON structure), covers all parameters including optional behaviors, and documents side effects. Appropriate for a tool with dual output modes and file system interactions.

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 has 100% coverage establishing baseline of 3. Description adds valuable semantic context: relationship between 'harmonize' parameter and the standalone 'harmonize_markdown' tool, and the side-effect nature of 'output_path' (disk write vs direct return).

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?

Specific verb ('Export') and resource ('Markdown content') with clear scope. Explicitly distinguishes from sibling tools by referencing 'harmonize_markdown' and 'convert_to_* family', clarifying when to use each.

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 ('when you want to save Markdown to a file'), when-not-to-use ('Prefer harmonize_markdown if you only want to normalize formatting without saving'), and clear alternatives (sibling tools named specifically).

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 declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds valuable transformation context (specific syntax mappings) that annotations don't cover, but omits handling of edge cases like invalid Markdown or whether the conversion preserves YAML frontmatter. No contradictions with annotations.

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

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

Two efficiently structured sentences with zero waste. The first sentence establishes purpose; the second provides concrete transformation examples that immediately clarify scope. Every word earns its place.

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

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

Given the simple 2-parameter input schema with complete descriptions and available annotations, the description adequately covers the conversion logic without needing to document return values (handled in output_path schema description). Minor gap: doesn't mention error handling for malformed input.

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. The description adds semantic value by specifying which Markdown features are handled (tables, headers, bold, code), implicitly documenting the 'markdown' parameter's expected content type beyond the schema's technical description. It doesn't detail the output_path behavior, but the schema covers that comprehensively.

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 'Convert Markdown to MediaWiki markup' with specific verb and resource. The transformation examples (== syntax, triple quotes, <syntaxhighlight> tags, {| wikitable) specifically distinguish this from sibling conversion tools like convert_to_html or convert_to_latex by identifying the exact target format syntax.

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 through the MediaWiki-specific syntax examples, making it clear this produces MediaWiki markup versus other formats. However, it lacks explicit guidance on when to choose this over the 20+ sibling conversion tools (e.g., no 'use this for MediaWiki wikis, use convert_to_html for web pages' comparison).

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 indicate idempotent=true and destructive=false. The description adds valuable behavioral context beyond these flags by detailing specific syntax transformations (headers to *, bold to *text*, code blocks to #+BEGIN_SRC), helping the agent understand the conversion logic and output structure.

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

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

Two sentences efficiently convey the tool's purpose and specific transformation rules. Every clause serves a function—first establishing the conversion direction, second detailing syntax mappings—with no redundant or filler 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?

Given the 100% schema coverage and presence of annotations, the description provides sufficient context by explaining what gets converted and how. The return behavior is adequately covered in the output_path schema description, making this complete enough for tool selection.

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 structured documentation already comprehensively describes both parameters. The description does not add parameter-specific guidance (e.g., format expectations for the markdown string), warranting the baseline score for high-coverage schemas.

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

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

The description clearly states the specific action ('Convert') and resources ('Markdown to Emacs Org Mode format'), distinguishing it from 20+ sibling conversion tools by explicitly naming the target format and providing syntax-specific details.

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?

While the description clearly identifies the tool's purpose (converting to Org Mode), it lacks explicit guidance on when to select this specific converter versus siblings like convert_to_asciidoc or convert_to_rst. Usage is implied by the format name but not stated as 'use this when...'.

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?

Rich disclosure beyond annotations: requires local Chrome/Chromium (with env var override), launches transient headless browser, CDN fetching behavior, directory creation, file overwrite behavior, and precise dual return format behavior (disk write vs JSON binary-guidance).

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?

Information-dense but well-structured: purpose→technical method→system requirements→side effects→file handling→return formats→sibling preferences. Each sentence earns its place given the complexity of external dependencies and dual output modes.

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?

Excellent coverage for a complex tool with external dependencies (Chromium), binary output, conditional return schemas, and side effects. Without output schema, description fully documents both return paths and operational prerequisites.

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, description adds crucial usage guidance: emphasizes output_path is almost mandatory for binary formats, explains the divergent return behaviors (confirmation JSON vs base64_preview JSON), and clarifies parent directory auto-creation semantics.

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 provides specific verb ('Convert'), resource ('Markdown' to 'PDF'), rendering pipeline details (GFM tables, KaTeX math, Puppeteer), and explicitly distinguishes from siblings ('Prefer convert_to_html... convert_to_docx... convert_to_latex').

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 ('high-fidelity, print-ready document output'), when to prefer alternatives (web-viewable→HTML, editable→DOCX, LaTeX toolchains), and critical usage constraint ('output_path should almost always be provided' for binary formats).

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 establish idempotentHint=true and destructiveHint=false. The description adds valuable transformation details (header underlining, code-block conversion, link syntax) that explain the conversion logic. It could improve by clarifying file overwrite behavior when output_path points to an existing file.

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

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

Two tight sentences with zero waste. The first establishes purpose; the second provides concrete transformation examples that earn their place by distinguishing RST output from other markup formats. Front-loaded and appropriately sized.

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 100% schema coverage and existing annotations, the description is complete. It covers input format expectations and transformation specifics. Could mention error handling for malformed Markdown, but not required given the tool's straightforward scope.

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. The description adds semantic value by explaining what happens to the markdown content (specific transformation rules) and implicitly clarifying the dual output behavior (string return vs file write) mentioned in the schema, helping users understand the markdown parameter's processing.

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

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

The description states the specific action (Convert) and resource (Markdown to RST) clearly. It distinguishes from siblings by detailing RST-specific transformations (underlined headers, code-block directives, reference syntax), making it clear this produces Sphinx-compatible RST rather than other formats.

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?

While the RST-specific syntax details imply when to use this tool (when you need reStructuredText output), there is no explicit guidance comparing it to sibling converters like convert_to_html or convert_to_latex, nor warnings about when to prefer 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?

Substantially exceeds annotations by detailing: (1) transformation behavior (preserves specific formatting types), (2) filesystem side effects (creates parent directories, overwrites existing files), and (3) bimodal return behavior (string vs JSON structure). Acts as complete behavioral spec.

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?

Six distinct sentences each serving unique purposes: conversion scope, side effects, conditional return #1, conditional return #2, usage guidance, alternatives. No redundancy; information density is high 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?

For a conversion utility with rich annotations and no output schema, description achieves completeness by documenting return structures, error-adjacent behaviors (directory creation, overwrites), target applications, and comparative tool selection. No gaps remain for agent 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?

While schema has 100% coverage, description adds critical semantic context linking output_path presence/absence to distinct return types (RTF string vs JSON object) and side effects, clarifying the parameter's role as a mode switch beyond simple file path semantics.

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 opens with specific verb-resource pair ('Convert Markdown to Rich Text Format') and immediately distinguishes scope with formatting details (bold, italic, headers, lists, code blocks). Naming convention and sibling differentiation are clear from the explicit RTF focus.

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 clause targeting 'legacy word processors, email clients' and names specific sibling alternatives ('Prefer convert_to_docx for modern Word documents, or convert_to_html for web display'), giving the agent clear decision 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?

Annotations declare idempotentHint=true and readOnlyHint=false. Description adds valuable transformation specifics beyond annotations: exact syntax conversions (**→*, _→_, headers→bold, links→<url|text>), helping agents predict output structure. No contradictions with annotations.

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

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

Two efficiently structured sentences. First sentence establishes purpose and transformation rules; second provides usage context. No redundancy, front-loaded with essential information despite the packed specifics of formatting transformations.

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 100% schema coverage and clear annotations, description adequately covers tool purpose. Absence of output schema noted, but schema's output_path description handles return value documentation. Missing only minor details like maximum input size or complex edge-case handling for 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 coverage is 100%, establishing baseline 3. Description references 'Markdown' input implicitly but does not elaborate on parameter semantics beyond schema descriptions. The output_path behavior is well-documented in schema property descriptions, requiring no additional description text.

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

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

Description states specific action ('Convert Markdown to Slack mrkdwn format') and enumerates exact transformations (bold→asterisks, italic→underscores, etc.). Clearly distinguishes from sibling converters like convert_to_html or convert_to_bbcode by specifying Slack-specific mrkdwn syntax.

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: 'Use this when pasting formatted content into Slack messages.' Lacks explicit 'when not to use' or named alternatives (e.g., 'use convert_to_html for web instead'), but provides clear contextual trigger.

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 declare idempotentHint=true and destructiveHint=false. Description adds platform compatibility context but does not disclose behavioral traits like 'creates parent directories automatically' (described in schema) or whether conversions are lossy.

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

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

Two sentences, zero waste. First sentence establishes core function; second provides platform context. Every element earns its place.

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

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

Appropriate for a conversion utility with 2 parameters and high schema coverage. Output behavior is well-documented in schema (string vs file return). Platform mention adds necessary domain 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 coverage is 100% with detailed descriptions for both parameters. Description does not add parameter semantics beyond schema, so baseline 3 applies per scoring rules for high-coverage schemas.

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

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

Specific verb 'Convert' with clear source/target resources (Markdown to Textile). Distinguishes from siblings by naming the specific markup format (Textile vs HTML, AsciiDoc, etc. in the convert_to_* family).

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 contextual guidance by listing specific platforms (Redmine, Basecamp, CMS) that consume Textile, implicitly signaling when to use this tool. Lacks explicit 'when not to use' or comparison with alternatives like convert_to_html.

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 (which only show idempotentHint), the description discloses critical behavioral traits: the conversion is 'destructive' (formatting lost), side effects include file system writes with directory creation and file overwriting, and return values differ based on parameter presence (string vs JSON).

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?

Six sentences cover: operation, result characteristics, destruction warning, side effects, return values, and usage guidelines. Every sentence earns its place, though slightly verbose. Well front-loaded with the core operation stated immediately.

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 (conditional side effects, dual return types, optional file I/O) and rich sibling ecosystem, the description is complete. It covers behavior, side effects, return formats, and sibling relationships without needing 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?

With 100% schema coverage, baseline is 3. The description adds significant value by explaining the dual-mode behavior of output_path (disk write vs direct return) and elaborating that markdown supports 'GitHub-Flavored Markdown and KaTeX', which aids agent decision-making.

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

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

The description uses specific verbs ('Convert'), identifies the resource ('Markdown to plain text'), and clearly distinguishes from siblings by explicitly naming alternatives ('Use this instead of convert_to_md', 'Use convert_to_html or convert_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?

Explicitly states when to use ('when you need formatting-free content') versus alternatives, provides concrete use cases ('for indexing, search, or clipboard'), and names specific sibling tools to use instead for different outcomes.

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 critical side effects beyond annotations: file system mutations ('writes the XLSX binary to disk', 'creates parent directories, overwrites existing files'). Explains dual return modes (disk write vs JSON binary-guidance object) and edge case behavior ('If the Markdown contains no tables, produces an empty workbook'). Annotations confirm idempotency and non-destructive nature; description adds implementation details.

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

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

Every sentence is load-bearing: purpose → parsing mechanics → edge cases → binary nature warning → side effects → return schema → sibling differentiation. No tautology or repetition of schema/annotation data. Information-dense structure guides agent through decision tree efficiently.

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

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

Absence of output schema is fully compensated by detailed return value documentation covering both branches (output_path provided vs omitted). Binary format complexities, side effects, and sibling ecosystem context are comprehensively addressed for a conversion utility.

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%, establishing baseline 3. Description adds critical operational semantics: warns that output_path 'should almost always be provided' for binary formats and details the two-stage workflow (preview then save) when omitted. Elevates understanding beyond raw schema 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?

Opens with specific verb-noun sequence ('Convert Markdown tables to... XLSX spreadsheet'), clearly identifies input resource (Markdown pipe-tables) and output format. Explicitly distinguishes from siblings convert_to_csv and convert_to_json by prescribing specific use cases ('lightweight plain-text' vs 'full Excel file with formatting').

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 ('when you need a full Excel file with formatting') and provides named alternatives with precise differentiators ('Prefer convert_to_csv for lightweight plain-text...or convert_to_json for structured programmatic access'). Also clarifies output_path as mandatory for binary workflows ('almost always be provided').

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

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

Rich disclosure beyond annotations: details exact XML element structure produced (<section>, <heading>, etc.), declares <?xml?> declaration, clarifies dual return behavior (string vs JSON object based on output_path), and explicitly documents side effects including parent directory creation and file overwrite 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?

Well-structured with logical flow: purpose → technical details → side effects → returns → usage guidance. Front-loaded with core function. Slightly dense but every sentence provides actionable information; no redundant repetition of schema details.

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

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

Comprehensive for a dual-mode conversion tool. Despite no output schema, description fully documents both return variants (XML string vs JSON summary object). File system behavior (directory creation, overwrite) is explicitly addressed. Sibling alternatives coverage is 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?

While schema coverage is 100%, description adds crucial contextual usage: explains that 'title' parameter becomes the root XML element name, and clarifies that 'output_path' presence triggers file write mode with JSON metadata return vs direct string return. Enhances agent understanding of parameter interactions.

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?

Excellent specificity: 'Convert Markdown to an XML document' provides clear verb+resource. Critically distinguishes from 20+ sibling conversion tools by naming specific alternatives (convert_to_json, convert_to_html, convert_to_csv) and their use cases.

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 guidance ('Use this for XML-based data interchange or when downstream systems require XML input') and explicit when-not-to-use with named alternatives. Clear distinction from siblings based on output format requirements.

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 declare read-only/idempotent nature. Description adds valuable output structure details beyond annotations: JSON array format with specific fields (language, code content, start/end line numbers) and the 'all' scope indicator.

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

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

Two sentences with zero waste: first sentence covers function + return format, second covers use case. Information-dense and front-loaded.

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

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

No output schema exists, but description fully compensates by detailing the JSON array structure and constituent fields (language, line numbers). Complete for a single-parameter extraction tool with good 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 coverage is 100% ('The Markdown text to extract code blocks from'). Description references 'Markdown document' but does not supplement schema with additional format constraints, validation rules, or examples. Baseline 3 appropriate for high-coverage schemas.

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

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

Specific verb 'Extract' with clear resource 'code blocks' and scope 'from a Markdown document'. Distinctly positioned against sibling 'extract_structure' (general structure) and 'extract_links' (URLs) by targeting fenced code blocks specifically.

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 concrete usage contexts ('LLM responses or documentation') indicating when to use. Lacks explicit exclusions or sibling comparisons (e.g., vs extract_structure), but clear enough for selection.

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?

While annotations declare readOnlyHint=true and idempotentHint=true, the description adds crucial output structure documentation ('Returns a JSON array with link text, URL, line number, and type') which compensates for the missing output schema. No contradictions with annotations.

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

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

Two well-structured sentences with zero waste: first sentence covers action and output format, second covers use cases. Front-loaded with the core operation. Every word earns its place.

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

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

For a single-parameter extraction tool, the description is fully complete. It compensates for the lack of output schema by detailing the JSON return structure. Combined with comprehensive annotations, no additional information is needed for correct invocation.

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

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

Schema coverage is 100% for the single 'markdown' parameter, which is adequately described in the schema as 'The Markdown text to extract links from.' The description references 'Markdown document' reinforcing the parameter purpose but does not add additional syntax constraints or format details beyond the schema.

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

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

Description uses specific verb 'Extract' with clear resource 'links and images' and scope 'from a Markdown document.' It clearly distinguishes from sibling conversion tools (convert_*) and other extraction tools (extract_code_blocks, extract_structure) by specifying exactly what content is targeted.

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 concrete use cases ('Useful for link checking, SEO analysis, or extracting references') indicating when to invoke the tool. Lacks explicit 'when not to use' guidance or named alternatives for extraction tasks, but the positive examples are specific enough to guide selection.

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?

Leverages annotations (readOnlyHint, destructiveHint, idempotentHint) effectively while adding valuable output contract details. Describes exactly what the JSON contains (statistics, heading outline, code block summary with language/line counts, link summary), clarifying what 'structure' means operationally. No contradictions 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?

Three well-constructed sentences: purpose declaration, detailed output specification, and conceptual summary. Zero redundancy—every sentence advances understanding of tool capabilities. Front-loaded with the core action.

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 no output schema, description comprehensively details return value structure (JSON components: statistics, headings, code blocks with metadata, links with counts). Combined with rich annotations covering behavioral traits, provides complete contractual information needed for agent invocation.

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

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

Schema coverage is 100% with clear parameter description ('The Markdown text to extract structure from'). Description references 'Markdown document' but adds no additional semantic constraints (size limits, encoding requirements, valid markdown prerequisites) beyond what the schema already provides. Baseline 3 appropriate given complete 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?

Excellent specificity: 'Extract' (verb) + 'full structure of a Markdown document' (resource+scope). Distinguishes clearly from siblings like extract_code_blocks and extract_links by emphasizing 'full structure' versus specific elements, and from convert_to_* tools by focusing on structural analysis rather than format transformation.

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 implied usage through output description ('bird's-eye view of document architecture'), indicating this is for structural overview. However, lacks explicit when/when-not guidance or comparisons to siblings like analyze_document or the more specific extraction tools.

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

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

Beyond annotations (readOnlyHint, destructiveHint), the description adds valuable behavioral context: output is a string not file, includes KaTeX CSS CDN link dependency, specifies exact return format (<!DOCTYPE html>…</html>), and confirms side effects none. Does not mention idempotency from annotations, but coverage is strong 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?

Ten sentences cover purpose, features, I/O behavior, side effects, return values, parameter specifics, and sibling distinctions. While dense, every sentence earns its place with no redundancy, following a logical what→how→when→alternatives structure.

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 for a conversion tool with many siblings. Compensates for missing output schema by explicitly describing the returned HTML string structure. Covers behavioral traits, parameters, and clear differentiation from 20+ sibling conversion tools.

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 description coverage, the baseline is 3. The description adds minor supplemental context about the 'title' parameter's effect on the HTML <head> section, but the schema already fully documents both parameters' purposes and types.

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

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

The description uses a specific verb ('Generate') and clear resource ('complete, self-contained HTML document'). It explicitly distinguishes from sibling 'convert_to_html' by emphasizing 'returns the HTML string directly — no file is written to disk' versus file output.

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: 'Use this when you need styled HTML output returned as a string' and clear alternatives: 'Prefer convert_to_html when you need to write the HTML to a file' and 'Prefer convert_to_pdf or convert_to_image for non-HTML visual output formats.'

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

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

Adds valuable behavioral details not present in annotations: output format specifics ('Markdown-formatted TOC with indented links') and special handling logic ('Handles duplicate heading slugs'). Complements the readOnly/idempotent annotations by describing the transformation behavior without contradicting 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?

Four tightly constructed sentences: purpose declaration, output specification, behavioral note on duplicates, and parameter guidance. Front-loaded with essential information; no filler content. Excellent information density.

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?

Compensates well for missing output schema by explicitly describing return format. Complete coverage of the two parameters with 100% schema coverage. Only gap is lack of explicit sibling differentiation given the server's large collection of document processing tools.

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 has 100% description coverage setting baseline at 3. Description adds redundant but clarifying phrasing for max_depth ('deepest heading level'), reinforcing the schema's intent without adding substantial new semantic information about parameter usage or constraints.

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 uses specific verb 'Generate' with clear resource 'Table of Contents' and source 'Markdown headings'. Effectively distinguishes from sibling convert/extract tools by specifying its unique purpose (TOC generation with links).

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 clear context about what the tool produces (indented links TOC) and input requirements (Markdown headings), but lacks explicit guidance on when to choose this over similar siblings like extract_structure. Usage is implied but not explicitly contrasted with 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?

Annotations declare idempotency and non-destructive nature; the description adds crucial behavioral specifics: exact formatting mutations (ATX headers, '-' list markers, fenced code blocks), file I/O side effects (directory creation, overwriting), and conditional return value schemas (string vs JSON object). This significantly augments the annotation-level safety profile with operational details.

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

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

The description is well-structured with logical flow: purpose → specific behaviors → side effects → returns → usage guidance → alternatives → exclusions. Every sentence provides unique value (normalization specifics, I/O behavior, return types, sibling distinctions). Slightly dense but efficiently packed with necessary information for a dual-mode tool (in-memory vs file-write).

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?

Excellently compensates for the missing output schema by explicitly documenting both return variants (harmonized string vs JSON summary with specific fields). Covers input requirements (GitHub-Flavored Markdown, KaTeX), side effects, and error-prone conditions (overwriting) ensuring the agent has complete operational context.

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

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

With 100% schema description coverage, the baseline is 3 per rubric. While the description elaborates on output_path behavior in the side-effects section (linking it to file writes vs string returns), the schema already documents the parameter purposes adequately. The description does not need to compensate for schema gaps.

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 action ('Standardize and normalize Markdown syntax') and scope ('without changing the document's meaning'). It immediately distinguishes itself from siblings by stating 'Not suitable for converting Markdown to other formats — use the convert_to_* tools instead' and explicitly comparing to convert_to_md, satisfying the requirement for sibling differentiation.

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 ('when you need to clean up inconsistent Markdown formatting before further processing'), explicit preference ('Prefer convert_to_md with harmonize=true if you also need to save the result'), and clear exclusions (not for converting to other formats). This covers all dimensions of 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?

While annotations declare idempotent/non-destructive hints, the description adds valuable behavioral context by enumerating specific HTML elements that are preserved (tables, code blocks, inline formatting), helping agents predict conversion fidelity. It aligns with annotations (idempotent 'round-trip' concept).

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

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

Four sentences with clear information hierarchy: purpose → capability details → use cases. The 'round-trip import' phrase is slightly jargon-heavy but overall structure is efficient with minimal 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?

Adequately covers the conversion capability and supported syntax, but lacks explicit documentation of return value behavior (file path vs string) in the description text itself, relying entirely on the parameter schema. No contradictions with annotations detected.

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?

Input schema has 100% description coverage, establishing a baseline of 3. The description focuses on functional capabilities rather than clarifying parameter semantics (e.g., html fragment vs document), which is acceptable given the comprehensive 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 'HTML to Markdown' with specific supported elements (headings, tables, lists, etc.), providing concrete scope. However, it fails to distinguish from sibling 'convert_to_md', which likely performs a similar function.

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

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

Provides implicit usage guidance through concrete examples ('importing web content', 'converting HTML emails'), helping agents identify relevant contexts. However, it lacks explicit when-not-to-use guidance or comparison with the generic 'convert_to_md' alternative.

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?

Excellent disclosure beyond annotations: details return structure (JSON array with line, column, severity, rule name, message, fixable flag) and enumerates specific lint rules checked (heading spaces, trailing whitespace, etc.). Matches readOnlyHint/destructiveHint annotations with 'report issues' framing.

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

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

Two sentences, zero waste. First sentence establishes purpose and return format; second enumerates specific checks. Perfectly front-loaded.

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

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

No output schema exists, but description comprehensively documents return structure (array of issue objects with specific fields) and behavior. Combined with rich annotations (readOnly, idempotent), description provides complete context for invocation.

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

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

Schema coverage is 100% ('markdown' parameter fully described), meeting baseline. Description adds no additional parameter semantics, but schema carries full burden adequately.

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 specific verb ('Lint') + resource ('Markdown') plus scope ('report issues'). Distinguished from conversion siblings (convert_to_*) and extraction siblings (extract_*) by focusing on validation/reporting.

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 implied usage through 'report issues' language, indicating read-only analysis. However, lacks explicit when-to-use guidance vs. close sibling 'repair_markdown' (which presumably fixes issues) or when to choose this over 'analyze_document'.

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 establish idempotency and non-destructive traits. The description adds valuable behavioral specifics beyond annotations by detailing exactly what constitutes 'repair' (mismatched table columns, missing heading spaces, etc.), clarifying the transformation scope without contradicting the 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?

Two dense sentences with zero waste. The first establishes purpose and context; the second enumerates specific fixes. Every clause earns its place, and the information is appropriately front-loaded.

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 100% schema coverage, idempotent annotations, and clear behavioral description, the definition is sufficiently complete. The lack of an output schema is partially mitigated by the parameter descriptions explaining the dual return modes (direct string vs. file write), though a brief summary of the return structure in the description would be ideal.

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%, establishing a baseline of 3. While the description implies the input content domain ('broken Markdown' with specific defects), it does not explicitly elaborate on parameter syntax, format constraints, or the optional output_path behaviors beyond what the schema already documents.

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

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

The description uses a specific verb ('Repair') with a clear resource ('Markdown') and explicitly scopes the functionality to 'LLM output or copy-paste.' It comprehensively lists specific defects handled (unclosed code fences, broken tables, stray emphasis, etc.), distinguishing it from generic conversion 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?

It provides contextual usage hints by specifying the source ('LLM output or copy-paste'), implying when the tool is needed. However, it lacks explicit guidance distinguishing it from close siblings like 'lint_markdown' or 'harmonize_markdown' regarding when to repair versus lint or standardize.

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