Skip to main content
Glama

Search Within Book

search_within_book
Read-onlyIdempotent

SEARCHES INSIDE ONE BOOK (requires book_id). PRIMARILY KEYWORD: it runs a lexical search over the book's pages plus a narrow scoped-semantic pass (top ~10), interleaved by relevance. PICK THIS when you know the wording you are looking for, or want every page of one book mentioning a term. → IF YOU ARE SEARCHING FROM A PARAPHRASE, a half-remembered line, or a modern restatement, USE search_concept INSTEAD — it is the meaning-matching tool and it searches the whole corpus, including translations whose vocabulary differs completely from yours (Thomas Taylor writes "energies" for energeia and "felicity" for eudaimonia, so a sensible modern paraphrase can miss his pages entirely while matching semantically). → To find the book first, use search_library or search_concept, then pass its book_id here. Results are ordered by relevance within this book. Each carries score (0-1, ABSOLUTE, not relative to the other results, so a query the book cannot answer scores low everywhere): the higher of similarity (raw cosine from the meaning pass, calibrated like search_concept: 0.70+ on topic though not necessarily agreeing, 0.55–0.70 weak, below 0.55 drift) and phrase_match (how much of a multi-word query the page prints in order at one place; 1 is all of it; a one-word query the page prints scores 1). Each also carries found_by ("keyword", "semantic", or "both" — both is the strongest signal). Results flagged is_front_matter are the translator's or publisher's words rather than the author's, and are ordered last. Returns OCR and translation snippets with page numbers, ready to cite.

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

Input Schema

NameRequiredDescriptionDefault
langNoISO code of the EDITION to read, e.g. "es". Default "en". Most books have only English — call get_book and read `editions`, or list_books with has_edition, to find the ones that do not. The response always states which edition it served.
queryYesSearch query
offsetNoPagination offset. Each call returns up to 50 pages; when truncated is true, call again with next_offset (default 0).
book_idYesThe book to search within. Its id, or the slug from a book URL (the part after /book/): both work.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / book_id / description
      Previous value: -"The book ID to search within"New value: +"The book to search within. Its id, or the slug from a book URL (the part after /book/): both work."
  2. Changed1 schema field changed
    • addedInput schema / properties / offset
      Added value: +{
      +  "description": "Pagination offset. Each call returns up to 50 pages; when truncated is true, call again with next_offset (default 0).",
      +  "type": "number"
      +}
  3. Changed1 schema field changed
    • addedInput schema / properties / lang
      Added value: +{
      +  "description": "ISO code of the EDITION to read, e.g. \"es\". Default \"en\". Most books have only English — call get_book and read `editions`, or list_books with has_edition, to find the ones that do not. The response always states which edition it served.",
      +  "type": "string"
      +}
  4. First observed

TDQS

A4.4/5.0
Behavior4/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), but the description adds substantial behavior beyond them: relevance interleaving, absolute (not relative) score semantics with calibration bands, found_by values, and front-matter flagging ordered last. The only gap is that it doesn't restate pagination behavior explicitly, though the schema covers that.

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?

Front-loaded with the core behavior before alternatives, and the arrow-routing structure makes the decision path scannable. The Thomas Taylor vocabulary example is illustrative but lengthy, and heavy ALL-CAPS emphasis makes it denser than necessary.

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?

There is no output schema, and the description fills that burden: it explains score ranges and thresholds, found_by values, front-matter handling, and that results carry OCR/translation snippets with page numbers ready to cite. Nothing an agent needs to call or interpret results is missing.

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

Parameters3/5

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

Schema coverage is 100% and the field descriptions are already rich (lang edition semantics, offset/next_offset, book_id accepting id or slug). The description adds only the book_id requirement, which the schema already marks required, so baseline 3 applies.

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+scope: lexical search over one book's pages plus a narrow scoped-semantic pass. It explicitly contrasts with search_concept, so an agent can distinguish the two without opening either schema.

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?

States when to pick this tool (you know the wording, want every page mentioning a term) and when not to (paraphrases, half-remembered lines, modern restatements → search_concept), with a concrete example of vocabulary drift. It also tells the agent how to obtain book_id via search_library or search_concept.

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.