This server provides structured access to PDF specification documents (e.g., ISO 32000), enabling LLMs to navigate, search, and analyze PDF standards through the following tools:
List specifications (list_specs): Discover available PDF spec documents (up to 17, including ISO 32000-2, PDF/UA, TS documents, guides, and application notes) with metadata like titles, page counts, and categories. Filter by category (standard, ts, pdfua, guide, appnote).
Browse section hierarchy (get_structure): Retrieve the table of contents/section tree of any specification with configurable depth levels.
Read section content (get_section): Extract structured content (headings, paragraphs, lists, tables, notes) from a specific section by identifier (e.g., 7.3.4, Annex A).
Full-text search (search_spec): Search across a specification using keywords or phrases, returning matching sections with context snippets (up to 50 results).
Extract normative requirements (get_requirements): Identify ISO normative language (shall, shall not, should, should not, may) from a specific section or entire document.
Look up term definitions (get_definitions): Retrieve term definitions from Section 3 of a specification, with optional keyword filtering.
Extract tables (get_tables): Pull structured table data (headers, rows, captions) from a section, with multi-page table merging and specific table targeting by index.
Compare PDF versions (compare_versions): Diff section structures between PDF 1.7 (ISO 32000-1) and PDF 2.0 (ISO 32000-2), identifying matched, added, and removed sections.
An MCP (Model Context Protocol) server that provides structured access to ISO 32000 (PDF) specification documents. Enables LLMs to navigate, search, and analyze PDF specifications through well-defined tools.
This is a specification reference, not a rule engine.
It retrieves and structures the text of ISO 32000 — clauses, tables, definitions, and
shall/should/may requirements. It does not examine a PDF file, and it cannot tell
you whether a document conforms to anything. Conformance verdicts come from
pdf-verify-mcp
(validate_conformance / evaluate_policy).
The distinction matters because three different things get conflated:
declaration — a label the file wrote about itself ("I am PDF/A" in the metadata). Writing it is not evidence /
conformance — whether the file actually meets the standard. There is no way to prove it in full; you can only find where it breaks the rules /
validation — what a validator (veraPDF and the like) reports against the checks it implements. A pass means "this inspection did not fail", not "the file conforms to the standard".
Reading a shall here tells you what the standard requires — not whether your file meets it.
A search that returns nothing means "cannot answer", not "no such requirement."
ISO 19005 (PDF/A) and ETSI PAdES are outside this corpus; see list_specs → coverage.gaps.
Server | Does | Does not |
pdf-spec-mcp (this) | Search, retrieve and extract requirements from 17 PDF-related documents | Is not a rule engine. Does not define business rules, inspect PDF files, or validate schemas. ISO 19005 (PDF/A) is not part of the corpus |
Extract text / tables / structure tree / fonts / annotations / images / signature fields | Does not verify cryptography. Does not read the incremental-update history, does not map object IDs to coordinates, does not OCR | |
Create, page operations, tagging, forms, annotations, metadata, attachments, PDF/A-3b scaffolding | Does not sign. Does not make the file meet the standard — it can write a label, not conformance | |
Conformance validation (delegated to veraPDF), cryptographic signature verification, tamper detection, policy verdicts | Does not prove the file meets the standard (it can only find where it breaks the rules). Does not vouch for the signer's identity. Does not judge whether the content is true |
PDF specification files are NOT included in this package. You must obtain the PDF specification documents separately and place them in a local directory.
Download from: PDF Association — Sponsored Standards
See "Setup" for details.
Multi-spec support — Auto-discovers and manages up to 17 PDF-related documents (ISO 32000-2, PDF/UA, Tagged PDF guides, etc.)
Structured content extraction — Headings, paragraphs, lists, tables, and notes from any section
Full-text search — Keyword search with section-aware context snippets
Requirements extraction — Extracts normative language (shall / must / may) per ISO conventions
Definitions lookup — Term definitions from Section 3 (Definitions)
Table extraction — Multi-page table detection with header merging
Version comparison — Diff PDF 1.7 vs PDF 2.0 section structures
Bounded-concurrency processing — Parallel page processing for large documents
On-disk index cache — The search index and the full requirements scan are built once per PDF and reused by every later process (ISO 32000-2: ~6 s → ~0.2 s)
Related MCP server: MCP PDF Reader
graph LR
subgraph Client["MCP Client"]
LLM["LLM<br/>(Claude, etc.)"]
end
subgraph Server["PDF Spec MCP Server"]
direction TB
MCP["MCP Server<br/>index.ts"]
subgraph Tools["Tools Layer"]
direction LR
T1["list_specs"]
T2["get_structure"]
T3["get_section"]
T4["search_spec"]
T5["get_requirements"]
T6["get_definitions"]
T7["get_tables"]
T8["compare_versions"]
end
subgraph Services["Services Layer"]
direction LR
REG["Registry<br/>Auto-discovery"]
LOADER["Loader<br/>LRU Cache"]
SVC["PDFService<br/>Orchestration"]
CMP["CompareService<br/>Version Diff"]
end
subgraph Extractors["Extractors"]
direction LR
OUTLINE["OutlineResolver<br/>TOC & Section Index"]
CONTENT["ContentExtractor<br/>Structured Extraction"]
SEARCH["SearchIndex<br/>Full-text Search"]
REQ["RequirementExtractor"]
DEF["DefinitionExtractor"]
end
subgraph Utils["Utils"]
direction LR
CACHE["LRU Cache"]
CONC["Concurrency"]
VALID["Validation"]
end
end
subgraph PDFs["PDF Spec Files (obtained separately)"]
direction LR
PDF1["ISO 32000-2<br/>(PDF 2.0)"]
PDF2["ISO 32000-1<br/>(PDF 1.7)"]
PDF3["TS 32001–32005<br/>PDF/UA, etc."]
end
LLM <-->|"stdio / JSON-RPC"| MCP
MCP --> Tools
Tools --> Services
Services --> Extractors
Services --> Utils
LOADER --> PDFs
REG -->|"Filename pattern<br/>auto-discovery"| PDFs
style Client fill:#e8f4f8,stroke:#2196F3
style PDFs fill:#fff3e0,stroke:#FF9800
style Tools fill:#e8f5e9,stroke:#4CAF50
style Services fill:#f3e5f5,stroke:#9C27B0
style Extractors fill:#fce4ec,stroke:#E91E63
style Utils fill:#f5f5f5,stroke:#9E9E9ELayer | Responsibility |
Tools | MCP tool schema definitions & handlers (input validation) |
Services | Business logic (PDF registry, loader, orchestration) |
Extractors | Information extraction from PDFs (TOC, content, search, requirements, definitions) |
Utils | Shared utilities (cache, concurrency, validation) |
PDF specifications arecopyrighted documents and are not included in this package. Download them from the sources below and place them in a local directory.
Document | Source |
ISO 32000-2 (PDF 2.0) | |
ISO 32000-1 (PDF 1.7) | |
TS 32001–32005, PDF/UA, etc. |
All 17 files below are supported. You do not need all of them — place only the specs you need (at minimum, ISO 32000-2 is recommended).
pdf-specs/
│
│ ── Standards ─────────────────────────────
├── ISO_32000-2_sponsored_EC3.pdf # iso32000-2 : PDF 2.0 EC3 (recommended; falls back to -ec2.pdf)
├── ISO_32000-2-2020_sponsored.pdf # iso32000-2-2020 : PDF 2.0 original
├── PDF32000_2008.pdf # pdf17 : PDF 1.7 (for version comparison)
├── pdfreference1.7old.pdf # pdf17old : Adobe PDF Reference 1.7
│
│ ── Technical Specifications (TS) ─────────
├── ISO_TS_32001-2022_sponsored_EC3.pdf # ts32001 : Hash extensions (SHA-3)
├── ISO_TS_32002-2022_sponsored_EC3.pdf # ts32002 : Digital signature extensions (ECC/PAdES)
├── ISO_TS_32003-2023_sponsored.pdf # ts32003 : AES-GCM encryption
├── ISO-TS-32004-2024_sponsored.pdf # ts32004 : Integrity protection
├── ISO-TS-32005-2023-sponsored.pdf # ts32005 : Namespace mapping
│
│ ── PDF/UA (Accessibility) ────────────────
├── ISO-14289-1-2014-sponsored.pdf # pdfua1 : PDF/UA-1
├── ISO-14289-2-2024-sponsored.pdf # pdfua2 : PDF/UA-2
│
│ ── Guides ────────────────────────────────
├── Tagged-PDF-Best-Practice-Guide.pdf # tagged-bpg : Tagged PDF Best Practice
├── Well-Tagged-PDF-WTPDF-1.0.pdf # wtpdf : Well-Tagged PDF
├── PDF-Declarations.pdf # declarations: PDF Declarations
│
│ ── Application Notes ─────────────────────
├── PDF20_AN001-BPC.pdf # an001 : Black Point Compensation
├── PDF20_AN002-AF.pdf # an002 : Associated Files
└── PDF20_AN003-ObjectMetadataLocations.pdf # an003 : Object MetadataThis package ships a CLI binary (pdf-spec-mcp) intended to be launched by an MCP client.
You do not need to install it manually — just point your MCP client to npx @shuji-bonji/pdf-spec-mcp@latest as shown in the next step.
If you want to run it directly from the shell (e.g. for debugging):
PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp@latestOr install it globally (optional):
npm install -g @shuji-bonji/pdf-spec-mcp
PDF_SPEC_DIR=/path/to/pdf-specs pdf-spec-mcpVariable | Description | Default |
| Directory containing PDF specification files | (required) |
| Where the on-disk index cache lives (see Index cache) |
|
| Set to | on |
Add to claude_desktop_config.json:
{
"mcpServers": {
"pdf-spec": {
"command": "npx",
"args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
"env": {
"PDF_SPEC_DIR": "/path/to/pdf-specs"
}
}
}
}Use @latest (or pin a version). npx -y <pkg> without a version keeps running whatever
it cached the first time — -y only skips the install prompt, it does not check for updates.
A bare specifier will happily run a months-old release. @latest makes npx check the registry
on each start; pin @0.4.0 instead if you want reproducibility.
To clear a stale cache: rm -rf ~/.npm/_npx.
Add to .cursor/mcp.json or VS Code MCP settings:
{
"mcpServers": {
"pdf-spec": {
"command": "npx",
"args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
"env": {
"PDF_SPEC_DIR": "/path/to/pdf-specs"
}
}
}
}Two operations walk every page of a specification: the first search_spec on a spec builds
its full-text index (ISO 32000-2, 1023 pages: about 6 s on a laptop), and get_requirements
without a section scans every section (about 11 s). Everything else opens only the pages it
needs and answers in well under a second.
Since 0.5.0 those two results are written to disk after the first build and read back by every
later process — an MCP client that starts one server per session no longer pays the build each
time. The second process answers the same search_spec in about 0.2 s and the full
requirements scan in about 0.02 s, from byte-for-byte the same index.
Location: ${PDF_SPEC_CACHE_DIR:-${XDG_CACHE_HOME:-~/.cache}/pdf-spec-mcp}/v1/<version>/<spec>.<kind>.<sha256[0:16]>.json.
The whole 17-spec corpus is about 18 MB per package version.
Key: package version, pdfjs-dist version, spec id, and the SHA-256 of the PDF. A
replaced PDF, an upgraded server, or an upgraded pdfjs all miss and rebuild. Entries of
older versions are left in place (another install may still use them); --clear-cache
removes everything.
Failure is a miss, never an error: an unreadable, truncated, or foreign file is rebuilt; an unwritable directory is reported once on stderr and the server carries on without a cache.
It is derived from your copy of the PDFs and stays on your machine. It is not part of the package and must not be redistributed — the specifications are copyrighted.
Nothing about searching changes: the same in-memory structure is searched by the same code. Only where it comes from (built vs. read) does.
The cache fills lazily, one spec at a time as tools touch it. To warm every spec up front — after installing, after upgrading, or from cron — run the CLI (it uses the same code path as the tools, processes specs sequentially, and exits):
PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp@latest --build-cache
# --spec=iso32000-2,pdf17 only these specs
# --force rebuild even when a valid entry exists
npx -y @shuji-bonji/pdf-spec-mcp@latest --cache-info # directory, key, entries
npx -y @shuji-bonji/pdf-spec-mcp@latest --clear-cache # remove the directoryA full build of the 17-spec corpus takes about a minute on a laptop.
All tools accept an optional spec parameter to target a specific specification (default: iso32000-2).
Tool | Description |
| List all discovered PDF specifications with metadata |
| Get section hierarchy (table of contents) with configurable depth |
| Get structured content of a specific section |
| Full-text keyword search across a specification |
| Extract normative requirements (shall/must/may) |
| Lookup term definitions |
| Extract table structures from a section |
| Compare PDF 1.7 and PDF 2.0 section structures |
list_specs — Discover SpecificationsList all available specification documents. Use the returned IDs as the spec parameter in other tools.
// List all specs
{ }
// Filter by category
{ "category": "ts" } // Technical specs only
{ "category": "pdfua" } // PDF/UA only
{ "category": "guide" } // Guide documents onlyget_structure — Table of ContentsGet the section hierarchy (TOC tree) of a specification.
// PDF 2.0 top-level sections only
{ "max_depth": 1 }
// Expand to 2 levels
{ "max_depth": 2 }
// TS 32002 (Digital Signatures) full structure
{ "spec": "ts32002" }
// PDF/UA-2 structure
{ "spec": "pdfua2", "max_depth": 2 }get_section — Section ContentGet structured content (headings, paragraphs, lists, tables, notes) of a specific section.
A parent section returns its entire subtree (its preamble followed by all subsections, in document order). Top-level clauses can be very large — prefer the most specific section number.
// PDF 2.0 Section 7.3.4.2 (Literal Strings)
{ "section": "7.3.4.2" }
// PDF 2.0 Annex A
{ "section": "Annex A" }
// TS 32002 Section 5
{ "spec": "ts32002", "section": "5" }
// PDF/UA-2 Section 8 (Tagged PDF)
{ "spec": "pdfua2", "section": "8" }search_spec — Full-text SearchSearch across a specification with section-aware context snippets. The first call on a spec builds its index (a few seconds); the index is then cached on disk (see Index cache).
// Search PDF 2.0 for "digital signature"
{ "query": "digital signature" }
// Limit results
{ "query": "font", "max_results": 5 }
// Search within TS 32002
{ "spec": "ts32002", "query": "CMS" }get_requirements — Normative RequirementsExtract normative requirements (shall / must / may) per ISO conventions.
// All requirements in section 12.8
{ "section": "12.8" }
// Only "shall" requirements
{ "section": "12.8", "level": "shall" }
// Only "shall not" requirements
{ "section": "7.3", "level": "shall not" }
// PDF/UA-2 requirements
{ "spec": "pdfua2", "section": "8", "level": "shall" }get_definitions — Term DefinitionsLook up term definitions from Section 3 (Definitions).
// Search for "font" definitions
{ "term": "font" }
// List all definitions
{ }
// PDF/UA definitions
{ "spec": "pdfua2", "term": "artifact" }get_tables — Table ExtractionExtract table structures (headers, rows, captions) from a section. Multi-page tables are automatically merged.
// All tables in section 7.3.4.2 (Table 3 — Escape sequences)
{ "section": "7.3.4.2" }
// Specific table only (0-based index)
{ "section": "7.3.4.2", "table_index": 0 }
// TS spec tables
{ "spec": "ts32002", "section": "5" }compare_versions — Version ComparisonCompare section structures between PDF 1.7 (ISO 32000-1) and PDF 2.0 (ISO 32000-2). Uses title-based automatic matching to detect matched, added, and removed sections.
This tool requires both PDF 1.7 (PDF32000_2008.pdf) and PDF 2.0 files in PDF_SPEC_DIR.
// Diff section 12.8 (Digital Signatures)
{ "section": "12.8" }
// Compare all top-level sections
{ }The server auto-discovers PDF files in PDF_SPEC_DIR by filename pattern matching:
Category | Spec IDs | Documents |
Standard |
| ISO 32000-2 (PDF 2.0), ISO 32000-1 (PDF 1.7) |
Technical Spec |
| Hash, Digital Signatures, AES-GCM, Integrity, Namespace |
PDF/UA |
| Accessibility (ISO 14289-1, 14289-2) |
Guide |
| Tagged PDF, Well-Tagged PDF, Declarations |
App Note |
| BPC, Associated Files, Object Metadata |
src/
├── index.ts # Entry point: MCP server on stdio, or the cache CLI
├── cli.ts # --build-cache / --clear-cache / --cache-info
├── config.ts # Configuration & spec patterns
├── errors.ts # Error hierarchy (PDFSpecError → sub-classes)
├── services/
│ ├── pdf-registry.ts # Auto-discovery of PDF files
│ ├── pdf-loader.ts # PDF loading with LRU cache
│ ├── pdf-service.ts # Orchestration layer
│ ├── index-store.ts # On-disk cache for the search / requirements indexes
│ ├── compare-service.ts # Version comparison
│ ├── outline-resolver.ts # Section index builder
│ ├── content-extractor.ts # Structured content extraction
│ ├── search-index.ts # Full-text search index
│ ├── requirement-extractor.ts
│ └── definition-extractor.ts
├── tools/
│ ├── definitions.ts # MCP tool schemas
│ └── handlers.ts # Tool implementations
├── types/
│ └── index.ts # Shared type definitions
└── utils/
├── concurrency.ts # mapConcurrent (bounded Promise.all)
├── text.ts # Text normalization
├── cache.ts # LRU cache
├── file-hash.ts # SHA-256 of a PDF (index cache key)
├── validation.ts # Input validation
└── logger.ts # Structured loggergit clone https://github.com/shuji-bonji/pdf-spec-mcp.git
cd pdf-spec-mcp
npm install
npm run build
# Unit tests
npm run test
# E2E tests (requires PDF files in ./pdf-spec/)
npm run test:e2e
# Lint & format
npm run lint
npm run format:checkCompare sections between PDF 1.7 (ISO 32000-1) and PDF 2.0 (ISO 32000-2). Returns matched sections (same or moved), added sections (new in 2.0), and removed sections (absent in 2.0). Uses title-based automatic matching.
| Name | Required | Description | Default |
|---|---|---|---|
| section | No | Compare a specific section and its subsections (e.g., "12.8" for Digital Signatures). Uses PDF 2.0 section numbering. If omitted, compares all top-level sections. |
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 that matching is title-based and returns three categories. However, it does not cover limitations, error handling, or behavior for ambiguous matches, which would improve transparency.
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 concise sentences with no wasted words. The purpose, output types, and matching method are front-loaded and clearly communicated.
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?
Given one optional parameter and no output schema, the description covers the tool's function and return types well. It lacks details on output format or size limits, but is largely complete for the tool's complexity.
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% with one parameter. The description adds value by explaining that the optional 'section' parameter uses PDF 2.0 numbering and comparing all top-level sections if omitted. This goes beyond the schema's basic description.
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 it compares sections between PDF 1.7 and PDF 2.0, specifying matched, added, and removed sections. The verb 'compare' is specific and the resource is well-defined, distinguishing it from siblings like get_section or list_specs.
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 provides clear context: it compares sections between two PDF versions. However, it does not explicitly state when not to use this tool or mention alternatives. Given the narrow scope, the usage is clear but lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get term definitions from Section 3 of the PDF specification (ISO 32000-2). Returns structured definitions with term, definition text, notes, and sources.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | Specification ID (e.g., "iso32000-2", "ts32002", "pdfua2"). Use list_specs to see available specs. Default: "iso32000-2" (PDF 2.0). | |
| term | No | Search for a specific term by keyword (case-insensitive substring match). If omitted, returns all definitions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
As no annotations are provided, the description carries the full burden. It mentions the return structure (term, definition text, notes, sources) but does not disclose any behavioral traits like read-only nature, performance, or limitations. This is adequate but not thorough.
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 concise at two sentences and immediately communicates the core purpose. Every word adds value, with no redundancy or fluff.
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?
The tool has two optional, simple parameters and no output schema. The description explains the return format and source, but could be more complete by mentioning default behavior (e.g., returns all definitions if term omitted). However, it covers the essential context for straightforward use.
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 description adds little beyond what the schema already explains. The description does not introduce new meaning for the parameters; it simply restates the context. Baseline score of 3 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 clearly states the tool retrieves term definitions from a specific section (Section 3) of a PDF specification, with a defined output structure. It distinguishes itself from sibling tools like 'get_section' or 'search_spec' by focusing specifically on definitions.
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 does not provide guidance on when to use this tool versus alternatives (e.g., 'search_spec' for broader searches). It lacks explicit when-to-use or when-not-to-use advice, leaving the agent to infer from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract normative requirements (shall/must/may) from the PDF specification (ISO 32000-2). Returns structured requirements with the sentence context, section, and requirement level.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | Specification ID (e.g., "iso32000-2", "ts32002", "pdfua2"). Use list_specs to see available specs. Default: "iso32000-2" (PDF 2.0). | |
| section | No | Filter by section number (e.g., "7.3.4", "12.8"). Includes subsections. If omitted, scans all sections (slower on first call). | |
| level | No | Filter by requirement level. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the tool's output structure and source specification. However, it does not explicitly state that it is a read-only operation or mention potential performance implications (e.g., slower without section filter), which are only implied in parameter descriptions.
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 action and result. Every word adds value, with no redundancy or unnecessary details.
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?
Given no output schema and no annotations, the description provides a reasonable overview of purpose and return format. It could be more complete by explicitly stating it is a read-only operation or noting performance characteristics, but overall it is sufficient for the tool's complexity.
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?
Input schema has 100% parameter description coverage. The description adds context by specifying the type of requirements (shall/must/may) and return fields (sentence context, section, level). It also references list_specs for available specs and explains section filtering behavior.
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 (extract), resource (normative requirements from PDF specification), and return format (structured with context, section, level). It effectively distinguishes from sibling tools like get_definitions and get_section.
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 implies usage for extracting requirements but does not explicitly state when to use this tool over siblings like search_spec or get_section. No direct comparison or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the content of a specific section from the PDF specification (ISO 32000-2). Returns structured content including headings, paragraphs, lists, tables, and notes.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | Specification ID (e.g., "iso32000-2", "ts32002", "pdfua2"). Use list_specs to see available specs. Default: "iso32000-2" (PDF 2.0). | |
| section | Yes | Section identifier (e.g., "7.3.4", "12.8", "Annex A", "Foreword") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It states the tool returns structured content (headings, paragraphs, etc.) but does not mention potential side effects, rate limits, authentication, size limits, or error handling. For a read-only tool, this is acceptable but not comprehensive.
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: first defines the action and resource, second describes return types. No redundant words, front-loaded with essential information.
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 simple tool with two well-documented parameters and no output schema, the description covers purpose and return types adequately. It lacks details on error cases or structure format, but given low complexity, it is nearly complete.
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 input schema has 100% description coverage, already documenting spec and section with examples. The description does not add parameter-level details beyond the schema. Baseline of 3 applies as the schema handles the burden.
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 tool retrieves the content of a specific section from the PDF specification, listing the types of content returned. It distinguishes itself from siblings like get_structure (which likely returns only the outline) and search_spec (which searches across sections).
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 implies the tool is for retrieving full section content, but it does not explicitly state when to use this over alternatives like get_structure (for structure) or get_definitions (for definitions). No when-not or alternative guidance is provided, though the purpose is clear enough to make an informed choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the section hierarchy of the PDF specification (ISO 32000-2). Returns the table of contents with section numbers, titles, and page numbers.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | Specification ID (e.g., "iso32000-2", "ts32002", "pdfua2"). Use list_specs to see available specs. Default: "iso32000-2" (PDF 2.0). | |
| max_depth | No | Maximum depth of the hierarchy to return (default: all levels). 1 = top-level only, 2 = top + sub-sections, etc. |
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 the return type but does not mention side effects, auth requirements, rate limits, or pagination. For a read-only operation, this is adequate but not rich.
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, to the point, and front-loaded with the main purpose. Every sentence adds value.
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?
Given two optional parameters, no output schema, and no annotations, the description adequately explains the return value. It lacks details on result limits but is sufficient for a simple hierarchy tool.
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% with detailed parameter descriptions. The description does not add new information beyond the schema, so it meets the baseline of 3.
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 it gets the section hierarchy (table of contents) of a PDF specification, with specific output details (section numbers, titles, page numbers). This distinguishes it from sibling tools like get_section (single section) and list_specs (list of specs).
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 implies use when needing the TOC, but does not explicitly state when to use or when not to use, nor does it mention alternatives. However, the sibling list provides context, so the agent can infer differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract table structures from a specified section of the PDF specification (ISO 32000-2). Returns tables with headers, rows, and optional captions.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | Specification ID (e.g., "iso32000-2", "ts32002", "pdfua2"). Use list_specs to see available specs. Default: "iso32000-2" (PDF 2.0). | |
| section | Yes | Section identifier (e.g., "7.3.4", "12.8", "Annex A") | |
| table_index | No | Optional 0-based index to retrieve a specific table. If omitted, returns all tables in the section. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the tool is read-only (extracting) and details what is returned. However, it does not disclose potential limitations like rate limits or authentication needs, though for a retrieval tool this is acceptable.
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 a single concise sentence with no extraneous information. It front-loads the main action and result, making it efficient for an agent to parse.
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?
While there is no output schema, the description adequately explains the return type. It lacks details on edge cases (e.g., section without tables) but covers the core functionality sufficiently for a simple extraction tool.
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 input schema has 100% description coverage with clear explanations for each parameter. The tool description adds minimal extra value beyond stating the return format, which is not parameter-specific. Baseline score of 3 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 clearly states the tool extracts table structures from a specified section of a PDF specification, including what is returned (headers, rows, optional captions). It distinctly differentiates from sibling tools like get_section or get_definitions by focusing specifically on tables.
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 implies usage when table structures are needed from a PDF spec section, but it does not provide explicit guidance on when to use this tool over alternatives like get_section or search_spec, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available PDF specification documents. Returns document IDs, titles, page counts, and categories. Use the returned IDs as the spec parameter in other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter by document category. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behaviors. It states the tool lists documents and returns specific fields, but does not mention any potential pagination, ordering, or limitations. This is adequate for a simple listing tool.
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 concise sentences with no superfluous words. The key information is front-loaded.
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?
Given no output schema, the description explains return fields. It provides sufficient context for a simple listing tool, though it could mention if results are ordered or limited. Overall complete.
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% with a clear parameter description. The description does not add significant meaning beyond the schema, but it does implicitly indicate that the category filter is optional.
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 uses specific verbs and resources ('List all available PDF specification documents') and lists return fields. It clearly distinguishes from sibling tools like 'compare_versions' or 'get_section'.
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 tells when to use the tool ('to get a list') and how to use the output ('Use the returned IDs as the `spec` parameter'). It does not mention when not to use or compare to alternatives, but it is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the PDF specification (ISO 32000-2) for a keyword or phrase. Returns matching sections with context snippets. The first call may take a few seconds to build the search index.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | Specification ID (e.g., "iso32000-2", "ts32002", "pdfua2"). Use list_specs to see available specs. Default: "iso32000-2" (PDF 2.0). | |
| query | Yes | Search query (keyword or phrase) | |
| max_results | No | Maximum number of results to return (default: 10, max: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It helpfully notes that the first call may take a few seconds to build the search index, indicating a setup cost. However, it does not disclose whether the operation is idempotent, any authorization needs, or what happens on errors.
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 concise sentences. The first sentence states the primary action and resource, the second states the output format, and the third adds a crucial performance note. No redundant or unnecessary information.
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?
Given the tool's complexity (3 parameters, no output schema, no annotations), the description adequately covers its purpose, output (sections with snippets), and a special behavior (first-call delay). It does not describe the return format in detail, but that is acceptable for a search tool.
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 input schema has 100% description coverage for all 3 parameters. The schema itself provides clear descriptions (e.g., spec ID hinting at list_specs). The tool description adds no additional parameter meaning beyond what the schema already offers, warranting the baseline score.
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 tool searches the PDF specification (ISO 32000-2) for a keyword or phrase and returns matching sections with context snippets. It distinguishes itself from siblings like get_section or get_definitions by focusing on keyword-based search across the entire spec.
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 implies usage for finding topics across the spec but does not explicitly state when to use this tool versus alternatives (e.g., get_section for known sections). It mentions a first-call delay but lacks guidance on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.4compare_versionsget_definitionsget_requirementsget_sectionget_structureget_tableslist_specssearch_specScored across 8 tools
Each tool targets a distinct aspect of the PDF specification: version comparison, definitions, requirements, sections, structure, tables, listing specs, and searching. No overlap in purpose.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_section, search_spec). There is no mixing of conventions.
With 8 tools, the set is well-scoped for exploring and comparing PDF specifications. Each tool serves a clear function without being excessive or insufficient.
The tool surface covers common operations for a reference document: listing, searching, retrieving structure, content, tables, definitions, requirements, and version comparison. No obvious gaps for its read-only domain.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Query your own PDFs and documents from any MCP client. Every answer cites the page it came from.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
