The search_library tool

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

This is one of 37 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

Parameter	Required	Type	Notes
query	yes	string	Arabic text only. A quoted wording works best; a topic also works.
scope	yes	string	One of twelve names — see Choosing a scope. This tool will not run without one.
limit	no	integer	Passages 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 an error, not an empty result:

Query has no searchable Arabic words.

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.

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:

Field	Meaning
passages	The hits, described below.
relaxedToTokens	true when the exact phrase was not found and a looser word search answered instead.
scope	The scope that was searched, echoed back.
booksSearched	How many books were in that scope.
totalMatches	How many pages matched in total, of which you received up to limit. Can be null on the fallback pass.
note	Present only when the result needs a caveat — see below.

Each entry in passages:

Field	Meaning
book	Title including the printing, e.g. صحيح البخاري - ط السلطانية.
author	The author’s name.
authorDied	Year of death in AH, or null if unknown.
printedPage	Volume and page as that printing paginates it, e.g. 1/ 6.
arabic	The passage itself, verbatim, with all markup removed.
matchedIn	body, footnote, both, or unknown — where the words were found.
matchQuality	How the match was made, e.g. exact_phrase.
bookId, pageId	Internal identifiers, stable enough to cite in a bug report.

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:

Field	Value
book	صحيح البخاري - ط السلطانية
author	البخاري
authorDied	256
printedPage	1/ 6
matchedIn	body
matchQuality	exact_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_get_page. shamela_get_pages_range and shamela_get_book_section read further — see the full tool surface.