Skip to main content
Glama

search_hadiths

Read-only

Search Sahih al-Bukhari hadiths by text phrase, narrator, book, or topic to find matching entries with hadith numbers; combine filters to narrow results.

Instructions

Search Sahih al-Bukhari's hadiths by words in the text, narrator, book or topic.

Filters combine (AND). Each result is an entry with its hadith numbers and its whole matn; call get_hadith for the sanad, the chains and the full text.

total is how many entries match. To count, call with limit=1 and read total. A total of 0 means nothing matched: try a shorter phrase, or check the topic with list_topics.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_hadiths"
  }
}

Input Schema

NameRequiredDescriptionDefault
bookNoPart of a book's name, such as الصوم.
limitNoResults per page, 1 to 50.
queryNoA phrase as it appears in the hadith's text; it matches as one whole phrase, not as separate words. Diacritics and hamza forms do not matter.
topicNoA topic name, which must match exactly: take it from list_topics.
offsetNoResults to skip: 0 for the first page, then the previous response's next_offset.
narrator_idNoOnly hadiths with this narrator in a chain.

Output Schema

NameRequiredDescriptionDefault
totalYesHow many entries match, across all pages.
offsetYesHow many entries this page skipped.
resultsYes
next_offsetNoPass as offset for the next page; null on the last page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries real weight and does: filters combine with AND, each result is one entry with its hadith numbers and full matn, and total counts matching entries rather than returned rows. The zero-result behavior and the shorter-phrase fallback are behavior an agent could not infer from the schema.

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

Conciseness5/5

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

The first sentence is front-loaded with purpose and facets; the following short lines each carry a distinct operational fact (AND semantics, result shape, total meaning, counting trick, empty-result fallback). No sentence repeats the name, title, or schema.

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?

Six optional parameters, an output schema, and read-only annotations are all well covered: the description supplies the combination semantics, the shape of a result, the meaning of total, and sibling routing. An agent has everything needed to invoke it correctly and interpret an empty response.

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, but the description adds genuine semantics beyond it: filters are AND-combined, and the zero-result advice implies query is matched as a whole phrase. It does not clarify narrator_id versus narrator-based text search or the interaction between topic and book, keeping it short of a 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?

States a specific verb and resource with scope ('Search Sahih al-Bukhari's hadiths') and enumerates the searchable facets (text, narrator, book, topic). It also distinguishes itself from the sibling get_hadith by declaring that results carry the matn only, with the sanad/chains/full text belonging to that other tool.

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?

Explicitly routes the agent: call get_hadith for the sanad and full text, call list_topics when a topic yields zero results. It even prescribes a concrete counting workflow (limit=1 and read total) and a remediation path for empty results, which is when-to-use guidance at the operational level.

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