Skip to main content
Glama
ianderso

nara-catalog-mcp

by ianderso
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

get_extracted_text

Read-only

Read the OCR text NARA machine-extracted from a record's page images to locate which page matters, then verify it against the page image before citing.

Instructions

Read the OCR text NARA machine-extracted from a record's page images.

This is a lead, not evidence. OCR was run over scans of handwriting, carbon copies and microfilm: it drops handwritten pages entirely, and it turns one surname into another silently. Use it to find which page matters, then open that page image with get_record_images and cite what you saw there -- never cite the OCR text itself.

Returns one entry per digital object, in page order, with the text truncated to max_chars.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
naidYesThe record's NAID.
pageNoPage of results, 1-based.
limitNoMaximum digital objects to return (1-100).
refreshNoTrue re-reads from the Catalog instead of the cache, spending one call and replacing the cached copy. The cache never expires on its own, so use this when the answer may have changed since you last asked.
max_charsNoCharacters of text to return per page. 0 returns all of it, which for a long file unit is tens of thousands.
object_idNoLimit to one digital object (one scanned page). Omit it to get the text of every page of the record.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.0.2
    • addedInput schema / additionalProperties
      Added value: +false
  2. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only cover read-only/open-world safety, but the description goes well beyond: it warns OCR 'drops handwritten pages entirely' and 'turns one surname into another silently,' plus defines the return shape (one entry per page, page order, truncated to max_chars). That is exactly the reliability context an agent needs and cannot get from structured fields.

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

Conciseness5/5

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

Front-loads the essential action, then the caveat, then the recommended workflow, then the return format. Every sentence carries distinct information; the structure maps cleanly to how an agent consumes it.

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

Completeness5/5

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

With no output schema, the description compensates by describing the return format (one entry per page, ordering, truncation). Combined with the OCR reliability caveats and the recommended get_record_images follow-up, an agent has everything needed to call and use this tool correctly.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful framing by tying the output to 'one entry per digital object' and text 'truncated to `max_chars`,' reinforcing the object_id/max_chars semantics. It does not, however, add syntax or defaults beyond the schema.

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 ('Read the OCR text NARA machine-extracted from a record's page images') and its scope ('one entry per digital object, in page order'). The qualifier 'machine-extracted' implicitly distinguishes it from the human-transcription sibling get_transcriptions, so an agent can route correctly without reading schemas.

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

Usage Guidelines5/5

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

Explicitly frames usage: 'Use it to find which page matters, then open that page image with get_record_images and cite what you saw there -- never cite the OCR text itself.' This names the alternative tool, the follow-up step, and an explicit prohibition, leaving nothing to inference.

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

Deploy Server

Other Tools