Search LOC digital collections, Chronicling America newspapers (full OCR), and LC Subject Headings.
Scored across 6 tools
Each tool has a clearly distinct purpose: browsing collections, retrieving item metadata, retrieving newspaper OCR text, searching general collections, searching newspapers, and searching subject headings. The descriptions explicitly cross-reference each other to guide selection, leaving no ambiguity about which tool fits a given task.
All tools follow a consistent libofcongress_ prefix with verb_noun naming (browse_collections, get_item, get_newspaper_page, search, search_newspapers, search_subjects). The pattern is uniform and predictable, with snake_case throughout.
Six tools is well-scoped for the server's purpose of exploring Library of Congress resources. Each tool addresses a distinct capability—search, browse, retrieval, and subject assistance—without redundancy or bloat, making the surface manageable for agents.
The tool set covers the core workflows: discovering collections, searching across formats, drilling into item details, and handling newspaper-specific data. Minor gaps exist (e.g., no direct tool for listing all newspapers or retrieving collection-level metadata beyond summary), but these are acceptable and do not block common user goals.
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", "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. |
| 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 | Names of contributors, creators, or photographers. |
| related_items | No | IDs or URLs of related LOC items for follow-up retrieval. |
| 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 establish readOnlyHint and openWorldHint, and the description adds valuable behavioral context: the exact id forms accepted, the instruction not to prepend the loc.gov URL, the detailed set of returned fields, and the conditional presence of digital-resource links. It stops short of describing not-found or error behavior, but that is a minor gap for a read-only retrieval tool.
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 front-loaded with the core purpose and then gives structured usage details. The enumerated return fields add length but provide useful expectations about what the full metadata record contains. It is somewhat dense, but every part earns its place with 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?
For a single-parameter retrieval tool with a rich output schema and annotations covering read-only behavior, the description is complete: it states when to call it, what input to pass, what the output includes, and which results are out of scope. Nothing critical is missing for an agent to invoke it 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 description coverage is 100%: the input schema already explains the id sources, simple-ID versus newspaper-path forms, verbatim passing, and the no-URL-prefix rule. The description reinforces the same guidance but adds no new parameter meaning beyond the schema, so the baseline of 3 applies.
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: 'Retrieve the full metadata record for a specific LOC digital item.' It distinguishes itself from search by requiring a prior libofcongress_search result and from newspaper-page retrieval by explicitly stating that non-item results such as newspaper pages have no item record and 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?
It gives an explicit workflow: 'Use after libofcongress_search on a result whose is_item is true.' It also gives a clear when-not condition, enumerating collections, exhibits, guides, and newspaper pages as invalid. The alternative for newspaper pages is inferable from the sibling list, and the exclusion is stated directly.
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. 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. |
| error | No | Present when the call failed. Absent on success. |
| state | No | State where the newspaper was published. |
| 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. |
| edition | No | Edition or publication context identifier. |
| 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. |
| newspaper_title | No | Title of the newspaper publication. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses meaningful behavior: OCR quality varies by batch/era, text may be fragmented or garbled, and missing OCR is represented as ocr_available=false with empty ocr_text and is explicitly not an error. This preempts likely misinterpretations by the agent.
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?
Three focused sentences with no filler. The primary purpose is front-loaded, the critical usage constraint is stated early, and the edge-case behavior is placed at the end without bloating the description.
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 read-only retrieval tool with an output schema and 100% schema coverage, the description covers everything needed: what is retrieved, how to obtain the URL, likely data-quality issues, and how to interpret empty OCR results. No essential guidance 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%, and the schema already documents the page_url parameter, including an example and an explicit warning not to modify the URL. The description reinforces the same guidance but adds no new semantic information beyond the schema, matching the baseline for full coverage.
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: 'Retrieve the full OCR text of a specific historical newspaper page along with publication metadata.' This clearly distinguishes it from the sibling search/browse tools and leaves no ambiguity about what the tool returns.
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 operational context by instructing the agent to pass the url field from a libofcongress_search_newspapers result and not to construct the URL manually. It implies the correct workflow, though it does not explicitly contrast this tool with siblings such as libofcongress_get_item.
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?
Annotations mark the tool as read-only, and the description adds useful behavioral context: results are item summaries, each carries an is_item flag, and non-item resources must be handled by opening their URL rather than requesting an item record. No contradiction with readOnlyHint or openWorldHint.
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 uses five sentences, each with a distinct job: search purpose, filter options, return content, result-handling workflow, and subject-filter prerequisite. It is front-loaded with the central verb and resource and contains 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?
For a 9-parameter search tool with an output schema, the description covers the essential return semantics and result routing, while the schema covers parameter details. It omits guidance about the sibling libofcongress_search_newspapers, which is relevant because this tool accepts 'newspaper' as a format.
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 baseline is 3; the description earns extra credit by explaining that subject headings must use exact LCSH spelling from libofcongress_search_subjects and by framing collection_slug as a scope limiter to a single curated collection. These hints go beyond the schema descriptions.
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 states a specific action: 'Search the Library of Congress digital collections by keyword,' and lists the available filters. It references several siblings such as libofcongress_get_item and libofcongress_search_subjects, but does not explicitly differentiate itself from libofcongress_search_newspapers even though 'newspaper' is an accepted format, leaving a small sibling ambiguity.
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 concrete routing guidance: use libofcongress_search_subjects first for subject filters, pass is_item-true IDs to libofcongress_get_item, and open the URL for non-item results. However, it does not say when to prefer the dedicated libofcongress_search_newspapers tool over this general search for newspaper queries.
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, state, 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 indicate read-only and open-world behavior. The description adds valuable behavioral context: excerpt length (~500 characters), the warning about OCR quality in 19th-century/degraded material, and the dependency relationship between this tool's url field and get_newspaper_page. It does not disclose ordering/sorting behavior, but that is likely covered by the output schema.
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?
Three sentences, each earning its place: the first states purpose and returns, the second gives routing guidance, and the third warns about data quality. Information is front-loaded; no filler or repetition.
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 7-parameter tool with a full output schema, the description covers everything an agent needs: what is searched, what is returned, how to proceed to the next step, and data quality caveats. Nothing essential 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 description coverage is 100%, so the baseline is 3. The description's summary of filters (keyword, date range, state, title) merely mirrors the schema; it adds no new parameter-specific meaning beyond what the property descriptions already provide.
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 states a specific verb ('Search'), a precise resource ('historical newspaper pages in the Chronicling America corpus'), and concrete return fields (OCR excerpts, title, date, state, URL). It clearly distinguishes this from the broader libofcongress_search and from libofcongress_get_newspaper_page by framing the page URL as the input to that 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?
The description gives explicit workflow guidance: OCR excerpts are sufficient for relevance assessment, and the returned url field should be passed to libofcongress_get_newspaper_page for full text. It gives context for when to stop at this tool, but it does not explicitly say when to prefer other siblings like libofcongress_search or search_subjects.
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. |
| 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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds valuable context: LCSH terms are standardized and differ from natural language, with concrete examples, and that the returned labels are meant to be fed into a downstream search. This goes beyond the annotations without contradicting them.
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 filler: it states the action, the return value, and the downstream usage rationale. The parenthetical examples are instructive rather than redundant, and the most important scoping information is front-loaded.
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 lookup tool with a full input schema, output schema present, and safety annotations, the description tells an agent everything needed to invoke it correctly: what to search, what it returns, and how to use the result. No critical context 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?
The input schema already documents both parameters with 100% coverage, including examples for query and constraints for limit. The description adds little parameter-specific meaning beyond calling the search 'by keyword,' so the baseline of 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 Library of Congress Subject Headings (LCSH) by keyword.' It clearly states the output (controlled-vocabulary subject labels and URIs) and distinguishes the tool's role from the sibling libofcongress_search by positioning this as the subject-term lookup step.
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 when-to-use guidance: run this tool before a subject-filtered libofcongress_search, and use the returned label as the subject filter. It does not enumerate when-not-to-use cases or compare against alternative lookups, so it stops short of a full 5.
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_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.
Search books and authors across Open Library, the Internet Archive open catalog.
Read-only OpenHeritage search for genealogy and cultural heritage records.
Add one secure layer between your agents and this server.