Skip to main content
Glama

Search records with filters

search_records
Read-onlyIdempotent

Search the archive with filters for collection, shelf (sub_collection), kind (media_type: document, image, video or audio), HABS/HAER survey number, entity, content type, island and year. Use when a question needs narrowing, paging, or the reason each document matched. Searches the full extracted text of the archive's documents, plus their catalogue records. Filters use the same vocabulary as the website's own facets. Every result carries a tier, a plain reason and the search terms it actually matched; there is no numeric relevance score. The tiers: exact = every term, found in the document's title or issuing entity (likely about the subject); strong = every term, in the text only (it mentions them); possible = at least half the terms; weak = fewer. When no document contains all the terms, results contain some of them and the response says so, and 'matched' lists which. Not covered: the archive's newspapers (the St. Croix Avis, The West End News, Home Journal and the St. Croix Tribune) and the Danish West Indies papers it opens for search, which are on its separate newspaper connector (the 2026 Virgin Islands Code is here, in search_code and get_code_section); and anything the archive has not published. Withheld and withdrawn documents are absent, not hidden.

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": "search_records"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoDefault 10, maximum 50.
queryYesPlain language is fine. Quote a phrase to require it intact.
entityNoThe issuing or subject body, exactly as recorded, e.g. "Water and Power Authority". Recorded on only part of the archive; archive_stats gives the share.
islandNoe.g. "St. Croix", "St. Thomas", "St. John"
offsetNoResults to skip, for paging. Results are ranked within the best 120 documents.
surveyNoA Historic American Buildings Survey or Engineering Record number, e.g. "HABS VI-3" or "HAER VI-2-A": every photograph, drawing and written record of that survey. A search query is still needed; the building name works.
year_toNoLatest year, inclusive. The year_from note on dates applies.
year_fromNoEarliest year, inclusive. Filters on the date the archive recorded, whose provenance varies by source: for most documents it is the date on the document, for some it is when the source posted the file. A year range can therefore miss a document executed in one year and posted the next, so it narrows rather than guarantees.
collectionNoe.g. "Courts", "Audits & Oversight"
media_typeNoThe kind of item: "image" (photographs, drawings, maps, plates), "video" (film), "audio" (recordings) or "document".
content_typeNoThe kind of document, exactly as recorded, e.g. "government-audit". An unknown value returns the nearest values that exist.
sub_collectionNoA shelf within a collection, exactly as recorded, e.g. "HABS/HAER Building Surveys" or "Internet Archive (V.I. texts)". list_collections gives every shelf.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / media_type
      Added value: +{
      +  "description": "The kind of item: \"image\" (photographs, drawings, maps, plates), \"video\" (film), \"audio\" (recordings) or \"document\".",
      +  "enum": [
      +    "document",
      +    "image",
      +    "video",
      +    "audio"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / sub_collection
      Added value: +{
      +  "description": "A shelf within a collection, exactly as recorded, e.g. \"HABS/HAER Building Surveys\" or \"Internet Archive (V.I. texts)\". list_collections gives every shelf.",
      +  "type": "string"
      +}
    • addedInput schema / properties / survey
      Added value: +{
      +  "description": "A Historic American Buildings Survey or Engineering Record number, e.g. \"HABS VI-3\" or \"HAER VI-2-A\": every photograph, drawing and written record of that survey. A search query is still needed; the building name works.",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantial behavior: the four-tier ranking scheme with definitions, the explicit absence of a numeric relevance score, per-result 'tier', 'reason' and 'matched' fields, the degraded-results fallback when no document matches all terms, and the fact that withheld/withdrawn documents are absent rather than hidden. That is far beyond what the structured fields convey.

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 in the first sentence and every later block earns its place (tiers, fallback, exclusions). It is dense and the 'Not covered' sentence is a long run-on with nested parentheticals, including the full list of newspaper titles, which is more detail than the routing decision requires.

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 12-parameter search tool with no output schema, the description covers result shape, ranking semantics, paging caveat, partial-match behavior, and scope exclusions with alternative tools. An agent has everything needed to call it correctly and to interpret what comes back.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning on top: it maps colloquial filter names to schema keys, states that filters reuse the website's facet vocabulary (useful for constructing valid values), and explains that the ranking/cutoff that governs offset paging is not a numeric score. It does not add per-parameter value formats beyond what the schema already documents, which caps it below 5.

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 archive with filters') and enumerates the filter axes, mapping plain-language names onto schema fields (shelf = sub_collection, kind = media_type). It also carves out what it does not cover and names the tools that do (search_code, get_code_section, the newspaper connector), so an agent can distinguish it from siblings without opening a schema.

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

Usage Guidelines4/5

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

Explicitly states the selection condition ('Use when a question needs narrowing, paging, or the reason each document matched') and provides strong negative guidance via the 'Not covered' paragraph naming the newspaper connector and search_code/get_code_section. The one gap is that it never contrasts this tool with the sibling 'search', leaving the agent to infer which of the two general search entry points to pick.

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.

Resources