Search LOC digital collections, Chronicling America newspapers (full OCR), and LC Subject Headings.
Scored across 6 tools
Each tool targets a distinct resource and action: search scopes (general, newspapers, subjects) and retrieval (item metadata vs. newspaper page OCR) are clearly separated. No two tools could be confused for the same task, even search variants have specific filters and outputs.
All tools share the libofcongress_ prefix and follow a consistent verb_noun pattern (browse_collections, get_item, get_newspaper_page, search, search_newspapers, search_subjects). The bare 'search' is a slight deviation but still fits the verb-first style and is unambiguous.
Six tools is within the ideal 3–15 range and perfectly scoped for a read-only digital archive server. Each tool serves a clear purpose without redundancy, covering search, browse, and retrieval without bloat.
The tool surface fully covers the domain: general search, newspaper search, subject-heading lookup, collection browsing, item metadata retrieval, and full-text newspaper page retrieval. There are no obvious gaps for a read-only API, and the search_subjects tool enhances the search workflow.
List and browse Library of Congress curated digital collections. Returns collection names, descriptions, item counts, slugs, and URLs. Optionally filter by keyword. Collections are curated subsets of the digital holdings with specific focuses (e.g., "Civil War Glass Negatives", "Baseball Cards", "WPA Posters"). Use the returned URL to navigate directly to a collection on loc.gov.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number for paginating results. | |
| limit | No | Maximum number of collections to return. Default 25, max 100. | |
| query | No | Optional keyword to filter collections by name or description. Omit to list all collections. |
| Name | Required | Description |
|---|---|---|
| page | No | Current 1-indexed page number. |
| error | No | Present when the call failed. Absent on success. |
| pages | No | Total number of pages available. |
| total | No | Total number of matching collections across all pages. |
| notice | No | Recovery hint when results are empty or a page is out of range — suggests broadening the keyword or removing filters. Absent on successful result pages. |
| has_next | No | True when more pages are available after this one. |
| totalCount | No | Total matching collections — mirrors output.total for agent reasoning. |
| collections | No | LOC curated collections matching the keyword filter, or all collections when no keyword is specified. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the read-only nature and unpredictability of results. The description adds value by listing what is returned (names, descriptions, item counts, slugs, URLs) and advising the use of URLs for direct navigation. It does not contradict annotations and provides useful behavioral context beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff. The first sentence front-loads the primary purpose and return type, the second explains the filtering option, and the third provides context and a practical usage tip. Every sentence earns its place, and the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, full parameter descriptions in the input schema, and annotations covering read-only and open-world behavior, the description is complete for an agent to call the tool correctly. It explains what the tool returns and how to use the results, leaving no critical gap for execution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters (page, limit, query), so the baseline is 3. The description mentions the keyword filter ('Optionally filter by keyword') but does not add any additional semantics about page or limit beyond what the schema already specifies. It reinforces the query parameter but adds no new information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: listing and browsing Library of Congress curated digital collections. It specifies the resource (curated collections) and the action (list/browse), and distinguishes itself from sibling tools by focusing on collections rather than item-level search or retrieval. The inclusion of concrete examples (e.g., 'Civil War Glass Negatives') further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool—when browsing or listing curated collections—and mentions the optional keyword filter. It implies this is the entry point for discovering collections before navigating to specific items, but it does not explicitly name alternatives or state when NOT to use it (e.g., 'For item-level search, use libofcongress_search'). The usage is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the full metadata record for a specific LOC digital item. Returns contributors, subjects, summary, languages, locations, rights information, physical description, call number, original and online formats, access restrictions, former catalog IDs, notes, related items, and links to digital resources (TIFF, JPEG, PDF) for items with digital surrogates. Use after libofcongress_search on a result whose is_item is true. Pass the result id verbatim — it may be a simple ID or a slash-separated newspaper path; do not prepend the loc.gov URL. Non-item results (is_item: false) — collections, exhibits, guides, newspaper pages — have no item record and cannot be retrieved here.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | LOC item id from a libofcongress_search result's "id" field (where is_item is true). A simple ID ("2009632251", "2005691065") or a slash-separated path for newspaper pages ("sn95047246/1935-09-05/ed-1"). Pass the id verbatim; do not prepend the loc.gov URL or an "item/" prefix. |
| Name | Required | Description |
|---|---|---|
| url | No | Canonical LOC item URL. |
| date | No | Publication or creation date. |
| error | No | Present when the call failed. Absent on success. |
| notes | No | Descriptive notes and annotations from catalogers. |
| title | No | Item title. |
| item_id | No | LOC item ID as resolved by the service (matches the input item_id). |
| summary | No | Cataloger's abstract of the item's subject and historical context. |
| languages | No | Languages of the item (e.g., "english"). |
| locations | No | Places the item depicts or originates from (e.g., "united states"). |
| former_ids | No | Superseded catalog identifiers or URLs this item was previously known by. |
| call_number | No | LOC call number — the shelf location for requesting the physical original. |
| contributors | No | Contributors, creators, or photographers as LOC catalogs them, role included (e.g., "Washington, George, 1732-1799 (Author)"). One person can appear once per role. Empty when LOC lists none. |
| related_items | No | IDs or URLs of related LOC records for follow-up retrieval; a title stands in for a related record LOC gives neither for. |
| online_formats | No | Formats the digitized surrogate is available in (e.g., "image"). |
| resource_links | No | URLs to downloadable digital files (TIFF, JPEG, PDF). Empty when no digital surrogate exists. |
| original_formats | No | Material types of the original (e.g., "photo, print, drawing"). |
| subject_headings | No | LCSH subject headings assigned to this item. |
| access_restricted | No | True when LOC restricts access to the original. Absent when upstream omits it. |
| rights_information | No | Rights and reproduction statement for this item. |
| physical_description | No | Physical or technical description of the original item. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral detail about what the response includes — contributors, subjects, rights, formats, access restrictions, and digital resource links — plus the caveat about items without digital surrogates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every section earns its place: purpose first, then return contents, then usage rules and exclusions. The structure is dense but scannable, with clear guidance embedded naturally.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single required parameter, a fully documented schema, an output schema present, and annotations covering read-only behavior, the description adds the remaining operational context: when to call it, what ids are valid, and what cannot be fetched. An agent has everything needed to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema itself is rich, giving a baseline of 3. The description reinforces key invocation semantics beyond the schema: pass the result id verbatim, the id may be a simple ID or a slash-separated newspaper path, and must come from an is_item:true search result.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the full metadata record for a specific LOC digital item and enumerates the returned data categories. It also distinguishes itself from related tools by explicitly saying non-item results like collections, exhibits, guides, and newspaper pages cannot be retrieved here.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: use this tool after libofcongress_search on a result whose is_item is true. It also states what not to do, including passing non-item results and not prepending the loc.gov URL or an 'item/' prefix.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the full OCR text of a specific historical newspaper page along with publication metadata — newspaper title, issue date, place of publication, indexed states, edition, the page's sequence, and the issue's page count. Pass the url field from a libofcongress_search_newspapers result — do not construct this URL manually. OCR quality varies by digitization batch and era: 19th-century and degraded materials may contain fragmented text, garbled words, and line-break artifacts that are surfaced as-is. When a page exists but has no digitized text, ocr_available is false and ocr_text is empty — this is a data property, not an error.
| Name | Required | Description | Default |
|---|---|---|---|
| page_url | Yes | The url field from a libofcongress_search_newspapers result (e.g., "https://www.loc.gov/resource/sn83045462/1905-03-15/ed-1/seq-1/"). Always pass the value directly from search results — do not construct or modify this URL. |
| Name | Required | Description |
|---|---|---|
| date | No | Issue publication date (YYYY-MM-DD). |
| error | No | Present when the call failed. Absent on success. |
| notice | No | Set when ocr_available is true but ocr_text is empty — the page has digitized OCR, but the text service did not return it this call. Distinguishes a transient retrieval miss from a genuinely image-only page (where ocr_available is false). Absent when OCR text was returned or the page has no OCR. |
| states | No | Every US state LOC indexes this newspaper title under (e.g., ["georgia", "south carolina"]), in LOC order — possibly more than the state of publication. Absent when LOC lists no state. |
| edition | No | Edition number of the issue (e.g., "1"). Absent when LOC gives none. |
| ocr_text | No | Full plain-text OCR content for the page. Empty string when ocr_available is false. May contain fragmented words, line-break artifacts, and misspellings inherent to historical OCR — do not attempt to repair. |
| page_url | No | The LOC resource URL for this newspaper page. |
| sequence | No | Page sequence number within the issue. |
| ocr_available | No | True when digitized OCR text exists for this page. False for image-only digitization batches where OCR has not been applied. |
| segment_count | No | Number of pages in the issue. Absent when LOC gives none. |
| newspaper_title | No | Title of the newspaper publication. Absent when LOC gives none. |
| place_of_publication | No | Where the newspaper was published, as LOC catalogs it (e.g., "Charleston, S.C."). Absent when LOC gives none. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses OCR quality variability across digitization batches and eras, including specific artifacts like fragmented text and garbled words, and clarifies that an empty ocr_text with ocr_available=false is a data property, not an error. These details go well beyond the readOnlyHint and openWorldHint annotations, giving the agent realistic expectations about output quality and error semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary action, then usage instruction, then behavioral caveats. Every sentence earns its place, there is no filler, and the structure flows logically from purpose to invocation to expected variability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter retrieval tool with an output schema already present, the description covers everything an agent needs: what it returns, how to obtain the required URL, and how to interpret two important edge cases (degraded OCR and missing text). No critical gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents page_url thoroughly, including an example and the directive to pass it unchanged. The tool description repeats that directive almost verbatim but adds no new semantic detail beyond what the schema states. Baseline 3 applies because the schema carries the full meaning and the description reinforces without extending it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Retrieve the full OCR text of a specific historical newspaper page' plus a detailed list of the metadata returned. It is unambiguously a fetch-a-page tool and is distinct from siblings like libofcongress_get_item (generic item) and libofcongress_search_newspapers (search). The instruction to use the url field from a search result anchors its role in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs the agent to pass the url field from libofcongress_search_newspapers and warns not to construct it manually. This gives a clear context for when the tool should be invoked. It does not explicitly name alternatives or state when not to use it, but the workflow implication is strong and the sibling tools are distinct enough that an agent can infer the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Library of Congress digital collections by keyword. Optionally filter by material format (photos, maps, newspapers, audio, etc.), date range, subject heading, or geographic location, or scope the search to a single curated collection with collection_slug. Returns item summaries with titles, dates, descriptions, LOC IDs, and format tags. Each result carries is_item: pass the id of a result where is_item is true to libofcongress_get_item for full metadata; results where is_item is false are non-item resources (collections, exhibit and research-guide pages, newspaper-page results) with no item record — open their url instead. Use libofcongress_search_subjects first to find the exact LCSH heading spelling before applying a subject filter.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number for paginating results. | |
| limit | No | Results per page. Default 25, max 100. | |
| query | Yes | Full-text search across metadata and available descriptive text. | |
| format | No | Material type filter. Options: photo, map, newspaper, manuscript, audio, film, book, notated-music. Omit to search all formats. | |
| subject | No | Subject heading filter. Use the exact label from libofcongress_search_subjects results for best precision. Example: "World War, 1939-1945". | |
| date_end | No | End year for date filter, inclusive (e.g., 1930). Omit for no upper bound. | |
| location | No | Geographic location filter (e.g., "oklahoma", "washington d.c."). Lowercase, matches LOC location facets. | |
| date_start | No | Start year for date filter, inclusive (e.g., 1920). Omit for no lower bound. | |
| collection_slug | No | Scope the search to one curated collection. Use a slug exactly as returned by libofcongress_browse_collections (e.g., "aaron-copland") — slugs are not derivable from the collection title. Cannot be combined with format; omit format and read each result's format field instead. Omit to search all of LOC. |
| Name | Required | Description |
|---|---|---|
| page | No | Current 1-indexed page number. |
| error | No | Present when the call failed. Absent on success. |
| items | No | Item summaries matching the search query and filters. |
| pages | No | Total retrievable pages. For result sets larger than LOC will page through (~100,000 items) this is capped, and a notice discloses how to reach the rest (partition by date/subject/location). |
| total | No | Total number of matching items across all pages. |
| notice | No | Recovery hint when results are empty or a page is out of range — echoes applied filters and suggests how to broaden. Absent on successful result pages. |
| has_next | No | True when a retrievable next page follows this one. Never promises a page past LOC's ~100,000-item retrieval ceiling. |
| totalCount | No | Total matching items across all pages — mirrors output.total for agent reasoning. |
| effectiveQuery | No | The query as submitted to the LOC API, after trimming. |
| effectiveCollectionSlug | No | The collection the search was scoped to, after trimming. Absent when the search covered all of LOC. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses a non-obvious behavioral contract: some results are not items, carry no item record, and must be handled by opening their url. It also specifies that each result has an is_item flag, which is exactly the kind of detail an agent needs before invoking downstream tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense sentences, each earning its place: the first states scope, the second lists filters, the third explains return-value handling, and the fourth gives a prerequisite workflow. Information is front-loaded and no filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the high parameter count and five siblings, the description covers the non-obvious result-routing logic (is_item vs url) and a critical prerequisite (search_subjects for subject filters). With a full schema and output schema available, nothing agent-critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the structured schema already documents every parameter including the collection_slug constraint and subject-label requirement. The description echoes those points (subject heading spelling, collection_slug) without adding materially new parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Search the Library of Congress digital collections by keyword') and clarifies it returns item summaries. It implicitly distinguishes itself from libofcongress_get_item and libofcongress_search_subjects, but it never explicitly distinguishes itself from the sibling libofcongress_search_newspapers, so an agent may be unsure which newspaper search to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete workflow guidance: use libofcongress_search_subjects first for exact LCSH headings, route is_item=true results to libofcongress_get_item, and open the url for non-item results. It does not, however, state when to prefer this general search over libofcongress_search_newspapers or when to start from libofcongress_browse_collections.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search historical newspaper pages in the Chronicling America corpus. Returns matching pages with OCR text excerpts (~500 characters), publication title, date, the states LOC indexes the title under, and the page URL needed for libofcongress_get_newspaper_page. Filters by keyword, date range, US state, and newspaper title. The OCR excerpts are sufficient for relevance assessment — call libofcongress_get_newspaper_page with the returned url field to read the full page text. OCR quality varies: 19th-century and degraded materials may contain fragmented or garbled text.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number for paginating results. | |
| limit | No | Results per page. Default 25, max 100. | |
| query | Yes | Keyword search across OCR text and newspaper metadata. | |
| state | No | Filter to newspapers published in this US state. Use the full state name, lowercase (e.g., "oklahoma", "new york"). | |
| date_end | No | End year for date filter, inclusive (e.g., 1920). Omit for no upper bound. | |
| date_start | No | Start year for date filter, inclusive (e.g., 1900). Omit for no lower bound. | |
| newspaper_title | No | Filter to a specific newspaper by title (partial match accepted). |
| Name | Required | Description |
|---|---|---|
| page | No | Current 1-indexed page number. |
| error | No | Present when the call failed. Absent on success. |
| items | No | Newspaper page results matching the search query and filters. |
| pages | No | Total retrievable pages. For result sets larger than LOC will page through (~100,000 pages) this is capped, and a notice discloses how to reach the rest (partition by date/state). |
| total | No | Total number of matching newspaper pages in the result set. |
| notice | No | Recovery hint when results are empty or a page is out of range — echoes applied filters and suggests how to broaden. Absent on successful result pages. |
| has_next | No | True when a retrievable next page follows this one. Never promises a page past LOC's ~100,000-item retrieval ceiling. |
| totalCount | No | Total matching newspaper pages — mirrors output.total for agent reasoning. |
| effectiveQuery | No | The keyword query as submitted to the Chronicling America API, after trimming. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, lowering the burden on the description. The description adds useful behavioral nuance beyond annotations: it discloses the ~500-character OCR excerpt length, the specific returned fields, and the caveat that 19th-century/degraded materials may contain fragmented or garbled text. This is meaningful transparency without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: purpose, return contents, filter capabilities, downstream usage, and a quality caveat. Every sentence adds useful information, with no repetition of schema details and no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover the read-only/open-world profile, the description is complete enough for correct invocation. It explains what results look like, how to use the returned url, and warns about OCR quality, leaving no essential gap for an agent deciding to call this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all seven parameters. The description adds a high-level summary of filter dimensions ('keyword, date range, US state, and newspaper title') but does not add meaning beyond what the parameter descriptions already provide. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search historical newspaper pages in the Chronicling America corpus.' It clearly distinguishes this tool from siblings by focusing on newspapers and by naming the companion tool libofcongress_get_newspaper_page, so an agent can tell it apart from the generic libofcongress_search or libofcongress_search_subjects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: for keyword, date, state, and title filtering over newspaper pages. It also explains the relationship with libofcongress_get_newspaper_page, saying the returned url field is needed to read full page text, and that OCR excerpts are sufficient for relevance assessment. It does not explicitly exclude sibling tools, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Library of Congress Subject Headings (LCSH) by keyword. Returns controlled-vocabulary subject labels and their URIs. Use the returned label as the subject filter in libofcongress_search — LCSH uses precise, standardized terms that differ from natural language (e.g., "World War, 1939-1945" not "World War II"; "Photography, Aerial" not "Aerial photography"). Running this tool before a subject-filtered libofcongress_search dramatically improves result quality.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of subject headings to return. Default 10, max 50. | |
| query | Yes | Keyword or partial subject heading to search for (e.g., "civil war", "immigration", "jazz"). |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this response — maximum headings the API will return. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of subject headings returned in this response. |
| total | No | Number of subject headings returned. |
| notice | No | Recovery hint when results are empty, or when the upstream candidate cap under-filled the request. Distinguishes "exhausted by ranking" (retry with a more specific query) from "no LCSH coverage", and suggests inverted-form strategies. Absent when the full requested set was returned. |
| subjects | No | LCSH subject headings matching the query, ordered by relevance. To see how many LOC items carry a heading, pass its label as the libofcongress_search subject filter and read total. |
| truncated | No | True when results were capped at the requested limit. Increase limit or refine the query to surface additional headings. |
| effectiveQuery | No | The keyword query as submitted to the id.loc.gov suggest endpoint, after trimming. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only and open-world. The description adds meaningful behavioral context by disclosing that LCSH terms are standardized and differ from natural language, and by stating the return value shape (labels and URIs). It doesn't discuss pagination or response size, but the output schema and limit parameter cover enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, with the action and deliverable front-loaded and a well-placed example pair. The closing sentence is partly persuasive ('dramatically improves result quality') but reinforces the usage guidance rather than adding clutter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only lookup with a full input and output schema, the description is complete: it covers what the tool finds, what it returns, why the vocabulary differs from natural language, and how to chain it into libofcongress_search. No critical calling information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both query and limit carry clear descriptions, so the description need not repeat them. It adds example natural-language queries and clarifies that the returned label, not the raw query, should be used downstream, but this is usage context rather than new parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search Library of Congress Subject Headings (LCSH) by keyword.' It then states the concrete deliverable ('controlled-vocabulary subject labels and their URIs'), which clearly separates this vocabulary-lookup tool from the general libofcongress_search sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit when-to-use directive: 'Use the returned label as the subject filter in libofcongress_search' and says running it before a subject-filtered search improves quality. It also teaches the key distinction with examples ('World War, 1939-1945' not 'World War II'), so an agent knows not to pass natural-language terms directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
libofcongress_get_item3 fields changedInput schema / properties / item_id / descriptionPrevious value: -"LOC item id from a libofcongress_search result's \"id\" field (where is_item is true). A simple ID (\"2009632251\", \"loc.pnp.ppmsc.02404\") or a slash-separated path for newspaper pages (\"sn95047246/1935-09-05/ed-1\"). Pass the id verbatim; do not prepend the loc.gov URL or an \"item/\" prefix."New value: +"LOC item id from a libofcongress_search result's \"id\" field (where is_item is true). A simple ID (\"2009632251\", \"2005691065\") or a slash-separated path for newspaper pages (\"sn95047246/1935-09-05/ed-1\"). Pass the id verbatim; do not prepend the loc.gov URL or an \"item/\" prefix."Output schema / properties / contributors / descriptionPrevious value: -"Names of contributors, creators, or photographers."New value: +"Contributors, creators, or photographers as LOC catalogs them, role included (e.g., \"Washington, George, 1732-1799 (Author)\"). One person can appear once per role. Empty when LOC lists none."Output schema / properties / related_items / descriptionPrevious value: -"IDs or URLs of related LOC items for follow-up retrieval."New value: +"IDs or URLs of related LOC records for follow-up retrieval; a title stands in for a related record LOC gives neither for."libofcongress_get_newspaper_page9 fields changedOutput schema / properties / date / descriptionPrevious value: -"Issue publication date."New value: +"Issue publication date (YYYY-MM-DD)."Output schema / properties / edition / descriptionPrevious value: -"Edition or publication context identifier."New value: +"Edition number of the issue (e.g., \"1\"). Absent when LOC gives none."Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"Machine-readable failure mode. Declared by this tool: `page_not_found`: The URL does not resolve to a valid LOC newspaper page resource. `rate_limit_exceeded`: LOC API rate limit exceeded; requests are blocked for approximately 1 hour. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_page_url`: page_url does not begin with https://www.loc.gov/resource/. `page_not_found`: The URL does not resolve to a valid LOC newspaper page resource. `rate_limit_exceeded`: LOC API rate limit exceeded; requests are blocked for approximately 1 hour. Other values are possible when a failure originates below the handler."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "page_not_found",
- "rate_limit_exceeded"
-]New value: +[
+ "invalid_page_url",
+ "page_not_found",
+ "rate_limit_exceeded"
+]Output schema / properties / newspaper_title / descriptionPrevious value: -"Title of the newspaper publication."New value: +"Title of the newspaper publication. Absent when LOC gives none."Output schema / properties / place_of_publicationAdded value: +{
+ "description": "Where the newspaper was published, as LOC catalogs it (e.g., \"Charleston, S.C.\"). Absent when LOC gives none.",
+ "type": "string"
+}Output schema / properties / segment_countAdded value: +{
+ "description": "Number of pages in the issue. Absent when LOC gives none.",
+ "type": "number"
+}Output schema / properties / stateRemoved value: -{
- "description": "State where the newspaper was published.",
- "type": "string"
-}Output schema / properties / statesAdded value: +{
+ "description": "Every US state LOC indexes this newspaper title under (e.g., [\"georgia\", \"south carolina\"]), in LOC order — possibly more than the state of publication. Absent when LOC lists no state.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}libofcongress_search2 fields changedOutput schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"Machine-readable failure mode. Declared by this tool: `incompatible_filters`: format and collection_slug were both supplied; each selects a different LOC endpoint, so only one can apply. `collection_not_found`: collection_slug does not resolve to a LOC collection. `rate_limit_exceeded`: LOC API rate limit exceeded; requests are blocked for approximately 1 hour. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: date_start is later than date_end. `incompatible_filters`: format and collection_slug were both supplied; each selects a different LOC endpoint, so only one can apply. `collection_not_found`: collection_slug does not resolve to a LOC collection. Reported on page 1; a later page gets the out-of-range notice, since LOC answers both cases the same way there. `rate_limit_exceeded`: LOC API rate limit exceeded; requests are blocked for approximately 1 hour. Other values are possible when a failure originates below the handler."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "incompatible_filters",
- "collection_not_found",
- "rate_limit_exceeded"
-]New value: +[
+ "invalid_date_range",
+ "incompatible_filters",
+ "collection_not_found",
+ "rate_limit_exceeded"
+]libofcongress_search_newspapers4 fields changedOutput schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"Machine-readable failure mode. Declared by this tool: `rate_limit_exceeded`: LOC API rate limit exceeded; requests are blocked for approximately 1 hour. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: date_start is later than date_end. `rate_limit_exceeded`: LOC API rate limit exceeded; requests are blocked for approximately 1 hour. Other values are possible when a failure originates below the handler."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "rate_limit_exceeded"
-]New value: +[
+ "invalid_date_range",
+ "rate_limit_exceeded"
+]Output schema / properties / items / items / properties / stateRemoved value: -{
- "description": "State where the newspaper was published.",
- "type": "string"
-}Output schema / properties / items / items / properties / statesAdded value: +{
+ "description": "Every US state LOC indexes this newspaper title under (e.g., [\"georgia\", \"south carolina\"]), in LOC order. A title indexed against its circulation area lists several, so no entry is necessarily the place of publication — libofcongress_get_newspaper_page returns place_of_publication. Absent when LOC lists no state.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}libofcongress_search_subjects2 fields changedOutput schema / properties / subjects / descriptionPrevious value: -"LCSH subject headings matching the query, ordered by relevance."New value: +"LCSH subject headings matching the query, ordered by relevance. To see how many LOC items carry a heading, pass its label as the libofcongress_search subject filter and read total."Output schema / properties / subjects / items / properties / countRemoved value: -{
- "description": "Approximate number of LOC items carrying this heading. Omitted when unavailable.",
- "type": "number"
-}libofcongress_browse_collectionslibofcongress_get_itemlibofcongress_get_newspaper_pagelibofcongress_searchlibofcongress_search_newspaperslibofcongress_search_subjectsChronicling America MCP — full-text search of ~150 years of digitized U.S.
Search 14.5M Smithsonian Open Access objects, get CC0 images, find cross-collection connections.
US National Archives Catalog (NARA): search the federal government's permanent records…
Search books and authors across Open Library, the Internet Archive open catalog.
Add one secure layer between your agents and this server.