Skip to main content
Glama

Source Library

by io.github.Embassy-of-the-Free-Mind
OverviewDiscussionsAdmin

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+ strong, 0.55–0.70 verify, 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.

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 ID to search within

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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"
+}
  2. 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"
+}
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only say read-only/idempotent; the description adds substantive behavior beyond them — hybrid keyword plus top-~10 semantic retrieval interleaved by relevance, absolute score calibration thresholds (0.70/0.55), found_by semantics, and front-matter results ordered last. This is exactly the kind of non-obvious retrieval behavior an agent cannot get from annotations.

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 verb and the divergence to search_concept, and every sentence carries usable information. It is long and caps-heavy, bordering on dense, but no sentence is filler.

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?

With no output schema, the description compensates by explaining returned fields (score with calibration bands, phrase_match, found_by, is_front_matter), ordering rules, and that results carry page numbers and snippets ready to cite. An agent can interpret results without further documentation.

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 value by stressing that book_id is mandatory and that results are ordered by relevance within that book. It does not extend the lang or offset semantics beyond what the schema already documents.

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?

States a specific verb and resource with scope: searches inside ONE book, requires book_id, and explicitly characterizes it as primarily lexical with a narrow scoped-semantic pass. It differentiates itself from search_concept and search_library by name and function.

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 explicit positive triggers ('know the wording', 'every page of one book mentioning a term'), explicit negative trigger ('searching from a paraphrase… USE search_concept INSTEAD'), and a prerequisite path (find the book via search_library or search_concept first).

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

All Source Library toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources