Skip to main content
Glama

libofcongress-mcp-server

Search LOC Items

libofcongress_search_items
Read-only

Search the Library of Congress digital collections by keyword. Optionally filter by material format (photos, maps, newspapers, audio, etc.), date range, subject heading, geographic location, or contributor (a creator, photographer, author, or other credited name), or scope the search to a single curated collection with collection_slug. Returns item summaries with titles, dates, descriptions, LOC IDs, format tags, and the contributors LOC credits. Each result carries is_item: pass the id of a result where is_item is true to libofcongress_get_item for full metadata. Non-item resources include collections, exhibit and research-guide pages, newspaper pages, catalog.loc.gov records, and hdl.loc.gov finding aids. When page_url is present, pass it to libofcongress_get_newspaper_page, optionally using the search query as match; its item_id identifies the issue. A link_notice warns that a retired catalog URL no longer opens its record; otherwise follow a non-item url. Use libofcongress_search_subjects to find an LCSH heading for the subject filter. To discover the subject, location, and contributor values the filters accept for a search, set include_facets to get its top subject_facets, location_facets, and contributor_facets.

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": {
      "query": "<query>"
    },
    "name": "libofcongress_search_items"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNo1-indexed page number for paginating results.
sortNoResult order: relevance (default), date (oldest first), or date_desc (newest first). Uses LOC catalog dates and upstream ordering.relevance
limitNoResults per page. Default 25. A page holds at most 100 results: a larger limit (up to 1000) is served as a 100-result page, and page then counts 100-result pages.
queryYesFull-text search across metadata and available descriptive text. Use "*" to match all records within the applied filters; relevance order can differ from a queryless LOC browse.
formatNoMaterial type filter. Options: photo, map, newspaper, manuscript, audio, film, book, notated-music. Omit to search all formats.
subjectNoSubject filter: an LCSH heading from libofcongress_search_subjects (e.g., "World War, 1939-1945", "United States--History--Civil War, 1861-1865") or a subject term from subject_facets (include_facets) or libofcongress_get_item subject_terms (e.g., "world war"). LOC indexes headings by their parts, so the value is split at "--" into lowercase terms with dates dropped, and an item must carry every term.
date_endNoEnd year for date filter, inclusive (e.g., 1930). Omit to run through the current year.
locationNoGeographic location filter (e.g., "oklahoma", "washington d.c."). Lowercase, matches LOC location facets; location_facets (include_facets) lists values for a search.
date_startNoStart year for date filter, inclusive (e.g., 1920). Omit for no lower bound.
contributorNoContributor filter: a creator, photographer, author, or other name LOC credits, in the form LOC indexes it, without dates or roles (e.g., "lange, dorothea", "united states. farm security administration"). Take values from contributor_facets (include_facets), a result's contributor_terms, or libofcongress_get_item contributor_terms; libofcongress_get_item contributors, which carry dates and roles, match nothing. Case is ignored; every other character must match, accents included. With format "newspaper", a page's contributor is the institution that digitized it, not an author.
include_facetsNoAlso return subject_facets, location_facets, and contributor_facets: LOC's top subject, location, and contributor terms across every match, with counts — the values the subject, location, and contributor filters accept. Default false: facets add time to each search, so request them when you need filter values to narrow by.
collection_slugNoScope the search to one curated collection. Pass a slug exactly as returned by libofcongress_browse_collections to libofcongress_search_items.collection_slug (e.g., "aaron-copland") — slugs are not derivable from the collection title. Combine with format to filter material type; use query "*" to browse every matching record. Omit to search all of LOC.

Output Schema

