Skip to main content
Glama

Search every catalogue at once

search_items
Read-onlyIdempotent

Search multiple library catalogues at once by title, creator, or subject and get a merged result list with item IDs for retrieving full records.

Instructions

Search the catalogue of every archive this server reads, at the same time, for a title, a creator or a subject, and get one merged list. Each row carries the id get_item takes, and that id names the archive it came from, so nothing has to be guessed afterwards. 'media_type' keeps one name across the archives and a vocabulary per archive, because the same word does not name the same set of things twice. An archive that files nothing under the name you give is not asked and is named as absent, with its own names listed, rather than asked under a translation. An archive that keeps one catalogue per kind of material is asked for its default when you name none, and the answer says which catalogue that was. Rows are interleaved one archive at a time. No score orders them against each other, and 'sort' is applied inside each archive rather than across them: a year is the date of an edition in one place and the date on a catalogue record in another, so there is no date order that spans the answer. 'oldest' and 'newest' order on a date field carrying a year and no era, so a date before the common era is filed there as a year of this one, and a record stating no date is placed by a stand-in rather than by its age. The first row of a date order is therefore not established as the oldest or newest thing an archive holds, the notes count the rows carrying no year, and this server orders nothing itself. Every count in 'per_source' is that archive's own and counts something of its own. They are never added together, and there is no total across archives. The catalogues read the words given in different ways, and 'per_source' says which each one does. One answers only where every word appears, so a question written as a sentence comes back empty; another scores the words and answers with the records it ranks highest, so a row of its can carry only some of them. Either way it is the words: a character that is neither a letter nor a digit is no word to an index, and 'non_word_characters' lists any the query carried. A name is also filed under more than one spelling, so further wordings are derived from the query and asked for their union. It costs nothing extra when the words as asked already answer. Every wording sent is named in 'per_source' with what it returned, every row carries the wording that returned it in 'found_by_query', and 'fan_out' turns the derivation off. A row's 'media_type' is the word that record carries for the kind of thing, which is often none of the names this argument takes: those are the divisions of a catalogue, and 'media_types' publishes them per archive. A row states no terms of reuse. Read the record with get_item for what that record itself says, and read silence as silence. Use search_inside for a phrase printed on a page: this tool reads catalogue records and knows nothing of what a book says, so a sentence given here matches only where a catalogue happens to carry it. Answers take several seconds, because one of the archives publishes a request ceiling this server keeps to.

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_items"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoWhich page of rows, from 1. Each archive is paged separately.
sortNoApplied inside each archive. The merged list stays interleaved, because no order runs across archives. 'oldest' and 'newest' run on a date field carrying a year and no era, and a record stating no date is placed by a stand-in, so neither end of such an order is a claim about age.relevance
limitNoRows to take from each archive, so one archive cannot fill the whole list.
queryYesA title, a creator, a subject, or plain words.
fan_outNoWhether to derive further wordings from the query and ask each archive for the union of what they return. A question written as a sentence returns nothing where every word given has to appear, and the records an index scores highest where it does not, and a spelling of a name is not the only one a catalogue files it under. An archive is asked a derived wording only when the words as asked did not return as many rows as 'limit', so a query that works costs one request. Set false to send exactly the words given. 'per_source' names every wording, sent or not, and each row names the one that returned it.
sourcesNoArchives to ask, by id. Left out, they are all asked, which is the point of this tool.
year_toNoLatest year, in each archive's own reading of what a year is. It cannot be earlier than 'year_from'.
year_fromNoEarliest year, in each archive's own reading of what a year is. Given with 'year_to', it must not be the later of the two: a range running backwards names no year and is refused rather than read differently by each archive.
media_typeNoThe kind of material, in the vocabulary of whichever archive uses that name. the Internet Archive files texts, movies, audio, image, software, data, web; the Library of Congress files books, photos, maps, audio, film-and-videos, manuscripts, notated-music, newspapers; the Bibliothèque nationale de France files work. The names are the union of those vocabularies rather than a shared one, so an archive that does not use the name you give is named as absent rather than asked under another. Naming none leaves an archive that searches every kind unnarrowed and asks an archive that keeps one catalogue per kind for its own default.

