Skip to main content
Glama

Find a work by its title

search_works
Read-onlyIdempotent

Find works in the Bibliothèque nationale de France catalogue by title words and return identifiers for get_work and list_editions.

Instructions

Find a work in the Bibliothèque nationale de France catalogue by words in its title, and get the identifier get_work and list_editions take. A row matches when its title carries every word given. The index returns no measure of how well a row matches, so the rows are ordered by the address of the record and the work a person would call the obvious answer can sit anywhere in the list or on a later page. A study of a book carries the book's title, so a search for a famous title returns the criticism alongside the work. Read 'creators' to tell them apart. This reads titles and nothing else. Searching a person's name returns the works written about them, whose creators are their critics; list_works is what walks from a person to the works the catalogue names them the creator of. 'status' says whether the BnF has established the work as a record of its own or holds it provisionally under a title it has catalogued. One search reads a fixed window of the index, and that window is read before the works are told apart from everything else the index holds, so even a short list can rest on a full one. 'index_window_full' says which: when it is true, titles sit past what was read, 'has_more' being false says where the reading stopped, and another reading of the same search can bring back other rows. Add a word to the title to reach further.

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": {
      "title": "<title>"
    },
    "name": "search_works"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNo
limitNo
titleYesWords from the title, such as 'saison enfer'. Every word given has to appear.

Output Schema

NameRequiredDescriptionDefault
pageYes
notesYes
titleYesThe words asked for.
worksYes
has_moreYesWhether the endpoint held at least one further row beyond this page, within the window the search read off the index. Read it alongside 'index_window_full': false on a full window says where the reading stopped rather than that the catalogue holds nothing else.
retrieved_atYesWhen these metadata were read from data.bnf.fr, as an ISO 8601 instant. The BnF licence asks for this date to be stated wherever the metadata are shown, so repeat it alongside the source.
words_searchedYesThe terms the index required, each of which has to appear in the title. A word is cut at an apostrophe and at a hyphen before the index sees it, so a word given as one can appear here as two, and a record carrying the pieces apart is a match.
index_window_fullYesWhether the fixed window this search reads off the index came back full. The window is read before the works are separated from the rest of the index, so a short list can rest on a full window. True means titles carrying these words sit past what was read, and another reading can bring back other rows. False means the window held everything that matched. Null when the endpoint stated no occupancy.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv2.2.0
    • removedOutput schema / properties / index_window_full / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / index_window_full / type
      Added value: +[
      +  "boolean",
      +  "null"
      +]
    • removedOutput schema / properties / works / items / properties / creators / items / properties / name / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / works / items / properties / creators / items / properties / name / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / works / items / properties / date / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / works / items / properties / date / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / works / items / properties / title / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / works / items / properties / title / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  2. Changed4 schema fields changedv1.1.0
    • addedOutput schema / properties / has_more / description
      Added value: +"Whether the endpoint held at least one further row beyond this page, within the window the search read off the index. Read it alongside 'index_window_full': false on a full window says where the reading stopped rather than that the catalogue holds nothing else."
    • addedOutput schema / properties / index_window_full
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Whether the fixed window this search reads off the index came back full. The window is read before the works are separated from the rest of the index, so a short list can rest on a full window. True means titles carrying these words sit past what was read, and another reading can bring back other rows. False means the window held everything that matched. Null when the endpoint stated no occupancy."
      +}
    • addedOutput schema / properties / words_searched / description
      Added value: +"The terms the index required, each of which has to appear in the title. A word is cut at an apostrophe and at a hyphen before the index sees it, so a word given as one can appear here as two, and a record carrying the pieces apart is a match."
    • changedOutput schema / required
      Previous value: -[
      -  "title",
      -  "words_searched",
      -  "works",
      -  "page",
      -  "has_more",
      -  "retrieved_at",
      -  "notes"
      -]New value: +[
      +  "title",
      +  "words_searched",
      +  "works",
      +  "page",
      +  "has_more",
      +  "index_window_full",
      +  "retrieved_at",
      +  "notes"
      +]
  3. First observedv1.0.0

TDQS

A4.3/5.0
Behavior5/5

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

Far beyond what readOnlyHint/idempotentHint convey: it discloses that there is no relevance measure, that rows are ordered by record address so the obvious answer can appear anywhere, that criticism surfaces alongside the work, that the index window is read before filtering, what index_window_full and has_more mean, and that repeating the same search can return different rows. That is exactly the non-obvious context an agent needs.

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 is front-loaded correctly, but the prose is dense and some clauses bury their point, e.g. the 'status' sentence takes a long subordinate construction to say whether the BnF holds the work as its own record or provisionally. Several points (window semantics) are restated across sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shapes need not be described, and the description covers result ordering, the creator field's role, status, and truncation signals. What remains thin is pagination behaviour — how page and limit interact with the fixed index window — which an agent would need to page reliably.

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

Parameters2/5

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

Only 'title' is explained (all words must appear, add a word to reach further), largely echoing the schema's own description. With schema coverage at 33%, page and limit — including their bounds of 100 and 50 and the fact that a short list can rest on a full window — are never addressed, so the schema gap is not compensated.

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?

The first sentence gives a specific verb and resource plus the exact source (BnF catalogue) and the constraint that it reads titles only, and it names the two downstream consumers (get_work, list_editions) whose identifiers it produces. 'This reads titles and nothing else' sharply separates it from list_works and search_authors.

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?

It states explicitly when not to use it ('Searching a person's name returns the works written about them... list_works is what walks from a person to the works') and gives a concrete remedy for ambiguous results ('Read 'creators' to tell them apart'). Alternative tool and selection conditions are both present.

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