Skip to main content
Glama

Narrators and isnads

shamela_lookup_rijal
Read-onlyIdempotent

Hadith narrators and isnad chains, from Shamela's rijal register and isnad index. mode:

  • narrators (default): a narrator by name → narrator_id, most-documented first, then earliest death year. Names collide: confirm the death year before using an id.

  • narrator: one dossier by narrator_id — lineage, death year, tabaqa, Ibn Hajar's and al-Dhahabi's grades, critics' jarh wa-ta'dil verdicts verbatim with source (the only paged part), hadith_notes on audition and irsal; include_network adds isnad-index counts per book and top teachers/students. Quote verdicts as worded; never synthesize a grade.

  • isnad_search: chains by the narrators in them — contains (anywhere) or transmission [teacher_id, student_id] pairs that must be adjacent (direct audition, the stronger test) — each hit with book, page, hadeeth_key and the chain.

  • isnad: the chain(s) printed on one page (book_id/page_id from a search hit) with names and death years, plus the same hadith's other routes — one thread or many. Rules: a parameter of another mode is refused. Chains run ascending (Companion first, collector last). Only ten hadith books are isnad-indexed (see scope_book_ids): an empty isnad_search means no such chain in those ten, not in all literature; most pages answer no_isnad_indexed:true with a no_isnad_reason, not an error. Errors: RIJAL_UNAVAILABLE (register not installed), NARRATOR_NOT_FOUND (search the name again), BOOK_NOT_FOUND, PAGE_NOT_FOUND, BOOK_NOT_DOWNLOADED (try shamela_get_details(kind='book') same_group). Instead: book authors → shamela_find(kind='author'); a hadith by its text → shamela_lookup_hadith(mode='search').

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": "shamela_lookup_rijal"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNoSelects what the call does: narrators | narrator | isnad_search | isnad. Default narrators.
limitNo[mode=narrators] Maximum narrators to return (1-50, default 10). [mode=narrator] How many CRITICS of al-jarḥ wa-l-taʿdīl to return (1-100, default 10) — the only part of the dossier that is paged. al-Zuhrī has 56 critics and 184 verdicts; they do not fit one response, and `total_critics` says how many there are. (mode=narrators|narrator only.)
queryNoPart of the narrator's name, in Arabic. Matched against the short name, the full lineage, and the register's الشهرة / اللقب / الكنية / النسب — so «الزهري» and «الأعمش» reach the men known by those nisbas even though neither appears in their recorded name. Folding is the same the page search uses, so «شعبه» finds «شعبة» and tashkeel is ignored. Tokens are ANDed and match anywhere, so «شعبة الحجاج» works even though the name reads «شعبة بن الحجاج». Results are ordered by how much al-jarḥ wa-l-taʿdīl the register holds on each man — the most-discussed «الزهري» first — with the earliest death year breaking ties. The register holds 18,989 narrators, died 2–774 AH. Names collide: check death year AND grade before deciding which «محمد بن إسماعيل» you have. E.g. 'شعبة بن الحجاج'. No hits: shorten or respell it. (mode=narrators only.)
top_nNoHow many teachers and how many students to return, most frequent first (1-100, default 15). (mode=narrator only.)
offsetNo[mode=narrators] Narrators to skip, for paging. Common names match in the thousands — «محمد بن» matches 4,271 — so page with this or narrow the query. Default: 0. [mode=narrator] Critics to skip, for paging through the verdicts. Follow `next_offset` until `has_more` is false. Default: 0. [mode=isnad_search] Chains to skip, for paging; follow `next_offset` while `has_more` is true. An offset past `paging_ceiling` returns no rows. Default: 0. (mode=narrators|narrator|isnad_search only.)
book_idNoBook id from a search hit (e.g. 1681, Sahih al-Bukhari). Chains exist only for the ten isnad-indexed books listed under shamela_lookup_rijal(mode='isnad_search'); other books answer no_isnad_indexed:true. (mode=isnad only.)
page_idNoShamela page id within that book (not the printed page number), from the same hit. An id the book lacks is PAGE_NOT_FOUND. (mode=isnad only.)
containsNoNarrator ids that must ALL appear in the chain, at any position and in any order. Use for «which reports pass through both X and Y». Ids from shamela_lookup_rijal(mode='narrators'). BAD_ARG when contains and transmission are both empty. E.g. {contains:[2779], scope_book_ids:[1681]} = Shu'ba's chains in al-Bukhari. (mode=isnad_search only.)
max_resultsNoChains to return per page (1-100, default 20). Chains come in index order. (mode=isnad_search only.)
narrator_idNoThe narrator id, as returned by shamela_lookup_rijal(mode='narrators') or inside a chain from shamela_lookup_rijal(mode='isnad'). Example: {narrator_id:4677}. (mode=narrator only.)
max_variantsNoCap on returned variant routes (1-200, default 20). `variants.truncated` reports when more exist. (mode=isnad only.)
transmissionNoPairs [teacher_id, student_id] that must appear ADJACENT and in that order — direct transmission, the student having heard from the teacher with nobody in between. This is the question «did X really narrate from Y», and it is strictly stronger than listing both in `contains`. All pairs are ANDed. E.g. [[1580,2779]] = Shu'ba heard from al-Hakam b. Utayba; [[4677,4494]] = Umar to Alqama (20 chains). (mode=isnad_search only.)
scope_book_idsNoRestrict to these books. The isnād index covers only ten: صحيح البخاري (1681), صحيح مسلم (711), سنن أبي داود (654), سنن الترمذي (7895), سنن النسائي (829), موطأ مالك (28107), مسند الطيالسي (1456), المنتقى لابن الجارود (627 و13071), وعلل الترمذي (642). 45,220 chains in all. (mode=isnad_search only.)
include_networkNoInclude the transmission network computed from the isnād index: how many chains this narrator carries, in which books, and their most frequent teachers and students. Set false to skip it when you only need the biography. Default: true. (mode=narrator only.)
response_formatNoFormat of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief).
include_variantsNoAlso return the other routes (طرق) of the same ḥadīth from the other indexed books, matched on Shamela's ḥadīth key. This is what shows whether a report rests on one thread or many. Default: true. (mode=isnad only.)

