Skip to main content
Glama
This connector has been deprecated

Find books, headings, authors, categories or names

shamela_find
Read-onlyIdempotent

Catalogue lookup — which books, headings, authors and shelves exist, not page text. kind:

  • book (default): titles, authors, publication lines, subject descriptions → book_ids, installed or not. no_title_match: not proof the book is held. downloaded:false → another edition (shamela_get_details(kind='book') same_group) or catalogue metadata only.

  • heading: chapter/section headings, i.e. where books treat a topic; open with shamela_read(unit='section', book_id, title_id). No hits = no heading carries the words: drop words or use shamela_search(match='words').

  • author: names and biographies → author_id, Hijri death year, book count; no scope. Empty is not absence: retry kunya, nisba or shuhra (ابن قدامة / الموفق / المقدسي).

  • category: the 41 flat shelves with catalogue and installed counts → scope.category_ids. A subject spans ids (Qur'anic studies 3 tafsir, 4 Qur'anic sciences/usul al-tafsir, 5 tajwid/qira'at; fiqh 14–17 by madhab): pass all that apply. downloaded_only:true when choosing shelves to search or read.

  • work: verify a cited title (optional author, edition); refuses rather than guesses; catalogue only, text need not be installed.

  • name: fuzzy best guess over book/author names, for an id; always answers, so never use it to verify a citation.

  • period: books by Hijri window, bounds ANDed (scope.period_* on searches unions them). Rules: a parameter of another kind is refused; book/heading/author/period page with limit/offset until has_more is false. Instead: page text → shamela_search; a printed page → shamela_cite(mode='printed_page'); one book's headings → shamela_read(unit='toc').

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_find"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNoSelects what the call does: book | heading | author | category | work | name | period. Default book.
typeNo'book' matches catalogue titles only, 'author' author names only, 'any' (default) both, returned as separate books[] and authors[] lists. Reads the s_book/ and s_author/ n-gram indexes (fast partial matching). Example: {query:'ابن قدامة', type:'author'}. (kind=name only.)
limitNo[kind=book|heading|author|period] Maximum number of results to return (1-100, default 20). [kind=work] Maximum candidates to report (1-50, default 20). [kind=name] Maximum results per list (1–20, default 5): with type 'any' you get up to `limit` books AND up to `limit` authors. (kind=book|heading|author|work|name|period only.)
queryNo[kind=book] Arabic words matched against book name + author + bibliography and the editorial subject description; each hit's `matched_in` says which. 1,729 entries carry a description (~1,500 characters on average), which finds a book by SUBJECT: «الرجز» matches 0 titles and 2 descriptions; {query:'البيوع'} also returns books whose description carries it. E.g. {query:'الأصول'}. [kind=heading] Arabic words matched against chapter / section title text, e.g. 'باب الصيام', or 'تعريف' with scope:{book_ids:[id]}. [kind=author] Arabic words matched against name + biography in the ~3,200-author catalogue, e.g. 'ابن قدامة'. [kind=name] An Arabic name fragment: 'ابن قدامة' resolves Ibn Qudamah, 'روضة الناظر' the book, 'الروضة' the books with that word in their title; «title لِauthor» is split into title and author. Every kind reads pre-built indexes: no download needed. (kind=book|heading|author|name only.)
scopeNo[kind=book] Restrict to authors, categories, a Hijri period (period_from/period_to) or downloaded_only (books whose text is installed); scope.book_ids is not accepted. E.g. {query:'فقه', scope:{category_ids:[17], downloaded_only:true}}. [kind=heading] The same filter as shamela_search(match='words'); scope.book_ids with one id searches only that book's headings. EMPTY_SCOPE: the scope matched no book. (kind=book|heading only.)
titleNoThe work's title as cited, e.g. «صحيح البخاري», «المغني», «فتح الباري». Leading words only — the title, not a description of it. You may include the catalogue's own edition tail, with the « - » («صحيح البخاري - ط السلطانية») or without it («مسند أحمد ط الرسالة»), and it will be read as `edition`. An author name appended instead («صحيح البخاري محمد بن إسماعيل البخاري», «الهداية للمرغيناني») is read as `author`. Where a title is held by more than one author, a trailing edition is NOT read as one until you also pass `author` — «صحيح البخاري ت البغا» alone is refused, «صحيح البخاري ت البغا» + author «البخاري» resolves. The title must be a PREFIX of the entry's own: «شرح صحيح البخاري», «المدخل إلى صحيح البخاري» and «عمدة القاري شرح صحيح البخاري» contain the work's name and none IS the work. A commentary is rejected (listed in rejected[]): quoting it as the work would attribute its author's words to al-Bukhari. Example: {title:'المغني', author:'ابن قدامة'}. (kind=work only.)
authorNoThe author as cited, when known. This is a FILTER, not a hint: a candidate whose author cannot be reconciled with it is rejected rather than ranked down, because that is exactly how a commentary gets returned as the work it comments on. (kind=work only.)
offsetNoNumber of results to skip for pagination. Use with `limit` to page through large result sets. The response includes `has_more` and `next_offset` to drive paging. Default: 0. (kind=book|heading|author|period only.)
died_toNoHijri year, inclusive UPPER bound on the MAIN AUTHOR's death year (author.death_number). Pair with died_from. (kind=period only.)
editionNoA specific printing, as the catalogue names it: 'ط السلطانية', 'ت البغا', 'ط التأصيل'. If no entry carries it you get status='not_found' with reason='edition_not_found' and the editions that DO exist — never a different book. (kind=work only.)
optionsNo[kind=book] morphology / wildcards / sort / relax_when_empty. [kind=heading] morphology / wildcards / sort ('chronological' = earliest author first); headings are matched in folded form only. [kind=author] morphology / wildcards / sort ('relevance' by default; 'chronological' = by Hijri death year, earliest first, undated last), e.g. {query:'الشافعي', options:{wildcards:false}}. preserve_* return OPTION_NOT_SUPPORTED; search_in is ignored (catalogue entries have no body or footnotes; a heading is a single field). Results are ranked by relevance unless sort says otherwise. (kind=book|heading|author only.)
died_fromNoHijri year, inclusive LOWER bound on the MAIN AUTHOR's death year (author.death_number). A different column from composed_*, but the same number on 98.5% of dated books. Pair with died_to. At least one of composed_from/composed_to/died_from/died_to is required (BAD_ARG); a missing side is open-ended, and undated books drop out under any bound set. E.g. died_from:700, died_to:800 = 8th-century-Hijri authors. A composed-vs-died question («written in the 8th century by authors who died in the 9th») cannot be answered from this data: a near-empty result means the distinction is unavailable, not that no such book exists. (kind=period only.)
category_idNoOptional: restrict to one category (use shamela_find(kind='category') for IDs). Categories are flat in master.db. Example: {died_from:600, died_to:700, category_id:17}. (kind=period only.)
composed_toNoHijri year, inclusive UPPER bound on book.book_date («تاريخ الكتاب»; see composed_from — it is not a composition year). Pair with composed_from. (kind=period only.)
composed_fromNoHijri year, inclusive LOWER bound on book.book_date — Shamela's «تاريخ الكتاب». NOT an independent composition year: it holds the main author's death year on 98.5% of dated books (8,461/8,587), so pairing it with died_* almost never narrows anything. Pair with composed_to. (kind=period only.)
include_countsNoIf true (default), include book_count for each category; false returns book_count 0. Costs nothing either way — counts are precomputed. downloaded_count is always filled. (kind=category only.)
downloaded_onlyNo[kind=category] If true, list only categories with at least one book installed on this server. Useful to see where the installed library is concentrated across the 41 categories. Default: false. [kind=period] If true, restrict to books whose text is installed on this server — the only ones with searchable page content. Default false lists the whole catalogue. (kind=category|period 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).

Output Schema

NameRequiredDescriptionDefault
booksNo[kind=name] Book matches, best first. [kind=period] book_id, book_name, main author + death year, book_date, category, downloaded; sorted by book_id. (kind=name|period only.)
matchNoThe single entry, when status is 'exact'. (kind=work only.)
notesNoGuidance on using the result. (kind=work only.)
queryNoThe query as received. (kind=book|heading|author|name only.)
titleNoTitle as parsed from the request. (kind=work only.)
totalNo[kind=category] Categories listed. [kind=period] Books satisfying every bound. (kind=category|period only.)
authorNoAuthor filter applied; null when none. (kind=work only.)
filterNoEcho of the applied constraints. (kind=period only.)
offsetNo[kind=book|heading|author] Offset this page started at. [kind=period] Rows skipped before this page. (kind=book|heading|author|period only.)
reasonNoWhen not_found: 'no_title_match', 'author_mismatch' or 'edition_not_found'. (kind=work only.)
statusNo'exact' — use `match`; 'ambiguous' — see `ambiguity`; 'not_found' — read `reason` (and available_editions for an unknown edition). (kind=work only.)
authorsNoAuthor matches, best first. (kind=name only.)
editionNoEdition requested; null when none. (kind=work only.)
resultsNo[kind=book] Catalogue entries: book_id, book_name, author_name, category, book_date, downloaded (false = text not installed on this server), snippet, matched_in ('bibliography' | 'description' | null). [kind=heading] Matching headings: book_id, book_name, author_name, title_id (pass to shamela_read(unit='section')), title_text, parent_id (enclosing heading, null at top level). [kind=author] Authors: author_id, author_name, death_year (Hijri, null when unknown), book_count, snippet. (kind=book|heading|author only.)
book_idsNoThis page's ids, ready for scope.book_ids. (kind=period only.)
coverageNoHits rolled up by_category and by_century. (kind=book only.)
has_moreNo[kind=book|heading|author] True when another page exists; call again with `next_offset`. [kind=period] True when more rows exist past this page. (kind=book|heading|author|period only.)
rejectedNoEntries that matched the words but are not the cited work. (kind=work only.)
returnedNo[kind=book|heading|author] Rows in `results` on this call. [kind=period] Rows in this response. (kind=book|heading|author|period only.)
ambiguityNoWhen ambiguous: 'edition' — one work in several printings: search them as one scope, cite one; 'work' — different books that nothing may choose between («المغني»: al-Dhahabi's book of weak narrators and Ibn Qudama's fiqh): the user must choose. (kind=work only.)
truncatedNo
candidatesNoEntries that carry the requested title. (kind=work only.)
categoriesNoCategories by id. (kind=category only.)
total_hitsNoEvery match in scope, not just the rows returned. (kind=book|heading|author only.)
next_offsetNo[kind=book|heading|author] Offset of the next page. Absent on the last page. [kind=period] Offset for the next page; present only when has_more is true. (kind=book|heading|author|period only.)
rows_droppedNo
no_title_matchNoTrue when no returned title carries every query word: hits match by some words or by description, not proof the book is held. (kind=book only.)
paging_ceilingNoDeepest offset paging can reach. Present only when the request went past it: narrow the scope instead of paging further. (kind=book|heading|author only.)
terms_truncatedNoTrue when the query had more words than are searched. (kind=book|heading|author only.)
downloaded_totalNoBooks installed on this server, whole library. (kind=category only.)
relaxed_of_termsNoWord count the relaxed match is measured against. (kind=book only.)
normalized_tokensNo[kind=book|heading|author] The query after Arabic folding, as actually searched. [kind=name] Tokens after Arabic normalisation. (kind=book|heading|author|name only.)
relaxed_min_matchNoSet when no entry held every word: hits carry at least this many of `relaxed_of_terms`. (kind=book only.)
available_editionsNoWhen edition_not_found: the printings the catalogue does carry, shaped like candidates. (kind=work only.)
no_confident_matchNoPresent when nothing reached score 800 (no name carries the whole query): treat the hits as suggestions. (kind=name only.)
truncation_messageNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already establish the safe read-only/idempotent profile, and the description goes well past them: per-kind refusal of foreign parameters, pagination-until-has_more-false, EMPTY_SCOPE, the madhab filter's deliberate exclusion of unresolved-school books, 'downloaded:false → another edition ... or catalogue metadata only', and the warning that `name` always answers. These are operational traits an agent cannot infer from readOnlyHint/destructiveHint.

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 purpose and the kind list are front-loaded, and the closing 'Instead:' block cleanly consolidates the anti-pattern routes. It is dense and long, but for a 7-mode, 18-parameter tool every bullet carries distinct operational content rather than filler, so the length is largely earned.

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?

An output schema exists, so return-shape explanation is correctly omitted. Given the complexity — 7 modes, nested scope/options, 100% schema coverage — the description still supplies everything an agent needs to pick a mode, know what gets refused, know how to page, and know which sibling handles the adjacent job.

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 description coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: that a parameter belonging to another kind is refused, that book/heading/author/period page with limit/offset, and that scope.category_ids should carry multiple ids when a subject spans shelves. That is meaningful beyond-schema guidance rather than restatement.

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 precise verb+resource framing — 'Catalogue lookup — which books, headings, authors and shelves exist, not page text' — that immediately scopes it against the content-searching sibling shamela_search. Each of the seven `kind` values is given its own concrete definition (book→titles/authors/publication lines, heading→chapter titles, etc.), so an agent can differentiate it from shamela_read, shamela_cite and shamela_get_details without opening any 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?

Explicit per-kind routing plus a closing rule that names alternatives by name: page text → shamela_search, a printed page → shamela_cite(mode='printed_page'), one book's headings → shamela_read(unit='toc'). It also states when NOT to use a mode ('name': always answers, so never use it to verify a citation; 'work': refuses rather than guesses). Both the when and the when-not are covered.

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