Agent-first CLI, Python API, and MCP server for the National Archives Catalog API
Server has 10 tools with complete schemas and descriptions. Naming follows verb_noun pattern consistently (nara_search, nara_get, nara_download). Descriptions are present and actionable (avg ~80 chars), explaining WHAT and WHEN. However, parameter descriptions are minimal (often single phrases), and output schemas are not documented. Error handling is absent, no guidance on retryability, user-fixable vs fatal errors, or recovery paths. Security is well-handled (secrets scrubbed, write-root validation), but composition could be tighter (some tools like nara_make_source_packet and nara_make_negative_search_record feel domain-specific rather than general-purpose).
Show ancestor, parent, and likely series context for a NAID.
Check whether a NARA API key is configured without returning the key.
Return a count-focused NARA Catalog search result.
Download selected digital objects for a NARA record into an explicit local destination.
Find records related by parent, series, record group, or similar title.
Fetch one NARA Catalog record by NAID.
Output schemas not documented. LLMs cannot predict response structure or plan downstream tool calls. E.g., nara_search_records returns 'normalized compact records' but field names, types, and nesting are invisible.
No error handling guidance. Tools lack recovery hints (e.g., 'NAID not found, try nara_search_records first'). No categorization of errors as retryable vs user-fixable. Agents cannot self-correct on failure.
Parameter descriptions are minimal. E.g., 'selection' in nara_download_digital_objects says 'Selection of objects to download (e.g. 1,3-5 or all)' but does not explain the format formally (regex, constraints, edge cases). LLMs may hallucinate invalid selections.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 58 | 2026-07-28+ | v2 |
List digital objects for a NARA Catalog record.
Create a negative-search draft from a NARA query and filters.
Create a repository-style NARA source-packet draft.
Search NARA Catalog records and return normalized compact records.
nara_make_source_packet and nara_make_negative_search_record are domain-specific and lack clear use cases in descriptions. 'Create a repository-style NARA source-packet draft' assumes knowledge of NARA archival workflows. Descriptions should explain WHEN an LLM should call these vs alternatives.
Pagination support incomplete. nara_search_records accepts 'page' but does not document total_count or next_cursor in response. LLMs cannot determine if more results exist or how to fetch them efficiently.