Find books, headings, authors, categories or names
shamela_findCatalogue 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
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Selects what the call does: book | heading | author | category | work | name | period. Default book. | |
| type | No | '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.) | |
| limit | No | [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.) | |
| query | No | [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.) | |
| scope | No | [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.) | |
| title | No | The 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.) | |
| author | No | The 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.) | |
| offset | No | Number 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_to | No | Hijri year, inclusive UPPER bound on the MAIN AUTHOR's death year (author.death_number). Pair with died_from. (kind=period only.) | |
| edition | No | A 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.) | |
| options | No | [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_from | No | Hijri 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_id | No | Optional: 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_to | No | Hijri 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_from | No | Hijri 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_counts | No | If 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_only | No | [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_format | No | Format 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
| Name | Required | Description | Default |
|---|---|---|---|
| books | No | [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.) | |
| match | No | The single entry, when status is 'exact'. (kind=work only.) | |
| notes | No | Guidance on using the result. (kind=work only.) | |
| query | No | The query as received. (kind=book|heading|author|name only.) | |
| title | No | Title as parsed from the request. (kind=work only.) | |
| total | No | [kind=category] Categories listed. [kind=period] Books satisfying every bound. (kind=category|period only.) | |
| author | No | Author filter applied; null when none. (kind=work only.) | |
| filter | No | Echo of the applied constraints. (kind=period only.) | |
| offset | No | [kind=book|heading|author] Offset this page started at. [kind=period] Rows skipped before this page. (kind=book|heading|author|period only.) | |
| reason | No | When not_found: 'no_title_match', 'author_mismatch' or 'edition_not_found'. (kind=work only.) | |
| status | No | 'exact' — use `match`; 'ambiguous' — see `ambiguity`; 'not_found' — read `reason` (and available_editions for an unknown edition). (kind=work only.) | |
| authors | No | Author matches, best first. (kind=name only.) | |
| edition | No | Edition requested; null when none. (kind=work only.) | |
| results | No | [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_ids | No | This page's ids, ready for scope.book_ids. (kind=period only.) | |
| coverage | No | Hits rolled up by_category and by_century. (kind=book only.) | |
| has_more | No | [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.) | |
| rejected | No | Entries that matched the words but are not the cited work. (kind=work only.) | |
| returned | No | [kind=book|heading|author] Rows in `results` on this call. [kind=period] Rows in this response. (kind=book|heading|author|period only.) | |
| ambiguity | No | When 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.) | |
| truncated | No | ||
| candidates | No | Entries that carry the requested title. (kind=work only.) | |
| categories | No | Categories by id. (kind=category only.) | |
| total_hits | No | Every match in scope, not just the rows returned. (kind=book|heading|author only.) | |
| next_offset | No | [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_dropped | No | ||
| no_title_match | No | True 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_ceiling | No | Deepest 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_truncated | No | True when the query had more words than are searched. (kind=book|heading|author only.) | |
| downloaded_total | No | Books installed on this server, whole library. (kind=category only.) | |
| relaxed_of_terms | No | Word count the relaxed match is measured against. (kind=book only.) | |
| normalized_tokens | No | [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_match | No | Set when no entry held every word: hits carry at least this many of `relaxed_of_terms`. (kind=book only.) | |
| available_editions | No | When edition_not_found: the printings the catalogue does carry, shaped like candidates. (kind=work only.) | |
| no_confident_match | No | Present when nothing reached score 800 (no name carries the whole query): treat the hits as suggestions. (kind=name only.) | |
| truncation_message | No |