MD2Doc

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

Annotations already declare readOnlyHint=false and openWorldHint=false; the description adds useful extra behavior — the download URL lives only 10 minutes and the upload id is single-use. It does not mention failure modes (invalid markdown, expired id) or what happens when both inputs are supplied.

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, no filler: the primary behavior and its return value come first, the large-file escape hatch second. Every sentence earns its place.

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

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

No output schema exists, and the description covers the return value (download URL, TTL) and the two input paths. It is a bit thin on error/edge behavior for a conversion tool with zero required parameters, where an agent could easily call it with no inputs.

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

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

Schema coverage is 100%, so the baseline is 3, but the description gives the concrete host URL for the upload endpoint that the schema only references as a path. It also documents the either/or relationship between markdown and markdown_upload_id, though it says nothing about filename defaults 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?

Names a specific verb and resource plus the output format ('Converts markdown to a Microsoft Word (.docx) file'), which inherently separates it from convert_to_html and convert_to_pdf. It never explicitly contrasts with those siblings, so it stops 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?

Gives a concrete routing rule for the large-document case: POST to the upload endpoint and pass the returned id instead of inline markdown. It does not state when to prefer this over convert_to_pdf/html or preview_markdown, so guidance is strong but incomplete on 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 only declare that this is a non-destructive, non-open-world operation, so the description carries the useful behavioral load: the output is self-contained with embedded CSS, the download URL expires in 10 minutes, and the upload id is single-use. What is missing is failure behavior (invalid markdown, expired upload id) and any content or size limits beyond 'large 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 sentences, both front-loaded with the highest-value facts: what is produced and what comes back first, then the escape hatch for large inputs. No filler and no repetition of the title.

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

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

With no output schema, the description usefully explains the return value (a 10-minute download URL) and the large-file path, which is enough for an agent to call it correctly. The one remaining gap is that the tool has zero required parameters and the description never states that at least one of markdown or markdown_upload_id must be supplied.

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, but the description adds the operational workflow behind markdown_upload_id (POST to a stated URL, then pass the returned id) and reinforces the either/or relationship between markdown and markdown_upload_id. It stops short of restating the filename default, which the schema already handles.

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

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

The description states a specific verb and resource ('Converts markdown') and goes further to specify the output shape: a standalone styled HTML document with embedded CSS plus a time-limited download URL. Sibling differentiation is implicit but unambiguous, since convert_to_docx and convert_to_pdf target other formats and preview_markdown produces a preview rather than a downloadable document.

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 gives actionable routing for one real branch: large inputs should go through the upload endpoint and pass back the id, which is exactly the decision an agent would otherwise get wrong. It does not say when to prefer a sibling converter (PDF/DOCX) or when preview_markdown is the better choice for a quick look, so the guidance is clear but not complete.

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

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

Annotations already establish that this is a non-destructive write operation with no open-world access. The description adds meaningful behavioral context beyond that: headless Chrome rendering, fidelity to the on-site preview, a download URL valid for 10 minutes, and a separate upload path for large 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 sentences, both front-loaded: the core conversion result first, the large-file escape hatch second. No wasted language.

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

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

No output schema exists, but the description explains that the return value is a download URL valid for 10 minutes. It also covers the large-file input path; the remaining schema details are fully documented in the parameters.

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 all three parameters are already documented. The description adds the large-file workflow that explains why markdown_upload_id exists, but it largely restates the schema's upload endpoint reference rather than adding new semantics for filename or markdown.

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

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

States a specific verb and resource ('Converts markdown to a PDF') and adds distinguishing detail about the rendering engine and output URL. It implicitly separates itself from convert_to_docx and convert_to_html by naming the PDF target, but it does not explicitly contrast with those 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?

Provides a useful large-file workflow ('For large files, POST to ... and pass the returned id'), but gives no explicit guidance on when to choose this tool over convert_to_docx, convert_to_html, or preview_markdown. Usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the return value is an HTML string, and there is a size constraint with a documented out-of-band upload workaround, which an agent would not otherwise know.

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, front-loaded with what the tool does and what it returns, then the exception for large files. No filler and nothing repeated from structured fields.

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

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

With no output schema, the description correctly states the return type, and it handles the main operational wrinkle (large inputs via upload id). The remaining gap is sibling differentiation: an agent cannot tell from this text why preview_markdown exists alongside convert_to_html.

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

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

Schema coverage is 100%, so both parameters (markdown and markdown_upload_id, including the either/or rule and the single-use 10-minute expiry) are already fully documented in the schema. The description reinforces the upload id path but adds no semantics the schema lacks, 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?

States a specific verb and resource ('Converts markdown to HTML') plus the framing that the output shows how it will look as a Word document, so the agent knows what it gets back. However, it never distinguishes itself from the sibling convert_to_html, which on its face sounds like the same operation, leaving the agent to guess which one to pick.

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?

Usage is only implied by the word 'preview' and the Word-document framing; there is no explicit statement of when to use this over convert_to_docx or convert_to_html. The one concrete usage rule given is the large-file path (POST to /mcp/upload, then pass the id), which is genuinely helpful workflow guidance but covers only an edge case.

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