Output Schema

NameRequiredDescriptionDefault
pageYes
itemsYes
notesYes
orderYesHow the list was built, in words.
queryYes
item_countYesRows in this answer, across every archive. Never a total of what exists.
per_sourceYes
media_typesYesWhich name each archive was asked under, published rather than reconciled, so a caller can map the vocabularies once and read what was actually searched.
queries_runYesRequests this server sent for this answer, counting every wording on every archive. Each archive's own wordings are in 'per_source'.
non_word_charactersYesCharacters in the query that are neither letters nor digits. These catalogues answer on words, so a row here can carry none of them, and 'requires_every_word' covers the words that were given rather than these.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed44 schema fields changedv2.1.0
    • removedOutput schema / properties / items / items / properties / creator / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / items / items / properties / creator / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / items / items / properties / date / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / items / items / properties / date / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / items / items / properties / found_by_derivation / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / items / items / properties / found_by_derivation / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / items / items / properties / found_by_query / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / items / items / properties / found_by_query / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / items / items / properties / identifier_provisional / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / items / items / properties / identifier_provisional / type
      Added value: +[
      +  "boolean",
      +  "null"
      +]
    • removedOutput schema / properties / items / items / properties / media_type / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / items / items / properties / media_type / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / items / items / properties / online / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / items / items / properties / online / type
      Added value: +[
      +  "boolean",
      +  "null"
      +]
    • removedOutput schema / properties / items / items / properties / title / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / items / items / properties / title / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / media_types / items / properties / asked_with / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / media_types / items / properties / asked_with / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / absent_because / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / absent_because / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / attribution / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / attribution / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / corpus / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / corpus / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / media_type_asked / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / media_type_asked / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / more_on_this_archive / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / more_on_this_archive / type
      Added value: +[
      +  "boolean",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / ordered_on / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / ordered_on / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / publishes_page_number / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / publishes_page_number / type
      Added value: +[
      +  "boolean",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / queries / items / properties / not_run_because / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / queries / items / properties / not_run_because / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / reported_total_means / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / reported_total_means / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / requires_every_word / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / requires_every_word / type
      Added value: +[
      +  "boolean",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / row_describes / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / row_describes / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / searches_on / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / searches_on / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / per_source / items / properties / year_means / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / per_source / items / properties / year_means / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  2. Changed29 schema fields changedv1.2.0
    • addedInput schema / properties / fan_out
      Added value: +{
      +  "default": true,
      +  "description": "Whether to derive further wordings from the query and ask each archive for the union of what they return. A question written as a sentence returns nothing where every word given has to appear, and the records an index scores highest where it does not, and a spelling of a name is not the only one a catalogue files it under. An archive is asked a derived wording only when the words as asked did not return as many rows as 'limit', so a query that works costs one request. Set false to send exactly the words given. 'per_source' names every wording, sent or not, and each row names the one that returned it.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / media_type / description
      Previous value: -"The kind of material, in the vocabulary of whichever archive uses that name. the Internet Archive files texts, movies, audio, image, software, data, web; the Library of Congress files books, photos, maps, audio, film-and-videos, manuscripts, notated-music, newspapers. The names are the union of those vocabularies rather than a shared one, so an archive that does not use the name you give is named as absent rather than asked under another. Naming none leaves an archive that searches every kind unnarrowed and asks an archive that keeps one catalogue per kind for its own default."New value: +"The kind of material, in the vocabulary of whichever archive uses that name. the Internet Archive files texts, movies, audio, image, software, data, web; the Library of Congress files books, photos, maps, audio, film-and-videos, manuscripts, notated-music, newspapers; the Bibliothèque nationale de France files work. The names are the union of those vocabularies rather than a shared one, so an archive that does not use the name you give is named as absent rather than asked under another. Naming none leaves an archive that searches every kind unnarrowed and asks an archive that keeps one catalogue per kind for its own default."
    • changedInput schema / properties / media_type / enum
      Previous value: -[
      -  "audio",
      -  "books",
      -  "data",
      -  "film-and-videos",
      -  "image",
      -  "manuscripts",
      -  "maps",
      -  "movies",
      -  "newspapers",
      -  "notated-music",
      -  "photos",
      -  "software",
      -  "texts",
      -  "web"
      -]New value: +[
      +  "audio",
      +  "books",
      +  "data",
      +  "film-and-videos",
      +  "image",
      +  "manuscripts",
      +  "maps",
      +  "movies",
      +  "newspapers",
      +  "notated-music",
      +  "photos",
      +  "software",
      +  "texts",
      +  "web",
      +  "work"
      +]
    • changedInput schema / properties / sort / description
      Previous value: -"Applied inside each archive. The merged list stays interleaved, because no order runs across archives."New value: +"Applied inside each archive. The merged list stays interleaved, because no order runs across archives. 'oldest' and 'newest' run on a date field carrying a year and no era, and a record stating no date is placed by a stand-in, so neither end of such an order is a claim about age."
    • changedInput schema / properties / sources / items / enum
      Previous value: -[
      -  "archive",
      -  "loc"
      -]New value: +[
      +  "archive",
      +  "loc",
      +  "bnf"
      +]
    • changedInput schema / properties / year_from / description
      Previous value: -"Earliest year, in each archive's own reading of what a year is."New value: +"Earliest year, in each archive's own reading of what a year is. Given with 'year_to', it must not be the later of the two: a range running backwards names no year and is refused rather than read differently by each archive."
    • changedInput schema / properties / year_to / description
      Previous value: -"Latest year, in each archive's own reading of what a year is."New value: +"Latest year, in each archive's own reading of what a year is. It cannot be earlier than 'year_from'."
    • addedOutput schema / properties / items / items / properties / found_by_derivation
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "How that wording was arrived at from the question, in words."
      +}
    • addedOutput schema / properties / items / items / properties / found_by_query
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "The wording this archive was given that returned this row. It is the query as you wrote it unless a further wording was derived, in which case the row answers that wording's words and not the rest of the question."
      +}
    • addedOutput schema / properties / items / items / properties / identifier_provisional
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "True where the archive itself calls this identifier provisional: it can be replaced once a cataloguer settles the record, so a citation carrying it can stop naming anything. Null on an archive that mints one kind of identifier and says nothing about settling it, which is not the same as an archive stating this one is settled."
      +}
    • changedOutput schema / properties / items / items / properties / online / description
      Previous value: -"Whether a digitised copy can be read online. Null on an archive that holds a copy of everything it catalogues and so states nothing."New value: +"Whether a digitised copy can be read online. Null on an archive that states nothing about a copy against a catalogue row."
    • changedOutput schema / properties / items / items / required
      Previous value: -[
      -  "id",
      -  "source",
      -  "source_name",
      -  "identifier",
      -  "title",
      -  "creator",
      -  "year",
      -  "date",
      -  "media_type",
      -  "source_url",
      -  "downloads",
      -  "location",
      -  "online"
      -]New value: +[
      +  "id",
      +  "source",
      +  "source_name",
      +  "identifier",
      +  "title",
      +  "creator",
      +  "year",
      +  "date",
      +  "media_type",
      +  "source_url",
      +  "downloads",
      +  "location",
      +  "online",
      +  "identifier_provisional",
      +  "found_by_query",
      +  "found_by_derivation"
      +]
    • changedOutput schema / properties / media_types / items / properties / vocabulary / description
      Previous value: -"Every name this archive files material under."New value: +"Every name this archive takes as the 'media_type' argument, which is how its catalogue is divided. The 'media_type' on a row is the word that record carries, and is often none of these."
    • addedOutput schema / properties / non_word_characters
      Added value: +{
      +  "description": "Characters in the query that are neither letters nor digits. These catalogues answer on words, so a row here can carry none of them, and 'requires_every_word' covers the words that were given rather than these.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / per_source / items / properties / attribution
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "What to say when repeating what this archive contributed, as this archive states it for this answer. An archive whose licence asks for the date its metadata was retrieved carries that date here. Null on an archive that was never asked."
      +}
    • changedOutput schema / properties / per_source / items / properties / corpus / description
      Previous value: -"What body of material this archive's full-text index reads."New value: +"What body of material this archive's full-text index reads. Null where this answer did not read it."
    • addedOutput schema / properties / per_source / items / properties / filters_dropped
      Added value: +{
      +  "description": "Narrowings you asked for that this archive never received, because its catalogue cannot apply them. Its rows were not narrowed by them, and a row from it that happens to satisfy one is a coincidence rather than a filter. Empty when it received every narrowing asked for.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "because": {
      +        "description": "Why this archive never received it.",
      +        "type": "string"
      +      },
      +      "filter": {
      +        "description": "The narrowing, named as the argument that carries it.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "filter",
      +      "because"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / per_source / items / properties / queries
      Added value: +{
      +  "description": "Every wording derived for this archive, in the order they were tried, with what each one returned and why any was withheld. Retyping one of them reproduces its rows by hand. Empty on a call that carries no query.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "added": {
      +        "anyOf": [
      +          {
      +            "maximum": 9007199254740991,
      +            "minimum": -9007199254740991,
      +            "type": "integer"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "Rows this wording contributed that an earlier one had not already returned. Null when it was not sent, or did not answer."
      +      },
      +      "count": {
      +        "anyOf": [
      +          {
      +            "maximum": 9007199254740991,
      +            "minimum": -9007199254740991,
      +            "type": "integer"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "Rows the archive returned for this wording. Zero is that wording finding nothing, which is a statement about the wording. Null when it was not sent, or did not answer."
      +      },
      +      "derivation": {
      +        "description": "How this wording was arrived at from the question, in words.",
      +        "type": "string"
      +      },
      +      "error": {
      +        "anyOf": [
      +          {
      +            "additionalProperties": false,
      +            "properties": {
      +              "code": {
      +                "type": "string"
      +              },
      +              "hint": {
      +                "type": "string"
      +              },
      +              "message": {
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "code",
      +              "message"
      +            ],
      +            "type": "object"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "Why this wording did not answer. Null when it did, or was never sent."
      +      },
      +      "not_run_because": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "Why it was withheld. Null when it was sent."
      +      },
      +      "query": {
      +        "description": "The words this archive was given, exactly as they were sent.",
      +        "type": "string"
      +      },
      +      "ran": {
      +        "description": "Whether it was sent. False means it was derived and withheld.",
      +        "type": "boolean"
      +      }
      +    },
      +    "required": [
      +      "query",
      +      "derivation",
      +      "ran",
      +      "count",
      +      "added",
      +      "not_run_because",
      +      "error"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / per_source / items / properties / requires_every_word
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Whether the index this answer put the words to answers only where every word given appears. It covers the words: a character that is neither a letter nor a digit is not a word to an index, and those are listed in 'non_word_characters' instead. False means the index ranks the words and answers with what it scores highest, so one of its rows can carry only some of them. Null on an archive that was not asked."
      +}
    • addedOutput schema / properties / per_source / items / properties / row_describes
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "What one row from this archive is: a copy it holds, a record in a catalogue, or a work as an entity whose editions are records of their own. Rows carry the same fields and describe different kinds of thing."
      +}
    • addedOutput schema / properties / per_source / items / properties / searches_on
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "The fields this archive matched the query against. The archives read different ones, so the same words are not the same question everywhere, and a name given to an index over titles alone comes back as the works written about that person."
      +}
    • removedOutput schema / properties / per_source / items / properties / skipped / anyOf
      Removed value: -[
      -  {
      -    "maximum": 9007199254740991,
      -    "minimum": -9007199254740991,
      -    "type": "integer"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedOutput schema / properties / per_source / items / properties / skipped / description
      Previous value: -"Rows this archive sent in a shape the server could not read, and left out. Null on an answer served from a cache that kept the rows and not the count of what was dropped building them."New value: +"Rows this archive sent in a shape the server could not read, and left out of this answer. Always a count, so it reads the same way on every answer. Rows served out of a cache were counted the same way when they were first read, and 'cached' marks an answer whose count can be short of a drop nobody kept a record of."
    • addedOutput schema / properties / per_source / items / properties / skipped / maximum
      Added value: +9007199254740991
    • addedOutput schema / properties / per_source / items / properties / skipped / minimum
      Added value: +-9007199254740991
    • addedOutput schema / properties / per_source / items / properties / skipped / type
      Added value: +"integer"
    • changedOutput schema / properties / per_source / items / required
      Previous value: -[
      -  "source",
      -  "name",
      -  "status",
      -  "stage",
      -  "absent_because",
      -  "count",
      -  "reported_total",
      -  "reported_total_means",
      -  "skipped",
      -  "more_on_this_archive",
      -  "ordered_on",
      -  "media_type_asked",
      -  "year_means",
      -  "publishes_page_number",
      -  "corpus",
      -  "cached",
      -  "error"
      -]New value: +[
      +  "source",
      +  "name",
      +  "status",
      +  "stage",
      +  "absent_because",
      +  "count",
      +  "reported_total",
      +  "reported_total_means",
      +  "skipped",
      +  "more_on_this_archive",
      +  "ordered_on",
      +  "media_type_asked",
      +  "attribution",
      +  "searches_on",
      +  "row_describes",
      +  "filters_dropped",
      +  "queries",
      +  "year_means",
      +  "publishes_page_number",
      +  "corpus",
      +  "requires_every_word",
      +  "cached",
      +  "error"
      +]
    • addedOutput schema / properties / queries_run
      Added value: +{
      +  "description": "Requests this server sent for this answer, counting every wording on every archive. Each archive's own wordings are in 'per_source'.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "query",
      -  "page",
      -  "items",
      -  "item_count",
      -  "per_source",
      -  "media_types",
      -  "order",
      -  "notes"
      -]New value: +[
      +  "query",
      +  "page",
      +  "items",
      +  "item_count",
      +  "per_source",
      +  "queries_run",
      +  "media_types",
      +  "non_word_characters",
      +  "order",
      +  "notes"
      +]
  3. First observedv1.0.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds substantial behavior beyond them: rows are interleaved per archive with no cross-archive ranking, per_source counts are never summed, sort applies inside each archive, year ordering ignores era and places undated records by stand-in, queries are interpreted differently per archive (all-words vs relevance scoring), synonym fan-out costs extra requests, and a request ceiling makes answers take seconds. This is exactly the context annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the search_inside exclusion are front-loaded, and most sentences carry genuine caveats, but the single ~450-word paragraph is dense and archaic ('a character that is neither a letter nor a digit is no word to an index'), with media_type and fan_out behavior largely repeated from the schema. It is complete but hard to scan.

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?

Given nine parameters, three heterogeneous archives, an output schema, and multiple quirky semantics, the description covers the failure modes an agent must anticipate: empty results from sentence-style queries, missing-archive reporting, per-source counts that cannot be aggregated, unreliable date ordering, and latency. Nothing needed to call it correctly appears to be 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?

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning about cross-parameter interaction — media_type names are a union of per-archive vocabularies so unknown names mark an archive absent rather than being translated, fan_out is skipped when the literal query already fills 'limit', and year ranges are read per archive. Some of this restates the schema fields, which keeps 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, resource and scope: search every archive's catalogue simultaneously for a title/creator/subject, returning one merged list. It also states how its ids relate to get_item and later explicitly separates itself from search_inside, so an agent can place it among its siblings without reading schemas.

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 an explicit exclusion with the alternative: 'Use search_inside for a phrase printed on a page: this tool reads catalogue records'. It also routes the agent to get_item for per-record reuse terms, and explains that omitting 'sources' is the intended default, so both when-to-use and when-not-to-use are covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools