Tafsir coverage and texts for an ayah
shamela_lookup_tafsirTafsir on one verse (aya_id OR surah + aya, else BAD_ARG). mode=coverage (default): which tafsir books cover it, fetching no text — shelves 3 (tafsir) and 4 (Qur'anic sciences; not 5, tajwid and qira'at) crossed with Shamela's curated tafsir index, plus index hits from other shelves (in_tafsir_categories:false). Status per book: indexed_covers (with page_id), indexed_no_entry_for_this_aya, or not_indexed_coverage_unknown — NOT evidence the book is silent.
mode=texts: the commentary from several books in one call, each attributed (book, author, death year, printed page), read only from pages the index maps to the verse, never a text-search guess. Each source's note names the next call when its text continues. Example: {surah:2, aya:255, book_ids:[1503, 639]}.
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_lookup_tafsir"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| aya | No | Verse number within the surah, 1..N; requires `surah`. | |
| mode | No | Selects what the call does: coverage | texts. Default coverage. | |
| surah | No | Surah number 1..114; requires `aya`. Alternative to aya_id. | |
| aya_id | No | Cumulative verse id, 1..6236 (e.g. 262 = 2:255). Give this OR surah + aya, not both; a reference that disagrees with surah/aya is BAD_ARG. | |
| book_ids | No | Restrict to these tafsir books, read in the order given (omit it and the installed indexed books are read earliest author first). Books not present in the curated index for this aya are reported with an explicit status instead of text. Use shamela_lookup_tafsir(mode='coverage') to see which books the index covers. (mode=texts only.) | |
| max_sources | No | Maximum number of sources to fetch text for (1-10, default 5). The response-size budget can stop earlier; `remaining_book_ids` lists the sources not read, to pass as book_ids next. (mode=texts only.) | |
| downloaded_only | No | If true (default), list only books whose text is installed on this server. false also lists books the curated index maps to this aya whose text is not installed (downloaded:false) — still useful as catalogue references. (mode=coverage 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 |
|---|---|---|---|
| aya | No | ||
| note | No | Caveat: the index is curated, so unknown status is not absence. | |
| books | No | Every tafsir-shelf book plus index hits, ordered by status, installed first, then book_id; a long list is cut (rows_dropped). (mode=coverage only.) | |
| surah | No | ||
| total | No | Distinct books the index maps to this verse, installed or not. (mode=coverage only.) | |
| aya_id | No | Cumulative verse id, 1..6236. | |
| totals | No | Count of books in each coverage status. (mode=coverage only.) | |
| fetched | No | Sources whose text was read. (mode=texts only.) | |
| results | No | The index hits alone, repeating books[] rows; filtered by downloaded_only (false adds hits whose text is not installed, downloaded:false). (mode=coverage only.) | |
| sources | No | Read only from pages the curated service/tafseer.db maps to this verse; there is no text-search fallback, which misattributes verses through shared phrases and the basmala. (mode=texts only.) | |
| _display | No | (mode=texts only.) | |
| returned | No | Rows in `results`. (mode=coverage only.) | |
| truncated | No | ||
| surah_name | No | ||
| rows_dropped | No | ||
| coverage_note | No | (mode=coverage only.) | |
| index_entries | No | Raw index rows; exceeds `total` when commentary spans pages. (mode=coverage only.) | |
| total_indexed | No | Books the curated index maps to this verse. (mode=texts only.) | |
| remaining_book_ids | No | Indexed sources not read in this call; pass as book_ids to continue. (mode=texts only.) | |
| truncation_message | No |