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

With no annotations, the description carries the transparency burden. It discloses the key side effect ('Writes a .md file under MARKITDOWN_OUTDIR') and output characteristics ('pure Markdown'), but it doesn't mention default overwrite behavior, potential errors, or side effects of openInSublime beyond what the schema says. The Sublime-specific note adds useful context but leaves behavioral gaps.

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

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

The description is three sentences with the primary action front-loaded. The second and third sentences explain the output location and format purpose without excessive fluff. Minor redundancy exists between 'Writes a .md file' and the outputPath/MARKITDOWN_OUTDIR param, but overall it is efficient.

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

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

The core scenario (converting text or file to Markdown) is covered, but the description lacks guidance on sibling tool selection, no output schema means return behavior is never explained, and overwrite defaults are only in schema. For a tool with 7 optional parameters and no annotations, this is adequate but not complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats 'or outputPath' and mentions MARKITDOWN_OUTDIR, but it does not add meaningful semantic value beyond the well-documented parameters. No compensation is needed because the schema already carries the parameter explanations.

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

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

The description clearly states the verb ('Convert') and resource ('plain text content or a file') into a specific output ('properly formatted Wiki-ready Markdown'), making the core purpose unambiguous. It does not explicitly distinguish itself from siblings like md_convert_batch, so it falls short of a 5.

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 this is for converting a single content string or file to Markdown, but it gives no explicit guidance on when to choose this over md_convert_batch, md_format, or md_preview. The 'when not using inputPath' note inside the schema adds some context, but the main description lacks direct alternative routing.

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

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

With no annotations provided, the description must carry the burden of explaining behavior. It says files are converted and that formatting matches md_convert, but it does not disclose whether original files are modified, whether existing output files are overwritten, what naming convention is used, or what happens when conversion fails. This is a significant gap for a tool that creates or modifies files.

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 short sentences with no filler. The main action and default behavior are front-loaded, and the reference to md_convert is a compact way to inherit formatting details without duplication.

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 good parameter schema coverage, the tool has no annotations and no output schema, so the description needs to explain what a successful conversion produces, whether the operation is destructive, and how output files are named. The current description leaves these operational details to inference, making it incomplete for safe and 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?

The input schema documents all four parameters with clear descriptions, so the schema does the heavy lifting. The description adds the default *.txt context but does not add meaning beyond the schema, which matches the baseline for full schema coverage.

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

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

The description states a clear action: convert all matching files in a folder to Markdown, with a default extension filter and an explicit reference to md_convert's formatting rules. This distinguishes the batch tool from the single-file sibling md_convert and makes its scope immediately understandable.

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

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

The description clearly implies this tool is for batch conversion of multiple files in a folder, in contrast to md_convert, and it signals shared behavior with md_convert. However, it never explicitly says 'use md_convert for a single file' or gives exclusion criteria, so the guidance is clear but not fully explicit.

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

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

No annotations are provided, so the description carries the burden of explaining behavior. It discloses that the tool modifies only formatting details, explicitly promises not to remove content, and scopes the operation to specific transformations. It does not mention the default overwrite behavior, but the schema covers that.

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

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

Two compact sentences deliver the action, the scope, the safety guarantee, and the rationale with no redundant wording. The most important information is 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?

For a simple two-parameter formatting tool with full schema coverage, the description is nearly complete. It covers purpose, scope, and behavioral constraints. It lacks explicit mention of return values or error behavior, but no output schema exists and the operation is straightforward for an agent to infer.

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

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

Schema description coverage is 100%, so the input schema already fully documents both parameters. The description adds no parameter-specific guidance beyond the overall tool purpose, which meets the baseline expectation but does not exceed it.

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

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

The description begins with a specific verb and resource: 'Normalize an existing .md file.' It names the exact transformations (fence spacing, blank lines around tables/headings) and explicitly states content is not removed, which clearly differentiates it from conversion, preview, style, and status siblings.

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

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

The rationale 'Keeps Wiki + Sublime preview consistency' provides clear context for when to use this tool. It does not explicitly name alternatives or state when not to use it, but the sibling list and the focus on formatting make the intended use reasonably apparent.

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

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

With no annotations, the description carries the behavioral burden. It does disclose that the tool mutates a specific settings file rather than merely reading information. However, it does not explain how existing settings are handled beyond the schema's force parameter, whether the operation is reversible, or what 'CSS + Copy JS' fully entails.

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

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

