Skip to main content
Glama
djrobson5

agentmd-mcp

by djrobson5
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

Convert document bytes to markdown

convert_document_to_markdown
Read-only

Convert base64-encoded document bytes into clean, LLM-ready markdown. Use when bytes come from uploads or memory, not a local file or URL. Supports PDF, DOCX, HTML, Markdown, plain text.

Instructions

Converts base64-encoded document bytes that you already hold into clean, LLM-ready markdown, without reading a file or fetching a URL. Use this instead of convert_file_to_markdown when the bytes came from somewhere other than this machine's filesystem (an upload, an earlier tool result, memory), and instead of convert_url_to_markdown when there is no fetchable link to the source. Returns one markdown text block: the detected title as a leading # <title> line when one is found, a > Warnings: ... blockquote line when the converter reports warnings, and tables preserved as GFM. Supported formats are PDF, DOCX, HTML, Markdown, and plain text, up to 25 MB per document — base64 inflates the payload by about a third, so prefer convert_file_to_markdown or convert_url_to_markdown for large files — and PDFs are text-extraction only, so scanned or image-only PDFs yield little or no text (OCR is not available yet). Requires AGENTMD_API_KEY; on a 401, a network failure, malformed base64, or an unsupported format it returns an isError result whose text explains what went wrong. Each successful call consumes one conversion from the account quota. To read only part of a large document, use the optional pages (PDF page ranges), mode: 'outline' then section, and maxTokens parameters instead of pulling the whole thing into context.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modeNo"full" (default) returns the document body. "outline" returns just the heading tree — each line is `- [#3] Heading text (~120 tokens)`. For a long document, call with mode: 'outline' first, then fetch only what you need with section: '#3' or a heading title.
pagesNoPDFs only: 1-indexed, inclusive page ranges to convert, e.g. "1-3,5,8-" (an open-ended range runs to the last page). Ignored with a warning for non-PDF formats.
base64YesThe document's full contents encoded as standard base64 (RFC 4648: A-Z a-z 0-9 + / with = padding). Pass the encoded string on its own — no `data:` URI prefix, no media type, no surrounding quotes.
sectionNoReturn only one section: either "#<n>" using the index from a mode: 'outline' call (e.g. '#3'), or the heading text itself (case-insensitive; exact match wins, then prefix, then substring). Ignored when mode is 'outline'.
filenameNoOriginal filename including its extension, e.g. report.pdf or notes.docx. Used for format detection when the bytes alone are ambiguous (HTML vs. Markdown vs. plain text) and to seed the document title. Optional, but supplying it makes detection markedly more reliable.
maxTokensNoCap the returned markdown at roughly this many tokens, cutting at a paragraph boundary. When the output is cut, the result starts with a `> Truncated: ~X of ~Y tokens` line — narrow with pages or section rather than raising this.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.1.4
    • addedInput schema / properties / maxTokens
      Added value: +{
+  "description": "Cap the returned markdown at roughly this many tokens, cutting at a paragraph boundary. When the output is cut, the result starts with a `> Truncated: ~X of ~Y tokens` line — narrow with pages or section rather than raising this.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}
    • addedInput schema / properties / mode
      Added value: +{
+  "description": "\"full\" (default) returns the document body. \"outline\" returns just the heading tree — each line is `- [#3] Heading text (~120 tokens)`. For a long document, call with mode: 'outline' first, then fetch only what you need with section: '#3' or a heading title.",
+  "enum": [
+    "full",
+    "outline"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / pages
      Added value: +{
+  "description": "PDFs only: 1-indexed, inclusive page ranges to convert, e.g. \"1-3,5,8-\" (an open-ended range runs to the last page). Ignored with a warning for non-PDF formats.",
+  "type": "string"
+}
    • addedInput schema / properties / section
      Added value: +{
+  "description": "Return only one section: either \"#<n>\" using the index from a mode: 'outline' call (e.g. '#3'), or the heading text itself (case-insensitive; exact match wins, then prefix, then substring). Ignored when mode is 'outline'.",
+  "type": "string"
+}
  2. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: PDFs are text-extraction only with no OCR, base64 inflates payload by a third, each successful call consumes quota, requires AGENTMD_API_KEY, and error conditions (401, network failure, malformed base64, unsupported format) return an isError result. It also discloses the return format (title line, warnings blockquote, GFM tables). The only minor gap is not detailing pagination or rate-limit specifics, but the description carries far more than the annotations require.

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

Conciseness4/5

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

The description is dense but every sentence earns its place: purpose, sibling routing, format/limits, error behavior, quota, and partial-read strategy. It is front-loaded with the core purpose and the most important caveats (base64 inflation, PDF text-only) before the error and quota details. It is long, but the tool is complex (6 params, 2 siblings, multiple formats, error modes), so the length is justified. Slightly tighter grouping of the error/quota sentence would push it to 5.

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

Completeness5/5

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

For a tool with 6 parameters, 2 siblings, no output schema, and multiple behavioral caveats, the description covers everything an agent needs to call it correctly: when to use it, what formats are supported, size limits, error behavior, quota consumption, return format, and a strategy for partial reads. The absence of an output schema is compensated by the description explicitly stating the return shape (title line, warnings blockquote, GFM tables, truncation line). Nothing critical is missing.

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

Parameters4/5

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

Schema description coverage is 100%, so the schema already documents all six parameters thoroughly. The description adds value by explaining the strategic relationship between parameters (use mode:'outline' first, then section; narrow with pages or section rather than raising maxTokens) and by warning that pages is ignored with a warning for non-PDFs. It doesn't restate the schema; it layers usage strategy on top. A 4 is warranted because the description meaningfully enriches parameter understanding beyond the schema.

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

Purpose5/5

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

The description opens with a specific verb ('Converts'), a precise resource ('base64-encoded document bytes that you already hold'), and an explicit outcome ('into clean, LLM-ready markdown'). It immediately distinguishes itself from both siblings by naming them and stating the exact condition that selects this tool over them. This is a model of purpose clarity.

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

Usage Guidelines5/5

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

The description explicitly says when to use this tool instead of convert_file_to_markdown (bytes came from somewhere other than this machine's filesystem) and instead of convert_url_to_markdown (no fetchable link). It also gives a concrete alternative for large files (prefer the siblings because base64 inflates payload by ~1/3) and for partial reads (use pages, mode:'outline', section, maxTokens). This is comprehensive routing guidance.

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

Deploy Server

Other Tools