Skip to main content
Glama

Tafsir coverage and texts for an ayah

shamela_lookup_tafsir
Read-onlyIdempotent

Tafsir 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

NameRequiredDescriptionDefault
ayaNoVerse number within the surah, 1..N; requires `surah`.
modeNoSelects what the call does: coverage | texts. Default coverage.
surahNoSurah number 1..114; requires `aya`. Alternative to aya_id.
aya_idNoCumulative 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_idsNoRestrict 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_sourcesNoMaximum 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_onlyNoIf 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_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).

Output Schema

NameRequiredDescriptionDefault
ayaNo
noteNoCaveat: the index is curated, so unknown status is not absence.
booksNoEvery tafsir-shelf book plus index hits, ordered by status, installed first, then book_id; a long list is cut (rows_dropped). (mode=coverage only.)
surahNo
totalNoDistinct books the index maps to this verse, installed or not. (mode=coverage only.)
aya_idNoCumulative verse id, 1..6236.
totalsNoCount of books in each coverage status. (mode=coverage only.)
fetchedNoSources whose text was read. (mode=texts only.)
resultsNoThe index hits alone, repeating books[] rows; filtered by downloaded_only (false adds hits whose text is not installed, downloaded:false). (mode=coverage only.)
sourcesNoRead 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.)
_displayNo (mode=texts only.)
returnedNoRows in `results`. (mode=coverage only.)
truncatedNo
surah_nameNo
rows_droppedNo
coverage_noteNo (mode=coverage only.)
index_entriesNoRaw index rows; exceeds `total` when commentary spans pages. (mode=coverage only.)
total_indexedNoBooks the curated index maps to this verse. (mode=texts only.)
remaining_book_idsNoIndexed sources not read in this call; pass as book_ids to continue. (mode=texts only.)
truncation_messageNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Even with annotations already declaring readOnly/idempotent/non-destructive, the description adds substantial behavioral context: the exact status values returned (indexed_covers, indexed_no_entry_for_this_aya, not_indexed_coverage_unknown) and the warning that these are NOT evidence a book is silent; that text is read only from index-mapped pages, never a search guess; and that `note`/`remaining_book_ids` drive the next call. 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?

Purpose is front-loaded and the mode-by-mode organization is logical, with a concrete example closing it out. The coverage-mode sentence is a long run-on dense with parentheticals, so it is not maximally scannable, but nearly every clause carries actionable information.

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 an 8-parameter, dual-mode tool with an output schema, the description covers the mode semantics, status vocabulary, pagination/continuation via remaining_book_ids, and where the structured output lives. Nothing an agent needs to invoke it correctly is missing, and return-value detail is rightly left to the output schema.

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 coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning: the aya_id vs surah+aya exclusivity with a BAD_ARG outcome, the semantics of book_ids ordering and non-indexed books being reported as status, and the response_format character-budget tradeoff. This goes past restating field docs.

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?

Opens with a concrete verb+resource ('Tafsir on one verse') and immediately disambiguates the two operating modes (coverage vs texts). It also implicitly separates itself from siblings like shamela_lookup_quran and shamela_lookup_hadith by naming the resource and the coverage/text distinction. An agent can tell what this does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes when to pick each mode — coverage to discover which books cover the verse, texts to pull attributed commentary — and the schema reinforces this ('Use shamela_lookup_tafsir(mode="coverage") to see which books the index covers'). It does not state when to prefer a sibling lookup tool instead, so the routing guidance is strong but not exhaustive.

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