[BUG] AxDocumentParser silently fails on documents exceeding 25k token limit

[dirkenglund]

Description

AxDocumentParser.parse_pdf_to_md has a ~25k token limit. When a PDF with many embedded images exceeds this limit, the tool either truncates silently or returns an error without guidance on how to work around it.

Reproduction

1. Provide a research paper PDF with 10+ figures (typically 30-50 pages)
2. Call parse_pdf_to_md
3. Response is truncated or fails with a token limit error

Expected behavior

• Clear error message indicating the document exceeds the token limit
• Suggestion to use page ranges or section filtering
• Ideally: support for a pages parameter (e.g., pages="1-10") to parse incrementally
• Or: return a summary/TOC first, then allow targeted extraction

Actual behavior

Large documents with images exceed the 25k token limit. The failure mode is unclear — sometimes truncation, sometimes an error.

Suggested improvements

1. Pagination support: Accept page_range parameter to process documents in chunks
2. Graceful degradation: If over limit, return what fits + a continuation token
3. Size estimation: Before processing, return estimated token count so the caller can decide how to chunk
4. Image handling: Option to skip embedded images (which consume most tokens) and return text + equation content only

Workaround

Check file size before calling. For large documents, use alternative PDF parsers (e.g., Docling) and only use AxDocumentParser for targeted sections.

Environment

• ax-mcp (MCP server, latest as of 2026-03-29)
• PDFs ranging from 5-50 pages with embedded figures