Output Schema

NameRequiredDescriptionDefault
nameNo (mode=narrator only.)
noteNo (mode=narrator only.)
queryNo (mode=narrators only.)
chainsNoChains printed on this page. (mode=isnad only.)
offsetNoRows skipped before this page. (mode=narrators|narrator|isnad_search only.)
tabaqaNoGeneration, per Taqrib al-Tahdhib. (mode=narrator only.)
book_idNo (mode=isnad only.)
networkNoIsnad-index network; null when include_network is false. (mode=narrator only.)
page_idNo (mode=isnad only.)
resultsNo[mode=narrators] Most-documented narrator first, earliest death year breaking ties. [mode=isnad_search] Chains in index order. (mode=narrators|isnad_search only.)
summaryNokunya, nasab, cities, relations — whatever the register holds. (mode=narrator only.)
containsNo (mode=isnad_search only.)
has_moreNoTrue when more rows exist past this page. (mode=narrators|narrator|isnad_search only.)
returnedNoRows in this response. (mode=narrators|narrator|isnad_search only.)
variantsNoOther routes of the same hadith, following its key outward: the route count shows one thread (gharib, غريب) or many (mashhur, مشهور). Null when none or not requested. (mode=isnad only.)
full_nameNo (mode=narrator only.)
truncatedNo
death_yearNo (mode=narrator only.)
jarh_tadilNoThis page of critics' verdicts, grouped by critic, each verbatim with book and volume/page (e.g. «تهذيب التهذيب (1/ 101)»). 15,160 of the 18,989 narrators carry verdicts, from 2,821 named critics. (mode=narrator only.)
total_hitsNoChains matching, before paging. (mode=isnad_search only.)
narrator_idNo (mode=narrator only.)
next_offsetNoOffset for the next page; present only when has_more is true. (mode=narrators|narrator|isnad_search only.)
hadeeth_keysNo (mode=isnad only.)
hadith_notesNoFawa'id on audition, irsal and implicit tawthiq: the evidence for whether a chain is connected. (mode=narrator only.)
rows_droppedNo
transmissionNo (mode=isnad_search only.)
grade_dhahabiNo (mode=narrator only.)
total_criticsNo (mode=narrator only.)
total_matchesNo (mode=narrators only.)
paging_ceilingNoPresent when offset passed the deepest reachable row. (mode=isnad_search only.)
total_verdictsNo (mode=narrator only.)
grade_ibn_hajarNo (mode=narrator only.)
no_isnad_reasonNono_marker_on_page (the page's own service annotations carry no isnad marker) | marked_but_unindexed | null. (mode=isnad only.)
chains_truncatedNo (mode=isnad only.)
no_isnad_indexedNo (mode=isnad only.)
page_isnad_markersNo (mode=isnad only.)
truncation_messageNo
total_chains_on_pageNo (mode=isnad only.)
absent_from_isnad_indexNoTrue when no indexed chain names this narrator; null when not computed. (mode=narrator only.)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, but the description adds substantial context: specific error codes (RIJAL_UNAVAILABLE, NARRATOR_NOT_FOUND, etc.), paging behavior, the fact that empty isnad_search results are not errors but a scope limitation, and a strong quality directive ('Quote verdicts as worded; never synthesize a grade'). This goes well beyond the 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?

The description is long, but it is well-structured with clear mode bullets and rules. For a 16-parameter, 4-mode tool, the length is mostly justified, and the purpose is front-loaded. A few sentences could be tightened, but it largely earns its space.

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?

Given the tool's complexity, the description covers the essential context: mode distinctions, scope limits (only ten books indexed), error handling, paging, and alternatives. An output schema exists, so return values need not be explained, and annotations cover safety. The description is complete for correct invocation.

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 description coverage is 100%, so the baseline is 3. The description reinforces mode behavior and parameter interactions (e.g., contains vs. transmission, paging ceiling), but the schema itself already provides detailed, example-rich descriptions for every parameter. The description adds little new semantic detail for individual parameters beyond what is in the schema.

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 description opens with 'Hadith narrators and isnad chains, from Shamela's rijal register and isnad index,' naming a specific resource and scope. It explicitly distinguishes itself from siblings: 'Instead: book authors → shamela_find(kind='author'); a hadith by its text → shamela_lookup_hadith(mode='search').' An agent can immediately tell what this tool does and what it does not.

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?

Each mode is given explicit when-to-use guidance, including conditions and expected inputs ('narrators (default): a narrator by name → narrator_id...', 'narrator: one dossier by narrator_id...'). It names alternatives for adjacent tasks and states a key rule: 'a parameter of another mode is refused.' Nothing is left to inference.

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.

Resources