Two concise sentences with the main purpose and side effect stated directly. Slightly informal phrasing ('Wire', 'Copy JS') costs some clarity, but there is no wasted content.

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

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

For a simple one-parameter tool with a full schema, the description is mostly adequate. Still, it omits when this should be run relative to sibling tools and does not clarify what happens on repeated invocations or whether any user action is needed afterward.

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

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

Schema description coverage is 100%, and the only parameter (force) is already well documented in the schema with its default behavior. The description adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description states a clear action ('Wire'), the target resource (MarkdownPreview settings pointing to the styles/ folder), and the concrete effect ('Writes/updates Packages/User/MarkdownPreview.sublime-settings'). It is specific enough to distinguish installation from the sibling style-related operations.

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

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

No guidance is given about when to run this tool rather than md_styles or md_preview, and no alternatives or exclusions are mentioned. The intended use is only implied by the name and description.

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

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

With no annotations, the description carries the full burden. It discloses the main behavior: opening a file in Sublime Text and using preview-related features. However, it does not mention prerequisites such as Sublime Text being installed, whether the tool blocks or returns immediately, or whether it modifies or creates any files.

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 short and front-loaded with the primary action. The second sentence provides useful preview context but is somewhat cryptic, especially the phrase 'styles/ CSS + Copy Markdown / Copy Formatted.' Still, there is no wasted padding.

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 tool with no output schema, this is reasonably complete for basic invocation. However, it lacks usage routing relative to sibling tools and does not disclose side effects or environment prerequisites, leaving some ambiguity for an agent deciding when and how to call it.

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

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

Schema description coverage is 100%, so the only parameter (path) is already documented with its relative-to MARKITDOWN_OUTDIR / WORKDIR semantics. The tool description adds no additional parameter detail, which is acceptable given the 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?

The description clearly states the core action: opening a Markdown file in Sublime Text, and adds detail about preview behavior using package styles/CSS and copy actions. It is specific enough to distinguish from conversion/formatting siblings, though it does not explicitly contrast with them.

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

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

The description implies the tool is used for opening/previewing Markdown files, but it gives no explicit when-to-use guidance and no indication of when to prefer alternatives like md_convert, md_format, or md_styles. An agent must infer the appropriate context from the tool name and first sentence.

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

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

The verb 'Check' plus the enumerated items signals a read-only diagnostic behavior, which is useful given there are no annotations. However, the description does not disclose what the tool returns, whether it performs any validation steps, or what happens if MarkItDown is unavailable or paths are missing.

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

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

The description is a single compact sentence that front-loads the action and then lists the checked items in a scannable sequence. Every word contributes information, with no filler or redundancy.

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

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

For a zero-parameter, no-output-schema status tool, the description is usable for invoking the tool, but it omits what the result will look like and what 'check' means operationally. A brief statement about return values or explicit side-effect-free behavior would make it more complete, especially without 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?

The input schema has zero parameters, so there is no parameter semantics for the description to add; the baseline of 4 applies. No parameter documentation is needed here.

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 ('Check') applied to the MarkItDown MCP resource and enumerates the exact status items: workdir, outdir, package-local styles, and optional Sublime path. This gives concrete scope and helps distinguish it from operational siblings like md_convert and md_styles, though it does not explicitly label itself as a status/diagnostic tool.

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

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

There is no guidance about when to use this tool versus alternatives, no conditions, and no mention of when not to use it. An agent must infer from the name and sibling list that this is the environment-status checker rather than a style-manipulation or conversion tool.

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

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

With no annotations, the description carries the behavioral burden. It states the tool reports paths and whether they exist, implying a read-only diagnostic operation with no mutation. This is explicit enough for a simple no-parameter tool, though it does not disclose the return format.

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

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

One sentence, immediately front-loaded with the verb 'Report', and it packs the exact file paths plus the existence-check behavior. Every word earns its place; no filler or redundancy.

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

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

For a zero-parameter read-only diagnostic, the description gives the essential information: what is reported and the specific paths. It does not describe the output format or when to use it, but the simplicity of the tool keeps these gaps minor.

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

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

The input schema has zero parameters, so there is nothing to document. The description covers all relevant inputs by having none, matching the baseline for a zero-parameter tool.

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 ('Report') and names the exact resource: package-local style/JS paths, including the concrete file paths. This clearly distinguishes it from siblings like md_install_styles (which implies installation) and md_status (which suggests a general status check).

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention md_install_styles, md_status, or any condition that would select this tool over a sibling. The intended use case must be inferred entirely from the name and description.

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