MarkItDown by pagespool

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

Annotations only declare readOnlyHint and openWorldHint; the description adds the substantive behavioral facts an agent needs: the 8 MB ceiling, the anonymous rate limit without an API key, a cost of 1 credit per call, and the important caveat that PDFs return only text-layer content with no headings and no OCR. That PDF limitation materially affects whether the tool fits a task and is not recoverable from any structured field.

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?

Purpose is front-loaded in the first clause, then input modes, supported types, output shape, limitations, and cost in a compact sequence of short paragraphs. The 'Returns `markdown` and `meta`' sentence is mildly redundant given a real output schema exists, which keeps it just short of full marks.

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 a nested `file` object and two alternative input channels, the description covers size limits, accepted formats, the extension-drives-parsing rule, output fields, the PDF text-layer caveat, auth/rate-limit behavior, and cost. With an output schema present, nothing an agent needs in order to call this correctly is missing.

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 baseline is 3, but the description adds real meaning beyond the schema: it frames `file` and `content_base64` as mutually alternative input channels, and explains that `filename`'s extension is what actually decides how the bytes are parsed. The 8 MB limit is stated as pre-encoding for the base64 path, which is a useful nuance the schema property description also carries.

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 (convert a document to Markdown) plus the engine (MarkItDown), and enumerates the supported extensions (.pdf, .docx, .pptx, .xlsx, .html, .htm, .txt) and the 8 MB cap. An agent knows exactly what this does and what inputs are valid without opening the schema.

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 concrete routing guidance for input modes: pass the file as base64 in `content_base64` or as a download link in `file`, plus the required `filename`. It also notes the tool works without an API key at the anonymous rate limit. There is no explicit when-not-to-use guidance, but with no sibling tools there is nothing to disambiguate against.

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