Skip to content

shamela_search_library: search Arabic books with citations

Parameters and result fields of shamela_search_library, the MCP tool that returns verbatim Arabic passages with edition, page and a Maktabah link.

On this page

Three parameters. It searches a named slice of the library and returns passages with their citations attached.

This is one of 15 tools, and the one to try first — it is the only search that refuses to run unscoped and that tells you how it matched. For everything it cannot do, see the full tool surface.

Parameters

ParameterRequiredTypeNotes
queryyesstringArabic text only. A quoted wording works best; a topic also works.
scopeyesstringOne of twelve names — see Choosing a scope. This tool will not run without one.
limitnointegerPassages to return, 1–10. Defaults to 5.

scope being required is the single most important thing about this tool, and the scopes page explains why in full: unscoped, this library ranks by how often a word appears, which buries the books you actually want.

The query must be in Arabic

The library is Arabic and so is the index. A query with no Arabic words is rejected outright — it is a tool error (isError), not an empty result, and the message tells the model what to do:

The library is Arabic, so the query must contain Arabic words. Translate the search terms into Arabic and call again, for example «إنما الأعمال بالنيات» for “actions are judged by intentions”.

That applies to English (prayer intention) and to transliteration (innama al-a'mal bil-niyyat) alike. If your assistant is working from an English question, it has to translate the search terms into Arabic before calling this tool. Nothing translates them for it. The unscoped search tool behaves the same way.

Diacritics do not matter. انما الاعمال بالنيات and إِنَّمَا الْأَعْمَالُ بِالنِّيَّاتِ return the same results, so there is no need to vowel a query or strip vowels from one you copied.

What comes back

A result object with the passages and some context about the search itself. The shape is published as the tool’s outputSchema in tools/list, so a client can read it without this page:

FieldMeaning
passagesThe hits, described below.
relaxedToTokenstrue when the exact phrase was not found and a looser word search answered instead.
scopeThe scope that was searched, echoed back.
booksSearchedHow many books were in that scope.
totalMatchesHow many pages matched in total, of which you received up to limit. Can be null on the fallback pass.
notePresent only when the result needs a caveat — see below.

Each entry in passages:

FieldMeaning
bookTitle including the printing, e.g. صحيح البخاري - ط السلطانية.
authorThe author’s name.
authorDiedYear of death in AH, or null if unknown.
printedPageVolume and page as that printing paginates it, e.g. 1/ 6.
arabicThe passage itself, verbatim, with all markup removed.
matchedInbody, footnote, both, or unknown — where the words were found.
matchQualityHow the match was made, e.g. exact_phrase.
bookId, pageIdThe page’s Shamela identifiers.
edition, editor, publisherBibliographic data for that printing. Present only when the library has them; never guessed.
sourceUrlhttps://qurangallery.com/maktabah/book/{bookId}/{pageId}, the same page in the Maktabah reader. Credit al-Maktaba al-Shamela when you quote.

The two passes

Search runs the strict pass first, then falls back:

  1. Exact phrase. Your words, in order, as written.
  2. Words together, if the phrase found nothing — the same words anywhere on a page, in any order.

You are always told which one answered, via relaxedToTokens. That flag is not bookkeeping; it changes what the result means, and Reading a result covers how.

The fallback exists because transmitted wording varies between printings. Searching إنما الأعمال بالنيات as a strict phrase finds one book and misses Sahih al-Bukhari, which prints بالنية. The looser pass finds al-Bukhari, Ibn Majah, Abu Dawud and al-Nasa’i. Running only the strict pass would turn a famous, well-attested hadith into a “not found” — which in this subject is its own kind of false claim.

A worked example

Searching إنما الأعمال بالنيات in the hadith-primary scope returns, among others:

FieldValue
bookصحيح البخاري - ط السلطانية
authorالبخاري
authorDied256
printedPage1/ 6
matchedInbody
matchQualityexact_phrase
arabic…عُمَرَ بْنَ الْخَطَّابِ ﵁ عَلَى الْمِنْبَرِ، قَالَ: سَمِعْتُ رَسُولَ اللهِ ﷺ، يَقُولُ: «إِنَّمَا الْأَعْمَالُ بِالنِّيَّاتِ…

With booksSearched: 8 and relaxedToTokens: false — eight edition-pinned collections, and the exact phrase was found.

The leading … is deliberate: it marks a passage that begins mid-sentence, because the excerpt is a window onto the page rather than the whole page.

Excerpt length

Passages are capped at roughly 1,600 Arabic characters and truncated with a trailing … if longer. This tool returns quotations, not books.

If you need the whole page rather than the matching window, take the bookId and pageId from a result and pass them to shamela_read (unit: 'page'). shamela_read (unit: 'range') and shamela_read (unit: 'section') read further — see the full tool surface.

Next steps

Edit this page on GitHub