Search page text (words, phrase, exact, boolean, batch)
shamela_searchFull-text search inside the pages (matn and footnotes) of installed books. match picks how the query is read:
words (default): every word required, ranked by relevance; options add morphology, wildcards, chronological sort. An all-words miss retries with fewer words (relaxed_min_match).
phrase: the words consecutively (a quotation). near: all words within
distance, any order. Both verified in the full page text.exact: diacritics, hamza/alef forms or digit systems kept distinct («أحمد» not «احمد», «عِلْم» not «عَلَم», ٢٥٥ not 255); set at least one
preserveflag.boolean: every all_of term, one or more any_of, no none_of (الوقف with المسجد or المقبرة, without البيع); one query over the whole index, so total_hits is exact and exclusion exhaustive.
batch: 1–24 scoped
queriesrun at once, merged and deduped by page (probe_ids); no paging, cut at max_total_passages. Rules: a parameter of another match value is refused. Page with limit/offset until has_more is false. scope.madhab drops books of unknown school: omit it for comparative questions; set scope.citable_only before quoting a page number. Follow-up rounds: exclude_pages / exclude_work_group_ids keep out pages already used and other printings of the same work. EMPTY_SCOPE: the scope matched no book. Instead: chapter headings → shamela_find(kind='heading'); titles → shamela_find(kind='book'); verses → shamela_lookup_quran(mode='search'); a hadith's wording → shamela_lookup_hadith(mode='search'). Example: {query:'استصناع', scope:{category_ids:[17]}}.
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_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return (1-100, default 20). (match=words|phrase|near|exact|boolean only.) | |
| match | No | Selects what the call does: words | phrase | near | exact | boolean | batch. Default words. | |
| query | No | [match=words] Arabic words, ANDed; each may match in body or footnotes, e.g. {query:'الكلام'}. A word the library lacks in your spelling is searched in the spelling the books use and reported in `respelled_terms`: say so when you quote. [match=phrase] The words as a consecutive phrase, e.g. {query:'خيار المجلس'}. [match=near] The words within `distance` of each other, in any order. Phrase and near candidates come from an AND search and are verified in the full page text up to 1,500 pages or 12 s, so `total_verified` is not a library total; narrow `scope` when `candidate_cap_hit`. [match=exact] The exact string, typed WITH the diacritics / hamza form / digit system to enforce (it is not auto-diacritized) and matched as written; `preserve` decides which distinctions count. An AND search gathers at most 100 candidate pages and each is checked against the book's raw text; results keep candidate-relevance order. (match=words|phrase|near|exact only.) | |
| scope | No | Restrict to books, authors, categories, a Hijri period or the other filters below; get ids from shamela_find(kind='category') or shamela_find(kind='name'). Strongly recommended on common words for match=phrase|near (verification stops after 1,500 candidate pages or 12 s) and match=exact (at most 100 candidate pages are verified): a narrow scope is what lets that window cover the topic. match=boolean: an unscoped search over a large library is exhaustive but slow, so scope narrows the question and speeds it up. (match=words|phrase|near|exact|boolean only.) | |
| shape | No | How much of each hit to return. 'full' (default): every field, snippets included — ask for it when the answer will QUOTE the page. 'brief': book_id/page_id, printed_page, match_quality and matched_in_section, book metadata hoisted into a top-level `books` keyed by book_id, NO snippet — which pages, how well each matched and how to cite them, for a fraction of the characters, so far more rows survive the budget. 'index': book_id/page_id only, to choose what to read before paying to read it. Requires the 'shape.full_brief_index' capability (see shamela_get_brief). (match=words|phrase|near|batch only.) | |
| all_of | No | The three lists are ONE Lucene BooleanQuery over the whole index: all_of MUST, any_of SHOULD (at least one), none_of MUST_NOT. AND — terms that must ALL appear on the page; a multi-word term is itself AND-searched (its words co-occur; not a phrase). Leave empty to rely on any_of, but not both: BAD_ARG. Results are ranked by relevance. E.g. {match:'boolean', all_of:['الوقف'], any_of:['المسجد','المقبرة'], none_of:['البيع'], scope:{category_ids:[17]}}. (match=boolean only.) | |
| any_of | No | OR — at least ONE of these terms must appear on the page. Union of every term's hit set, then intersected with the all_of result. Leave empty to rely on all_of. (match=boolean 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. (match=words|phrase|near|exact|boolean only.) | |
| none_of | No | NOT — pages containing ANY of these terms are excluded, across the whole index (a MUST_NOT clause, not a subtraction inside a sampled window). Optional. (match=boolean only.) | |
| options | No | Search options: morphology, wildcards, sort, search_in (body/foot), relax_when_empty. Defaults to body+foot, no toggles. preserve_* redirect to shamela_search(match='exact'). E.g. {query:'كلم', options:{morphology:true}}. (match=words only.) | |
| queries | No | Several wordings of one question, run concurrently to assemble its evidence; results are merged, deduped by (book_id, page_id) and attributed to the probes that found each page (`probe_ids`): a page several probes found is corroboration across wordings, not a duplicate. Every probe's scope must carry book_ids, author_ids, category_ids or madhab, else the whole call is BAD_ARG. A probe that errors or outlasts deadline_ms is reported in its own slot and sets `incomplete`: a thin result is then not the library being silent. E.g. {queries:[{query:'الوتر واجب', scope:{category_ids:[14,19]}}, {query:'حكم صلاة الوتر', mode:'near', scope:{madhab:['hanafi']}}]}. (match=batch only.) | |
| distance | No | For match='near': maximum word span from the FIRST to the LAST query word, counted inclusively — 1 = adjacent, 2 allows one word between two query words. Ignored for match='phrase'. Suits fiqh terms that sit close but not adjacent: {match:'near', query:'بيع قبض', distance:5, scope:{category_ids:[17]}}. Default: 5. (match=phrase|near only.) | |
| preserve | No | Which distinctions to enforce when each candidate is verified; at least one must be true (none = BAD_ARG), and every unset feature folds. E.g. {query:'أحمد', preserve:{preserve_hamza:true}}, {query:'عِلْم', preserve:{preserve_diacritics:true}}. (match=exact only.) | |
| search_in | No | [match=phrase|near] Which page sections to verify the phrase in: body (matn), foot (footnotes). Default both; a hit's `matched_in_section` says where it was found. [match=boolean] Which page sections every clause (all_of, any_of and none_of alike) looks in: body (matn), foot (footnotes). Default ['body','foot']. (match=phrase|near|boolean only.) | |
| deadline_ms | No | Wall-clock budget for the whole batch. Probes still running when it expires are reported with status='timeout' and contribute nothing. A timeout is NOT a negative finding — it means the question was not fully asked. Default: 8000. (match=batch only.) | |
| exclude_pages | No | Exact pages to keep out — the pages a previous round already returned. Excluding these rather than whole books is what lets a follow-up search find MORE evidence in a book that has already contributed some. (match=words|phrase|near 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). | |
| exclude_book_ids | No | Book ids to keep out of the results entirely. (match=words|phrase|near only.) | |
| exclude_author_ids | No | Exclude every book by these authors. (match=words|phrase|near only.) | |
| max_total_passages | No | Hard cap on merged rows returned. Rows are ordered by match quality then probe agreement before the cut, so the cap drops the weakest evidence rather than an arbitrary tail. `truncated` says whether it fired. Default: 60. (match=batch only.) | |
| exclude_category_ids | No | Exclude every book on these shelves. (match=words|phrase|near only.) | |
| exclude_work_group_ids | No | Exclude every catalogue entry of these works — all printings at once. This is the one to use after a round returned «صحيح البخاري - ط السلطانية»: excluding that book_id alone leaves the other seven entries of group 1681 free to return the same text again as if it were a second source. (match=words|phrase|near only.) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | 'phrase' or 'near', as searched. (match=phrase|near only.) | |
| books | No | shape 'brief' only: book metadata keyed by book_id, hoisted off the rows. (match=words|phrase|near|batch only.) | |
| notes | No | Caveats about how the expression was evaluated. (match=boolean only.) | |
| query | No | The query as received. (match=words|phrase|near|exact only.) | |
| all_of | No | AND terms, as searched. (match=boolean only.) | |
| any_of | No | OR terms, as searched. (match=boolean only.) | |
| offset | No | Offset this page started at. (match=words|phrase|near|exact|boolean only.) | |
| probes | No | One report per probe, in request order. (match=batch only.) | |
| by_book | No | Returned rows per book name. (match=batch only.) | |
| none_of | No | NOT terms, as searched. (match=boolean only.) | |
| results | No | [match=words|phrase|near] Matching pages. shape 'full': book_id, book_name, author_name, category, book_date, work_group_id, madhab fields, page_id, printed_page, matched_in, match_quality ('exact_phrase' | 'near' | 'all_terms' | 'relaxed': a near miss is not a located quotation), matched_in_section ('body' | 'footnote' | 'both'; 'footnote' = the editor's voice, not the author's), snippet_body/snippet_foot (<mark> around matches). shape 'brief' drops book metadata into `books`; 'index' keeps ids only. [match=exact] Verified pages: book_id, book_name, author_name, category, book_date, page_id, printed_page, matched_in (sections holding the exact form), snippet. [match=boolean] Matching pages: book_id, book_name, author_name, category, book_date, madhab fields, page_id, printed_page, matched_in, matched_terms, snippet_body, snippet_foot. [match=batch] Merged page rows (as shamela_search(match='words'), per `shape`) plus probe_ids (every probe that found the page), ordered by match_quality then probe agreement. A 'footnote' matched_in_section is the editor's voice. | |
| coverage | No | Roll-up of hits by_category and by_century (the whole sample), by_book and by_author (the largest top_n only, so they do not sum to it) and edition_groups (one work under several catalogue entries: one source, not corroboration). A census only when sample_is_complete; otherwise a top-scoring sample of sampled_hits. (match=words only.) | |
| distance | No | Word span used for mode 'near'. (match=phrase|near only.) | |
| has_more | No | True when another page exists; call again with `next_offset`. (match=words|phrase|near|exact|boolean only.) | |
| preserve | No | The preserve_* flags enforced on this call. (match=exact only.) | |
| returned | No | Rows in `results` on this call. (match=words|phrase|near|exact|boolean only.) | |
| exclusion | No | What the `exclude_*` parameters removed. Present only when used. (match=words|phrase|near only.) | |
| truncated | No | ||
| incomplete | No | True when any probe errored or timed out: a thin result is then not the library being silent. (match=batch only.) | |
| total_hits | No | [match=words] Every match in scope, not just the rows returned. [match=boolean] Exact count of pages matching the whole expression. (match=words|boolean only.) | |
| next_offset | No | Offset of the next page. Absent on the last page. (match=words|phrase|near|exact|boolean only.) | |
| scope_count | No | Books in the resolved scope; -1 when unscoped. (match=words|phrase|near|boolean only.) | |
| rows_dropped | No | ||
| edition_groups | No | Works present under several catalogue entries in these rows: read each as one source. (match=batch only.) | |
| paging_ceiling | No | Deepest offset paging can reach. Present only when the request went past it: narrow the scope instead of paging further. (match=words|boolean only.) | |
| total_verified | No | Matches confirmed within the scanned window, not a library total. (match=phrase|near|exact only.) | |
| zero_hit_terms | No | Query words with no entry in the library as spelled. A zero then reflects spelling, not the topic. (match=words|phrase|near|exact|boolean only.) | |
| respelled_terms | No | {typed, searched_instead, hits}: a word absent as typed was searched in the spelling the books use. (match=words only.) | |
| terms_truncated | No | True when the query had more words than are searched. (match=words only.) | |
| relaxed_of_terms | No | Word count the relaxed match is measured against. (match=words only.) | |
| scope_resolution | No | Requested book_ids split into resolved and `dropped` (not in the catalogue, never searched). (match=words|phrase|near only.) | |
| candidate_cap_hit | No | True when the candidate window filled up: more matches may exist outside it; narrow the scope. (match=phrase|near|exact only.) | |
| normalized_tokens | No | The query after Arabic folding, as actually searched. (match=words only.) | |
| relaxed_min_match | No | Set when no page held every word: hits carry at least this many of `relaxed_of_terms`. (match=words only.) | |
| truncation_message | No | ||
| morphology_fallback | No | True when the literal search found nothing and was re-run with morphology (root forms). (match=words only.) | |
| unattributable_books | No | Books excluded by scope.madhab because no school can be established for them. (match=words|phrase|near only.) | |
| total_unique_passages | No | Distinct pages found across all probes, before the max_total_passages cut. (match=batch only.) | |
| zero_due_to_exclusion | No | True when pages matched but every one was excluded: not evidence of absence. (match=words|phrase|near only.) | |
| morphology_expanded_to | No | options.morphology only: exactly what was searched, per word. Roots are ambiguous and every reading is kept («كتب» also searches تبب/توب/وتب, perdition and repentance), so results are a SUPERSET of the word asked for. (match=words only.) | |
| total_candidates_scanned | No | Candidate pages verified against the page text. (match=phrase|near|exact only.) |