PaperOffice AI

Get document details and metadata

po_documents_get

Read-onlyIdempotent

READ-ONLY. Returns data, changes nothing. Get document identity, processing state and compact trust.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`pofid`	No	PaperOffice File ID (POFID). Copy byte-for-byte from po_documents_search. Hash prefix uses PaperOffice encoding (SHA-256 with digit 0 stored as letter O) — never replace O with 0. At least one of pofid or documents_id MUST be provided.
`compact`	No	Default true: core identity and summary, plus capabilities, processing_state, trust and audit.
`resolve`	No	latest returns the current version of the line. Default exact returns the given version.	exact
`documents_id`	No	Numeric document ID — alternative to pofid. At least one of pofid or documents_id MUST be provided.
`include_pages_ocr`	No	Default false. Set true only for per-page OCR; otherwise use po_documents_text_get.

Output Schema

TableJSON Schema

Name	Required	Description
`hint`	No
`text`	No
`pofid`	No
`details`	No
`message`	No
`summary`	No
`currency`	No
`_warnings`	No
`file_name`	No
`retryable`	No
`error_code`	No
`enforcement`	No
`http_status`	No
`total_pages`	No	Page count. page_count_basis says source or rendered pages.
`capabilities`	No
`display_name`	No
`documents_id`	No
`total_amount`	No
`workspace_id`	No
`document_type`	No
`page_integrity`	No
`workspace_name`	No
`_billing_summary`	No
`page_count_basis`	No
`processing_state`	No
`original_file_name`	No
`total_pages_rendered`	No
`write_tools_in_profile`	No	Whether the write tool is registered on this connector (not a permission)
`extraction_capabilities`	No
`effective_write_permissions`	No	Document capability ∩ token ACL, enforced server-side

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 12, 2026

changedInput schema / properties / compact / description

Previous value: -"Compact mode (default true): core identity, classification, dates, summary, sender/recipient, amounts when present, plus capabilities, processing_state, trust and audit."New value: +"Default true: core identity and summary, plus capabilities, processing_state, trust and audit."

changedInput schema / properties / include_pages_ocr / description

Previous value: -"When false (default), pages_ocr is omitted from the response — use po_documents_text_get for OCR text. Set true only when per-page OCR is required."New value: +"Default false. Set true only for per-page OCR; otherwise use po_documents_text_get."

changedInput schema / properties / resolve / description

Previous value: -"Versioning: latest = return the CURRENT version of the document line even if pofid points to an older version (response.document.resolved_to_latest=true, requested_pofid keeps the input). Default exact = the given version."New value: +"latest returns the current version of the line. Default exact returns the given version."

changedOutput schema / properties / total_pages / description

Previous value: -"Page count on the basis named in page_count_basis: source file pages, or rendered pages for Markdown/DOCX/XLSX/EML (then total_pages_source holds the source count)"New value: +"Page count. page_count_basis says source or rendered pages."

Changed1 schema field changedOct 11, 2026

changedInput schema / properties / compact / description

Previous value: -"Compact mode (default true): core identity, classification, dates, summary, sender/recipient, amounts when present, plus capabilities and processing_state."New value: +"Compact mode (default true): core identity, classification, dates, summary, sender/recipient, amounts when present, plus capabilities, processing_state, trust and audit."

First observedSep 26, 2026

TDQS

C2.9/5.0

Behavior2/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so 'READ-ONLY. Returns data, changes nothing.' is pure duplication of structured data. The description adds no behavioral context beyond the annotations — no auth requirements, rate limits, or notes on what the compact flag alters in practice.

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

Conciseness3/5

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

Very short and front-loaded, but the opening two sentences are redundant with the annotations, so they do not earn their place. Given five parameters and a compact/resolve versioning model, the definition is under-specified rather than admirably tight.

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

Completeness3/5

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

An output schema exists, so return values need not be explained, and the schema itself covers the pofid/documents_id either-or constraint. What is missing is any prose about sibling selection (text_get for OCR text, search for discovery), which is exactly the gap the description should fill at this complexity level.

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 100% and every parameter (pofid, compact, resolve, documents_id, include_pages_ocr) carries a detailed schema description including the POFID encoding caveat and the alternates. The description adds nothing new about parameters, so the baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource: 'Get document identity, processing state and compact trust.' This is more informative than the title alone and tells the agent the payload class (identity/metadata, not content). However, it never distinguishes itself from siblings like po_documents_text_get or po_documents_search, leaving that routing work to the schema.

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

Usage Guidelines2/5

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

The description contains no when-to-use guidance, no prerequisites, and no named alternatives — unlike the sibling routing hint buried in the schema ('otherwise use po_documents_text_get'). An agent gets no textual signal about when this tool is the right choice versus text_get or search.

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

All PaperOffice AI tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?