Skip to main content
Glama

Smart OCR

extract_document_json

Idempotent

Extract strict, structured JSON matching any custom JSON schema or field template from a PDF or image (PNG, JPG, WEBP, TIFF). Ideal for developer pipelines, ERP/accounting ingestion, and custom document fields. Works on the free tier (2 free docs/day) or with a Smart OCR API key (10 free credits at https://smartocr.dev).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "schema": "<schema>"
    },
    "name": "extract_document_json"
  }
}

Input Schema

NameRequiredDescriptionDefault
schemaYesTarget JSON schema or key-value object template describing the fields to extract (e.g., {"vendorName": "string", "invoiceNumber": "string", "invoiceDate": "string", "totalAmount": "number", "lineItems": [{"description": "string", "quantity": "number", "amount": "number"}]}).
api_keyNoOptional Smart OCR API key from https://smartocr.dev (can also be sent via x-api-key header). If omitted, uses the free tier (2 free docs/day).
file_urlNoPublic HTTP/HTTPS URL to a PDF, PNG, JPG, WEBP, or TIFF document to extract.
file_nameNoOptional filename with extension (e.g., "invoice.pdf").
file_base64NoBase64-encoded document content (raw base64 or data:...;base64,... URI). Provide either file_url or file_base64.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Annotations declare it is not read-only, is idempotent, and reaches an open world, so the safety profile is already covered. The description adds genuinely new operational facts: supported input formats, a free-tier cap of 2 docs/day, and that an API key can be passed directly or via the x-api-key header. It stops short of describing failure modes or partial extraction behavior.

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?

Three sentences, front-loaded with the core capability before the use cases and pricing/auth note. The Smart OCR URL and free-credit plug are mildly promotional, but they carry real auth information, so little is wasted.

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 5-parameter, nested-schema tool with no output schema, the definition covers input formats, schema/template semantics, and auth paths adequately. It does not state what the returned JSON envelope looks like on failure or how partial/missing fields are represented, which is the main remaining gap.

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%, so the baseline is 3. The phrase "custom JSON schema or field template" echoes what the schema property already documents, adding no new syntax or constraint detail, and file_url/file_base64 handling is only covered by the schema itself.

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?

"Extract strict, structured JSON matching any custom JSON schema or field template from a PDF or image" names a specific verb, output artifact, and input formats, which is enough to distinguish it from extract_document_table (tables) by output shape. It never names the sibling explicitly, so the differentiation is inferred rather than stated.

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

Usage Guidelines3/5

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

Use cases are given (developer pipelines, ERP/accounting ingestion, custom document fields), which implies when to reach for it. However, there is no explicit when-not guidance and no routing to extract_document_table for tabular output or get_smartocr_status for account state, leaving the agent to guess at boundaries.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources