AgentMD

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

No annotations are provided, so the description carries the full burden. It discloses several behavioral traits: supports reading only part of a large document, PDF page ranges, heading outline, single section, token cap; pages are ignored with a warning for non-PDF formats; section matching is case-insensitive with exact/prefix/substring precedence; truncated output starts with a '> Truncated: ~X of ~Y tokens' line. This is rich behavioral disclosure. It doesn't mention error handling for invalid base64 or unsupported formats, but the disclosed behaviors are substantial.

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 two sentences, front-loaded with the core purpose and input method, then a compact list of partial-read capabilities. Every sentence earns its place. The schema's parameter descriptions carry the detailed semantics, keeping the main description lean. No fluff or repetition.

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

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

For a 6-parameter tool with no output schema and no annotations, the description plus schema covers the key usage workflow, partial-read modes, and truncation behavior. The main gap is that the description doesn't state what the output looks like for a successful full conversion (e.g., does it return just markdown or a wrapper object?), and there's no mention of error cases like invalid base64 or unsupported file types. However, the schema's mode description gives a concrete example of the outline output format, and the truncation line is documented. This is nearly complete for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the overall workflow (outline first, then section fetch) and by clarifying the truncation behavior and the 'narrow with pages or section' guidance. The schema already documents each parameter well, including the outline format and section matching precedence. The description's added value is moderate but meaningful, so a 4 is appropriate.

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

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

The description states a specific verb ('Convert'), the resource ('a document you already have'), the input formats (PDF, DOCX, HTML, plain text), and the output ('clean, LLM-ready markdown'). It also distinguishes itself from the sibling convert_url_to_markdown by emphasizing 'you already have' (local file contents passed as base64) rather than a URL. This is a clear, specific purpose statement.

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

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

The description explicitly says to pass file contents as base64 and gives concrete usage guidance for large documents: call with mode 'outline' first, then fetch only what you need with section '#3' or a heading title. The schema's mode parameter description reinforces this workflow. It also tells users to narrow with pages or section rather than raising maxTokens. This is explicit when-to-use guidance with a clear strategy.

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 that web pages are stripped to main content, tables are preserved, page ranges are ignored for non-PDFs, section is ignored in outline mode, and truncation adds a marker line. These are specific behavioral traits beyond the schema, though error handling or invalid-URL behavior is not covered.

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, each adding distinct value: core function, extraction behavior, and partial-reading options. It is front-loaded and contains no filler words or redundant phrasing.

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

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

For a tool with 5 parameters and no output schema, the description explains the main behaviors and partial-reading workflow comprehensively. It does not cover error handling or edge cases like unreachable URLs, but the essential usage and behavior are clear enough for an agent to call it correctly.

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

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

The schema already provides 100% parameter descriptions, including mode enum, page range format, section matching rules, and maxTokens truncation behavior. The tool description adds a valuable workflow suggestion (outline-first pattern) that supplements the parameter semantics and guides effective usage.

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 action (fetch a URL and convert to markdown) and resource (URL) with a specific output format. It distinguishes from the sibling by emphasizing URL-based fetching, and adds detail about content extraction and table preservation, making the purpose unambiguous.

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 concrete guidance on handling large documents (call with mode 'outline' first, then use section) and advises narrowing with pages or section instead of raising maxTokens. It does not explicitly mention the sibling tool as an alternative, but the URL focus strongly implies the tool's domain.

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