mcp-template

pdf_open

Open a PDF into a server-side editing session and return a doc_id, form-field inventory, or text layout so later edits can be planned; optionally render pages as PNGs.

Instructions

Open a PDF into a server-side editing session and return everything needed to plan edits: a doc_id handle, the fillable form-field inventory (name, type, current value, page, rect), and - for flat PDFs without form fields - the existing text layout with coordinates for anchoring text overlays. The PDF bytes stay server-side; every later pdf_* call takes the doc_id. Optionally pass render_pages (1-based page numbers) to also get PNG renders of pages for visual inspection. Coordinates are PDF user space: origin at the page's bottom-left corner, in points (1/72 inch).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`source`	Yes
`user_id`	No
`render_pages`	No

Output Schema

TableJSON Schema

Name	Required	Description
`doc_id`	Yes	Session handle for all subsequent pdf_* calls
`fields`	No
`status`	Yes
`filename`	Yes
`warnings`	No	Non-fatal caveats about this document (existing digital signatures, XFA forms). Relay these to the user before planning edits.
`page_count`	Yes
`page_sizes`	No
`page_images`	No
`text_layout`	No	Existing text lines with coordinates (flat PDFs only), for anchoring add_text overlays
`has_acroform`	Yes	True if the PDF has fillable form fields (use set_field); false means a flat PDF (use add_text overlays anchored on text_layout)
`existing_signatures`	No	Signature fields that already hold a digital signature. Editing such a document cryptographically invalidates them - pdf_edit requires acknowledge_signature_invalidation=true, and the user must be told before proceeding.
`text_layout_truncated`	No	True if text_layout was cut at pdf_forms.text_layout_max_lines

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.1Oct 19, 2026

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses that PDF bytes stay server-side, that the call establishes a session keyed by doc_id, and it defines the coordinate system (origin at bottom-left, points at 1/72 inch) needed for later anchoring. It omits session lifetime/expiry, permission requirements, and size limits, which keeps it below 5.

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?

Dense but well front-loaded: the first sentence leads with the action and the three things returned, and the coordinate-system note is placed last where it belongs. Every sentence adds information, though the return-value enumeration is somewhat verbose given an output schema exists.

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

Completeness4/5

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

For a session-opening tool with no annotations, the description covers the critical unknowns: server-side byte handling, the doc_id lifecycle, optional rendering, and coordinate conventions. Missing auth/prerequisite and session-expiry details keep it from being fully complete, though the presence of an output schema reduces the need to describe return payloads.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate. It explains render_pages well (1-based page numbers, produces PNG renders for visual inspection), but never says how the PDF is supplied, and user_id is not mentioned at all. The nested GmailAttachmentSource $defs description partially covers the source locator, leaving one of three parameters fully undocumented.

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?

States a specific verb and resource ('Open a PDF into a server-side editing session') and immediately enumerates what it returns: doc_id, form-field inventory, or text layout for flat PDFs. The line 'every later pdf_* call takes the doc_id' positions it as the entry point relative to pdf_edit, pdf_export, and pdf_request_signature, so an agent can tell it apart from those siblings without opening schemas.

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

Usage Guidelines4/5

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

Clearly establishes the sequencing context: open first, then pass doc_id to subsequent pdf_* calls, and render_pages is framed as an optional extra 'to also get PNG renders... for visual inspection.' There is no explicit when-not guidance or named alternative (e.g., what to do if the PDF is already open), so it falls short of a 5.

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

Deploy Server