NameRequiredDescriptionDefault
pageNoCurrent 1-indexed page number.
errorNoPresent when the call failed. Absent on success.
itemsNoItem summaries matching the search query and filters.
pagesNoTotal 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).
totalNoTotal number of matching items across all pages.
noticeNoRecovery hint when results are empty or a page is out of range — echoes applied filters, subject terms, location, and contributor included, and suggests how to broaden — plus disclosure of a capped limit or of the retrieval ceiling. Absent on ordinary result pages.
has_nextNoTrue when a retrievable next page follows this one. Never promises a page past LOC's ~100,000-item retrieval ceiling.
totalCountNoTotal matching items across all pages — mirrors output.total for agent reasoning.
effectiveSortNoApplied LOC result order, including empty and out-of-range pages.
effectiveLimitNoThe page size actually served when limit exceeded the per-call cap of 100. Absent when limit was within the cap.
effectiveQueryNoThe query as submitted to the LOC API, after trimming.
subject_facetsNoLOC's top subject terms across every item matching this search (up to 10), most frequent first. Pass a value as the subject filter to narrow the search. Present only when include_facets is true; empty when LOC reports none.
location_facetsNoLOC's top location terms across every item matching this search (up to 10), most frequent first. Pass a value as the location filter to narrow the search. Present only when include_facets is true; empty when LOC reports none.
contributor_facetsNoLOC's top contributor terms across every item matching this search (up to 10), most frequent first. Pass a value as the contributor filter to narrow the search. Present only when include_facets is true; empty when LOC reports none. On newspaper pages the contributor is the institution that digitized the page, so institutions can appear here beside creators.
effectiveSubjectTermsNoThe subject terms the subject filter was sent as, all required to match. Absent when no subject filter was given.
effectiveCollectionSlugNoThe collection the search was scoped to, after trimming. Absent when the search covered all of LOC.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • addedInput schema / properties / contributor
      Added value: +{
      +  "description": "Contributor filter: a creator, photographer, author, or other name LOC credits, in the form LOC indexes it, without dates or roles (e.g., \"lange, dorothea\", \"united states. farm security administration\"). Take values from contributor_facets (include_facets), a result's contributor_terms, or libofcongress_get_item contributor_terms; libofcongress_get_item contributors, which carry dates and roles, match nothing. Case is ignored; every other character must match, accents included. With format \"newspaper\", a page's contributor is the institution that digitized it, not an author.",
      +  "type": "string"
      +}
    • changedInput schema / properties / include_facets / description
      Previous value: -"Also return subject_facets and location_facets: LOC's top subject and location terms across every match, with counts — the values the subject and location filters accept. Default false: facets add time to each search, so request them when you need filter values to narrow by."New value: +"Also return subject_facets, location_facets, and contributor_facets: LOC's top subject, location, and contributor terms across every match, with counts — the values the subject, location, and contributor filters accept. Default false: facets add time to each search, so request them when you need filter values to narrow by."
    • addedOutput schema / properties / contributor_facets
      Added value: +{
      +  "description": "LOC's top contributor terms across every item matching this search (up to 10), most frequent first. Pass a value as the contributor filter to narrow the search. Present only when include_facets is true; empty when LOC reports none. On newspaper pages the contributor is the institution that digitized the page, so institutions can appear here beside creators.",
      +  "items": {
      +    "additionalProperties": false,
      +    "description": "One contributor facet value.",
      +    "properties": {
      +      "count": {
      +        "description": "Matching items carrying this contributor term.",
      +        "type": "number"
      +      },
      +      "value": {
      +        "description": "The contributor term, as the contributor filter accepts it.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "value",
      +      "count"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: date_start is later than date_end, or date_start is given alone and is later than the current year. `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. `server_busy`: More Library of Congress requests are queued on this server than can start within this call's time budget. `request_timed_out`: The Library of Congress did not respond within the 50-second request budget. `upstream_unavailable`: The Library of Congress could not be reached, or answered with an error status, a bot challenge or other HTML page, or an unreadable response instead of its JSON. 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, or date_start is given alone and is later than the current year. `invalid_filter_value`: A subject, location, or contributor value has \"|\" between other characters, which the Library of Congress reads as a separator between filters. A \"|\" at either end of a value is dropped. `query_too_long`: The Library of Congress refused the search as too long (HTTP 414), which an over-long query causes. `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. `server_busy`: More Library of Congress requests are queued on this server than can start within this call's time budget. `request_timed_out`: The Library of Congress did not respond within the 50-second request budget. `upstream_unavailable`: The Library of Congress could not be reached, or answered with an error status, a bot challenge or other HTML page, or an unreadable response instead of its JSON. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_date_range",
      -  "collection_not_found",
      -  "rate_limit_exceeded",
      -  "server_busy",
      -  "request_timed_out",
      -  "upstream_unavailable"
      -]New value: +[
      +  "invalid_date_range",
      +  "invalid_filter_value",
      +  "query_too_long",
      +  "collection_not_found",
      +  "rate_limit_exceeded",
      +  "server_busy",
      +  "request_timed_out",
      +  "upstream_unavailable"
      +]
    • addedOutput schema / properties / items / items / properties / contributor_terms
      Added value: +{
      +  "description": "Every contributor LOC credits this result with, in LOC order, each in the form the contributor filter accepts (e.g., \"lange, dorothea\"). On a newspaper page, the institution that digitized it. Absent when LOC credits none.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / items / items / properties / date / description
      Previous value: -"Publication or creation date as LOC catalogs it: free text, a year, or a full date (e.g., \"c1915 Feb. 19.\", \"1912\"). Absent when LOC records only a coded value (\"uuuu\", \"||||\") or none."New value: +"Publication or creation date as LOC catalogs it: free text, a year, a year and month, or a full date (e.g., \"c1915 Feb. 19.\", \"1912\", \"1863-11\", \"1863-11-20\"). Absent when LOC records only a coded value (\"uuuu\", \"||||\") or none."
    • changedOutput schema / properties / notice / description
      Previous value: -"Recovery hint when results are empty or a page is out of range — echoes applied filters, subject terms and location included, and suggests how to broaden — plus disclosure of a capped limit or of the retrieval ceiling. Absent on ordinary result pages."New value: +"Recovery hint when results are empty or a page is out of range — echoes applied filters, subject terms, location, and contributor included, and suggests how to broaden — plus disclosure of a capped limit or of the retrieval ceiling. Absent on ordinary result pages."
  2. Changed12 schema fields changed
    • changedInput schema / properties / collection_slug / description
      Previous value: -"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."New value: +"Scope the search to one curated collection. Pass a slug exactly as returned by libofcongress_browse_collections to libofcongress_search_items.collection_slug (e.g., \"aaron-copland\") — slugs are not derivable from the collection title. Combine with format to filter material type; use query \"*\" to browse every matching record. Omit to search all of LOC."
    • changedInput schema / properties / query / description
      Previous value: -"Full-text search across metadata and available descriptive text."New value: +"Full-text search across metadata and available descriptive text. Use \"*\" to match all records within the applied filters; relevance order can differ from a queryless LOC browse."
    • addedInput schema / properties / sort
      Added value: +{
      +  "default": "relevance",
      +  "description": "Result order: relevance (default), date (oldest first), or date_desc (newest first). Uses LOC catalog dates and upstream ordering.",
      +  "enum": [
      +    "relevance",
      +    "date",
      +    "date_desc"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "items",
      -      "total",
      -      "page",
      -      "pages",
      -      "has_next",
      -      "effectiveQuery",
      -      "totalCount"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "items",
      +      "total",
      +      "page",
      +      "pages",
      +      "has_next",
      +      "effectiveSort",
      +      "effectiveQuery",
      +      "totalCount"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / effectiveSort
      Added value: +{
      +  "description": "Applied LOC result order, including empty and out-of-range pages.",
      +  "enum": [
      +    "relevance",
      +    "date",
      +    "date_desc"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: date_start is later than date_end, or date_start is given alone and is later than the current year. `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. `server_busy`: More Library of Congress requests are queued on this server than can start within this call's time budget. `request_timed_out`: The Library of Congress did not respond within the 50-second request budget. `upstream_unavailable`: The Library of Congress could not be reached, or answered with an error status, a bot challenge or other HTML page, or an unreadable response instead of its JSON. 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, or date_start is given alone and is later than the current year. `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. `server_busy`: More Library of Congress requests are queued on this server than can start within this call's time budget. `request_timed_out`: The Library of Congress did not respond within the 50-second request budget. `upstream_unavailable`: The Library of Congress could not be reached, or answered with an error status, a bot challenge or other HTML page, or an unreadable response instead of its JSON. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_date_range",
      -  "incompatible_filters",
      -  "collection_not_found",
      -  "rate_limit_exceeded",
      -  "server_busy",
      -  "request_timed_out",
      -  "upstream_unavailable"
      -]New value: +[
      +  "invalid_date_range",
      +  "collection_not_found",
      +  "rate_limit_exceeded",
      +  "server_busy",
      +  "request_timed_out",
      +  "upstream_unavailable"
      +]
    • changedOutput schema / properties / items / items / properties / id / description
      Previous value: -"LOC identifier for this result: an item ID, or the bare LCCN of a record whose url is an lccn.loc.gov permalink. When is_item is true, pass it to libofcongress_get_item for full metadata. When is_item is false it is a non-item resource (a collection, exhibit, guide, newspaper page, catalog.loc.gov record, or hdl.loc.gov finding aid), not a get_item input — open url instead."New value: +"LOC identifier for this result: an item ID, or the bare LCCN of a record whose url is an lccn.loc.gov permalink. When is_item is true, pass it to libofcongress_get_item for full metadata. When is_item is false it is a non-item resource (a collection, exhibit, guide, newspaper page, catalog.loc.gov record, or hdl.loc.gov finding aid), not a get_item input. Use page_url for newspaper pages, heed link_notice for retired links, and otherwise follow url."
    • changedOutput schema / properties / items / items / properties / is_item / description
      Previous value: -"True when this result is a catalog item whose id resolves through libofcongress_get_item, including records LOC links by an lccn.loc.gov permalink. False for collections, exhibits, research guides, newspaper pages, catalog.loc.gov records, hdl.loc.gov finding aids, and other non-item results, which have no get_item record — follow url instead. Always present on every result."New value: +"True when this result is a catalog item whose id resolves through libofcongress_get_item, including records LOC links by an lccn.loc.gov permalink. False for collections, exhibits, research guides, newspaper pages, catalog.loc.gov records, hdl.loc.gov finding aids, and other non-item results, which have no get_item record. Use page_url for newspaper pages, heed link_notice for retired links, and otherwise follow url. Always present on every result."
    • addedOutput schema / properties / items / items / properties / link_notice
      Added value: +{
      +  "description": "Warning that a retired catalog URL no longer opens its record; no replacement record URL is known.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / page_url
      Added value: +{
      +  "description": "Recognized newspaper page URL: pass to libofcongress_get_newspaper_page as page_url, optionally with this search query as match. That tool returns item_id for the issue.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / items / items / properties / url / description
      Previous value: -"LOC item or collection URL."New value: +"Original LOC result URL, preserved even when retired; read link_notice before following it."
  3. Changed3 schema fields changed
    • changedOutput schema / properties / items / items / properties / date / description
      Previous value: -"Publication or creation date as LOC catalogs it: free text, a year, or a full date (e.g., \"c1915 Feb. 19.\", \"1912\")."New value: +"Publication or creation date as LOC catalogs it: free text, a year, or a full date (e.g., \"c1915 Feb. 19.\", \"1912\"). Absent when LOC records only a coded value (\"uuuu\", \"||||\") or none."
    • changedOutput schema / properties / items / items / properties / id / description
      Previous value: -"LOC identifier for this result. When is_item is true, pass it to libofcongress_get_item for full metadata. When is_item is false it is a non-item resource (a collection, exhibit, guide, or newspaper page), not a get_item input — open url instead."New value: +"LOC identifier for this result: an item ID, or the bare LCCN of a record whose url is an lccn.loc.gov permalink. When is_item is true, pass it to libofcongress_get_item for full metadata. When is_item is false it is a non-item resource (a collection, exhibit, guide, newspaper page, catalog.loc.gov record, or hdl.loc.gov finding aid), not a get_item input — open url instead."
    • changedOutput schema / properties / items / items / properties / is_item / description
      Previous value: -"True when this result is a catalog item whose id resolves through libofcongress_get_item. False for collections, exhibits, research guides, newspaper pages, and other non-item results, which have no get_item record — follow url instead. Always present on every result."New value: +"True when this result is a catalog item whose id resolves through libofcongress_get_item, including records LOC links by an lccn.loc.gov permalink. False for collections, exhibits, research guides, newspaper pages, catalog.loc.gov records, hdl.loc.gov finding aids, and other non-item results, which have no get_item record — follow url instead. Always present on every result."
  4. Changed14 schema fields changed
    • changedInput schema / properties / date_end / description
      Previous value: -"End year for date filter, inclusive (e.g., 1930). Omit for no upper bound."New value: +"End year for date filter, inclusive (e.g., 1930). Omit to run through the current year."
    • addedInput schema / properties / include_facets
      Added value: +{
      +  "default": false,
      +  "description": "Also return subject_facets and location_facets: LOC's top subject and location terms across every match, with counts — the values the subject and location filters accept. Default false: facets add time to each search, so request them when you need filter values to narrow by.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / limit / description
      Previous value: -"Results per page. Default 25, max 100."New value: +"Results per page. Default 25. A page holds at most 100 results: a larger limit (up to 1000) is served as a 100-result page, and page then counts 100-result pages."
    • changedInput schema / properties / limit / maximum
      Previous value: -100New value: +1000
    • changedInput schema / properties / location / description
      Previous value: -"Geographic location filter (e.g., \"oklahoma\", \"washington d.c.\"). Lowercase, matches LOC location facets."New value: +"Geographic location filter (e.g., \"oklahoma\", \"washington d.c.\"). Lowercase, matches LOC location facets; location_facets (include_facets) lists values for a search."
    • changedInput schema / properties / subject / description
      Previous value: -"Subject heading filter. Use the exact label from libofcongress_search_subjects results for best precision. Example: \"World War, 1939-1945\"."New value: +"Subject filter: an LCSH heading from libofcongress_search_subjects (e.g., \"World War, 1939-1945\", \"United States--History--Civil War, 1861-1865\") or a subject term from subject_facets (include_facets) or libofcongress_get_item subject_terms (e.g., \"world war\"). LOC indexes headings by their parts, so the value is split at \"--\" into lowercase terms with dates dropped, and an item must carry every term."
    • addedOutput schema / properties / effectiveLimit
      Added value: +{
      +  "description": "The page size actually served when limit exceeded the per-call cap of 100. Absent when limit was within the cap.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / effectiveSubjectTerms
      Added value: +{
      +  "description": "The subject terms the subject filter was sent as, all required to match. Absent when no subject filter was given.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous 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. `server_busy`: More Library of Congress requests are queued on this server than can start within this call's time budget. `request_timed_out`: The Library of Congress did not respond within the 50-second request budget. 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, or date_start is given alone and is later than the current year. `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. `server_busy`: More Library of Congress requests are queued on this server than can start within this call's time budget. `request_timed_out`: The Library of Congress did not respond within the 50-second request budget. `upstream_unavailable`: The Library of Congress could not be reached, or answered with an error status, a bot challenge or other HTML page, or an unreadable response instead of its JSON. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_date_range",
      -  "incompatible_filters",
      -  "collection_not_found",
      -  "rate_limit_exceeded",
      -  "server_busy",
      -  "request_timed_out"
      -]New value: +[
      +  "invalid_date_range",
      +  "incompatible_filters",
      +  "collection_not_found",
      +  "rate_limit_exceeded",
      +  "server_busy",
      +  "request_timed_out",
      +  "upstream_unavailable"
      +]
    • changedOutput schema / properties / items / items / properties / date / description
      Previous value: -"Publication or creation date."New value: +"Publication or creation date as LOC catalogs it: free text, a year, or a full date (e.g., \"c1915 Feb. 19.\", \"1912\")."
    • addedOutput schema / properties / location_facets
      Added value: +{
      +  "description": "LOC's top location terms across every item matching this search (up to 10), most frequent first. Pass a value as the location filter to narrow the search. Present only when include_facets is true; empty when LOC reports none.",
      +  "items": {
      +    "additionalProperties": false,
      +    "description": "One location facet value.",
      +    "properties": {
      +      "count": {
      +        "description": "Matching items carrying this location term.",
      +        "type": "number"
      +      },
      +      "value": {
      +        "description": "The location term, as the location filter accepts it.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "value",
      +      "count"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"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."New value: +"Recovery hint when results are empty or a page is out of range — echoes applied filters, subject terms and location included, and suggests how to broaden — plus disclosure of a capped limit or of the retrieval ceiling. Absent on ordinary result pages."
    • addedOutput schema / properties / subject_facets
      Added value: +{
      +  "description": "LOC's top subject terms across every item matching this search (up to 10), most frequent first. Pass a value as the subject filter to narrow the search. Present only when include_facets is true; empty when LOC reports none.",
      +  "items": {
      +    "additionalProperties": false,
      +    "description": "One subject facet value.",
      +    "properties": {
      +      "count": {
      +        "description": "Matching items carrying this subject term.",
      +        "type": "number"
      +      },
      +      "value": {
      +        "description": "The subject term, as the subject filter accepts it.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "value",
      +      "count"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  5. Added

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, so the description's added value is in result semantics: the is_item discriminator, the list of non-item resource types, the link_notice warning for retired URLs, and the fact that facets cost extra time per search. It stops short of describing error conditions or result-size limits in prose (the limit behavior lives in the schema), which keeps it below a 5.

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?

Purpose is front-loaded and nearly every sentence carries actionable routing or result-parsing information, which is defensible for a 12-parameter tool. It is delivered as one undifferentiated block, mixing return-value parsing with filter discovery, so structure could be tighter even though little is wasted.

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?

For a broad search tool with an output schema, this covers the full lifecycle: how to scope, how to discover facet values, how to interpret is_item and page_url results, and which sibling to call next. Nothing an agent needs in order to call it correctly or consume its output is missing.

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?

With 100% schema coverage the baseline is 3, but the description adds cross-tool meaning: it tells the agent where accepted values for subject, location, and contributor come from (search_subjects, facets, get_item terms) and warns that get_item contributors with dates and roles match nothing. That is genuine guidance beyond the schema's own per-parameter text.

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?

Opens with a specific verb and resource ("Search the Library of Congress digital collections by keyword") and immediately names the filters that scope it. It is clearly distinguishable from siblings search_subjects, get_item, get_newspaper_page, and browse_collections, each of which is invoked for a different purpose in the same paragraph.

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?

Gives explicit routing: pass is_item=true ids to get_item, pass page_url to get_newspaper_page, use search_subjects to obtain an LCSH heading, use browse_collections for a collection_slug, and set include_facets when filter values are unknown. These are concrete when-to-use-this-vs-alternative instructions rather than implied usage.

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.