Skip to main content
Glama
This connector has been deprecated

Search page text (words, phrase, exact, boolean, batch)

shamela_search
Read-onlyIdempotent

Full-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 preserve flag.

  • 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 queries run 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

NameRequiredDescriptionDefault
limitNoMaximum number of results to return (1-100, default 20). (match=words|phrase|near|exact|boolean only.)
matchNoSelects what the call does: words | phrase | near | exact | boolean | batch. Default words.
queryNo[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.)
scopeNoRestrict 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.)
shapeNoHow 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_ofNoThe 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_ofNoOR — 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.)
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. (match=words|phrase|near|exact|boolean only.)
none_ofNoNOT — 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.)
optionsNoSearch 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.)
queriesNoSeveral 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.)
distanceNoFor 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.)
preserveNoWhich 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_inNo[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_msNoWall-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_pagesNoExact 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_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).
exclude_book_idsNoBook ids to keep out of the results entirely. (match=words|phrase|near only.)
exclude_author_idsNoExclude every book by these authors. (match=words|phrase|near only.)
max_total_passagesNoHard 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_idsNoExclude every book on these shelves. (match=words|phrase|near only.)
exclude_work_group_idsNoExclude 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

NameRequiredDescriptionDefault
modeNo'phrase' or 'near', as searched. (match=phrase|near only.)
booksNoshape 'brief' only: book metadata keyed by book_id, hoisted off the rows. (match=words|phrase|near|batch only.)
notesNoCaveats about how the expression was evaluated. (match=boolean only.)
queryNoThe query as received. (match=words|phrase|near|exact only.)
all_ofNoAND terms, as searched. (match=boolean only.)
any_ofNoOR terms, as searched. (match=boolean only.)
offsetNoOffset this page started at. (match=words|phrase|near|exact|boolean only.)
probesNoOne report per probe, in request order. (match=batch only.)
by_bookNoReturned rows per book name. (match=batch only.)
none_ofNoNOT terms, as searched. (match=boolean only.)
resultsNo[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.
coverageNoRoll-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.)
distanceNoWord span used for mode 'near'. (match=phrase|near only.)
has_moreNoTrue when another page exists; call again with `next_offset`. (match=words|phrase|near|exact|boolean only.)
preserveNoThe preserve_* flags enforced on this call. (match=exact only.)
returnedNoRows in `results` on this call. (match=words|phrase|near|exact|boolean only.)
exclusionNoWhat the `exclude_*` parameters removed. Present only when used. (match=words|phrase|near only.)
truncatedNo
incompleteNoTrue when any probe errored or timed out: a thin result is then not the library being silent. (match=batch only.)
total_hitsNo[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_offsetNoOffset of the next page. Absent on the last page. (match=words|phrase|near|exact|boolean only.)
scope_countNoBooks in the resolved scope; -1 when unscoped. (match=words|phrase|near|boolean only.)
rows_droppedNo
edition_groupsNoWorks present under several catalogue entries in these rows: read each as one source. (match=batch only.)
paging_ceilingNoDeepest offset paging can reach. Present only when the request went past it: narrow the scope instead of paging further. (match=words|boolean only.)
total_verifiedNoMatches confirmed within the scanned window, not a library total. (match=phrase|near|exact only.)
zero_hit_termsNoQuery 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_termsNo{typed, searched_instead, hits}: a word absent as typed was searched in the spelling the books use. (match=words only.)
terms_truncatedNoTrue when the query had more words than are searched. (match=words only.)
relaxed_of_termsNoWord count the relaxed match is measured against. (match=words only.)
scope_resolutionNoRequested book_ids split into resolved and `dropped` (not in the catalogue, never searched). (match=words|phrase|near only.)
candidate_cap_hitNoTrue when the candidate window filled up: more matches may exist outside it; narrow the scope. (match=phrase|near|exact only.)
normalized_tokensNoThe query after Arabic folding, as actually searched. (match=words only.)
relaxed_min_matchNoSet when no page held every word: hits carry at least this many of `relaxed_of_terms`. (match=words only.)
truncation_messageNo
morphology_fallbackNoTrue when the literal search found nothing and was re-run with morphology (root forms). (match=words only.)
unattributable_booksNoBooks excluded by scope.madhab because no school can be established for them. (match=words|phrase|near only.)
total_unique_passagesNoDistinct pages found across all probes, before the max_total_passages cut. (match=batch only.)
zero_due_to_exclusionNoTrue when pages matched but every one was excluded: not evidence of absence. (match=words|phrase|near only.)
morphology_expanded_toNooptions.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_scannedNoCandidate pages verified against the page text. (match=phrase|near|exact only.)

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 declare readOnly/idempotent/non-destructive, so the bar is low, yet the description adds substantial behavior: relaxed_min_match retry, EMPTY_SCOPE, candidate caps (1,500 pages/12 s for phrase/near, 100 for exact), deadline timeouts framed as 'not a negative finding', respelled_terms, and exclusion semantics. This is well beyond what the annotations convey.

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?

Front-loaded with the resource and a per-mode breakdown, and nearly every sentence carries routing or rule content. It is dense and long, and some match-mode detail overlaps the schema's own parameter text, but on balance the length is earned by the tool's 22-parameter surface.

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?

For a highly complex tool (22 params, nested scope, batch mode, enums), the description covers mode selection, scoping, pagination, follow-up exclusions, and error states. An output schema exists, so return-format gaps are not the description's burden.

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%, establishing a baseline of 3, but the description adds cross-parameter meaning not obvious from the schema alone — e.g. 'a parameter of another match value is refused', the concurrency/merge/dedup behavior of batch probes, and the follow-up-round exclusion strategy. Useful synthesis rather than pure repetition.

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 — 'Full-text search inside the pages (matn and footnotes) of installed books' — and immediately decomposes the tool by match mode. It explicitly distinguishes itself from siblings (headings → shamela_find, verses → shamela_lookup_quran, hadith → shamela_lookup_hadith), so an agent can route 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?

Gives explicit when-to-use rules per mode (words = every word required, phrase = quotation, exact = typed distinctions, boolean = whole-index exhaustive, batch = 1–24 probes), plus scope guidance (omit madhab for comparative questions, set citable_only before quoting) and a full 'Instead:' routing block. When-not and alternatives are both 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