search_booksFind the passages that best match query, by its words, across every book or within one (book, a slug). Each result has its book, edition, section ID and title, a snippet, and the citation block to cite it with. Read a whole result with get_section. limit is 5 unless you ask for up to 10.
| Name | Required | Description | Default |
|---|---|---|---|
| book | No | ||
| limit | No | ||
| query | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, closed-world behavior, so the description is free to add the useful non-annotation details: the shape of each result (book, edition, section ID, title, snippet, citation) and the default/maximum limit. It does not discuss ranking behavior beyond 'best match', which is a small residual gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: scope and matching first, result contents second, follow-on tool and limit default last. Nothing is repeated from the annotations and no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists, the description still sketches the result fields and how to cite them, and covers the default/limit behavior, so an agent has everything needed to call and consume the tool. Nothing material is missing for a three-parameter search.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description has to carry all parameter meaning and largely does: `book` is explained as a slug that scopes the search, and `limit` is documented with a default of 5 and a ceiling of 10, which the schema does not express. `query` is only implicitly described as words to match rather than given format guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (find passages matching `query` by words) and pins down the scope: every book or restricted to one via `book`. It also names the sibling `get_section` for the follow-on action, so the agent can distinguish search from retrieval without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear context of use (find matching passages, then read a whole result with get_section) but does not state when *not* to search, e.g. when to go straight to get_section if the section is already known. Adequate routing guidance with a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.