Quran Gallery MCP

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

Goes well beyond the readOnly/idempotent annotations by disclosing truncation behavior (4 body parts, ~4,000 chars, 2 without an API key), the metadata.complete=false signal, and the continuation call shamela_read. It also states error behavior for malformed or unheld ids. Slight gap: "the editor's words, never the author's" for footnotes is evocative but not fully operationalized.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Information-dense and front-loaded with the core action, and every clause carries distinct information. However, the middle is a long run-on sentence with nested em-dash asides, which costs readability for an agent parsing quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values need not be spelled out, yet the description still flags the truncation/continuation contract that the schema cannot express. Combined with the error semantics and sibling routing, nothing needed to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description earns above that by tying the id to a `search` result in prose and pointing to shamela_cite mode "printed_page" as the conversion path from printed references. It reinforces the id-derivation constraint rather than restating the format alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Read one library page whole by the id") and enumerates exactly what comes back: main text, footnotes under their own label, book/author/volume/page/edition metadata, and reader link. It distinguishes itself from siblings both positively (shamela_read, shamela_cite) and negatively ("Not a search").

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

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

Explicit routing: use shamela_read for unit "page", "range", or "section"; use shamela_cite mode "printed_page" to convert printed references into ids; this tool is not for searching. The agent knows precisely when this tool is and is not the right choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, but the description adds substantial behavioral context beyond them: a hard cap of 10 pages, the exact return shape, ranking being term-frequency based, the exact-phrase-first-then-split-words fallback, the meaning of the three title flags ([footnote match], [token match], [near match]), that empty results mean no page carries the words, and that a query with no Arabic words raises a tool error.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence front-loads the tool's identity, scope, and return contract, and every subsequent sentence carries real information. It is dense and slightly long, with the title-flag glossary and match-fallback detail sitting between the alternative-tool routing and the error note rather than in a clean order, but nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although an output schema exists and return values need not be explained, the description still covers limits, ranking, fallback matching, flag meanings, and error behavior for a single-parameter read tool. Nothing an agent needs to call it correctly or interpret empty results is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single `query` parameter's description already specifies Arabic text, an example, and the 2–6 word sweet spot, so the baseline is 3. The description adds one genuinely new constraint not in the schema — that a query without Arabic words returns a tool error — but otherwise does not add syntax or matching-mode detail to the parameter itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb, resource, and scope: search the whole classical Islamic library across 8,594 works with no filtering, returning up to 10 {id, title, url} pages that chain into `fetch`. It explicitly positions itself as the generic one-argument entry in the search/fetch pair and names the scoped siblings that answer research questions better, so an agent can separate it from shamela_search and shamela_search_library 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.

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

It gives explicit routing rules: use shamela_search_library for hadith/tafsir/fiqh questions because unscoped ranking is by term frequency and a poetry anthology can outrank Sahih al-Bukhari; use shamela_search to pin books, categories, or a madhhab, match exact/diacritized phrases, or paginate; use shamela_cite with mode "printed_page" for citations. The condition that selects each alternative is stated, not implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavior beyond them: failures surface via `status`, citable:false means Shamela's own numbering, BOOK_NOT_FOUND as an error, no arithmetic links printed number to page_id, and one printed page often spans several ids. It also flags which output fields (page_resolved, components.auto_numbered, notes[]) to inspect, though this overlaps somewhat with the existing output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads mode=citation before mode=printed_page and every sentence carries information. It is dense to the point of being hard to parse (fragments like 'Citations.', heavy em-dashes and « » glyphs), so it is efficient but not maximally scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, two-mode tool with an output schema, the description covers both modes, their dependencies, error surfaces, and the ambiguity case (omitting `part` reports matched parts instead of silently resolving). Nothing an agent needs in order to call it correctly appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema itself already annotates mode-specific applicability ('mode=citation only') and the full style enum. The description's parameter-level contribution is largely redundant ('it needs only the catalogue, plus the installed text'), so the baseline 3 applies even though the description is well-written.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The title and first paragraph state specific verbs and resources for both modes: mode=citation builds a citation for a book/page, mode=printed_page maps a printed citation to page_ids. It explicitly separates the two behaviors and names the sibling tools (shamela_find, shamela_read) it cooperates with, so an agent can distinguish it from the lookup and read tools 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.

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

It gives explicit when-to-use ('Call it whenever you attribute a quote') and explicit routing ('Resolve the work with shamela_find(kind=work) first; holding a page_id already, skip this'), plus a mode-selection rule (holding a page_id → skip printed_page). Alternatives and their preconditions are named rather than left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already establish the safe read-only/idempotent profile, and the description goes well past them: per-kind refusal of foreign parameters, pagination-until-has_more-false, EMPTY_SCOPE, the madhab filter's deliberate exclusion of unresolved-school books, 'downloaded:false → another edition ... or catalogue metadata only', and the warning that `name` always answers. These are operational traits an agent cannot infer from readOnlyHint/destructiveHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and the kind list are front-loaded, and the closing 'Instead:' block cleanly consolidates the anti-pattern routes. It is dense and long, but for a 7-mode, 18-parameter tool every bullet carries distinct operational content rather than filler, so the length is largely earned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-shape explanation is correctly omitted. Given the complexity — 7 modes, nested scope/options, 100% schema coverage — the description still supplies everything an agent needs to pick a mode, know what gets refused, know how to page, and know which sibling handles the adjacent job.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: that a parameter belonging to another kind is refused, that book/heading/author/period page with limit/offset, and that scope.category_ids should carry multiple ids when a subject spans shelves. That is meaningful beyond-schema guidance rather than restatement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a precise verb+resource framing — 'Catalogue lookup — which books, headings, authors and shelves exist, not page text' — that immediately scopes it against the content-searching sibling shamela_search. Each of the seven `kind` values is given its own concrete definition (book→titles/authors/publication lines, heading→chapter titles, etc.), so an agent can differentiate it from shamela_read, shamela_cite and shamela_get_details 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.

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

Explicit per-kind routing plus a closing rule that names alternatives by name: page text → shamela_search, a printed page → shamela_cite(mode='printed_page'), one book's headings → shamela_read(unit='toc'). It also states when NOT to use a mode ('name': always answers, so never use it to verify a citation; 'work': refuses rather than guesses). Both the when and the when-not are covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already establish read-only, idempotent, non-destructive, non-open-world behavior, but the description adds substantial traits they do not cover: it is constants-only, requires no library access, and 'does not fail', versus other tools whose strict input validation fails the whole call. It also discloses the caching contract via brief_hash, which is operationally important and absent from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first clause, followed by usage, caching, and failure semantics in a logical order, and the closing example is compact. It is dense and slightly long for a single-paragraph description, but each sentence carries distinct operational information rather than restating the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return values, and it does not. For a bootstrap tool it covers everything an agent needs: when to call, what it yields, the validation hazard, the caching strategy, and the fact that it cannot fail — nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single enum parameter is fully documented in the schema, so the baseline is 3. The description adds marginal value by giving concrete invocation examples ('{}' or '{response_format:\'json\'}') and by flagging response_format:'none' as a capability-gated argument, which tells the caller why that enum value may be rejected on an older build.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb+resource ('Return this server's machine-readable capability handshake') and enumerates the payload precisely: capabilities, numeric limits, retired tool names with replacements, and traps. This is clearly distinguishable from siblings like shamela_search or shamela_get_details, which operate on library content rather than server metadata.

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

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

It gives an explicit directive — 'Call it first from a programmatic client' — and explains the condition that makes it necessary: strict inputs mean an unsupported argument (shape, response_format:'none') is a hard validation error, and tools/list cannot reveal argument support. It also says how to use the result (gate each new argument on its capability string) and when to re-call (only when brief_hash changes).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantial context beyond them: the error codes, the null-means-unknown semantics for death year, the instruction never to supply a missing bibliographic field, cover-image token cost, and the response_format.none capability requirement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose followed by tight kind-scoped bullets; the routing line and error list are the only additions. Dense but nearly every clause carries information, though the record-field detail leans on the output schema's territory.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present the description needn't re-explain return values, yet it covers the decision context (installed vs not, same_group fallback), failure codes, and field-interpretation caveats. Nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema already documents kind, book_id, author_id, include_books, include_cover and response_format in detail. The description reinforces defaults ('kind=book, default', 'installed or not') but adds little parameter syntax beyond what the schema provides, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Catalogue record for one book ... or one author'), and the kind=book/kind=author bullets enumerate exactly what each mode returns. It distinguishes itself from siblings by noting shamela_read handles volumes and shamela_find handles title/subject lookups.

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

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

Explicit when-to-use guidance: 'When a reader tool says BOOK_NOT_DOWNLOADED, pick an installed entry from same_group or answer from this record.' It also routes two adjacent cases to shamela_read(unit='parts') and shamela_find(kind='book'), and names the two error codes that signal this tool's failure modes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

With readOnly/idempotent/non-destructive annotations already covering the safety profile, the description adds real behavioral depth: no offset, automatic one-word relaxation surfaced in `relaxed`, takhrij limited to key_index_books, SERVICE_KEY_NOT_FOUND semantics, and the downloaded:false catalogue-vs-installed distinction. These are constraints the agent cannot infer from annotations or schema alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the mode distinction and the highest-value caveats (no offset, takhrij scope) before the sibling routing. It is dense and slightly clause-heavy in places, and a few lines overlap with schema text, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, dual-mode, read-only lookup with an output schema present, the description covers what the schema cannot: mode semantics, result-window interaction, known error codes, and edition-availability caveats. Return values are correctly left to the output schema, so nothing an agent needs before calling is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is already 100%, so the baseline is 3, but the description contributes genuine cross-parameter reasoning the schema does not: that max_pages_scanned is 'the only result window' and `matches` never exceeds it regardless of `limit`, and that limit only cuts after key-bearing pages come first. It also explains the response_format='none' budget tradeoff between text and structuredContent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Find a hadith ... trace its takhrij') and splits the tool's two distinct behaviors (mode=search vs mode=sources) with concrete outputs for each. An agent can distinguish it from shamela_search and shamela_lookup_rijal purely from this text, since the description names those siblings and the boundary conditions that select between them.

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

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

Explicit routing guidance: narrator chains go to shamela_lookup_rijal(mode='isnad_search'), general text to shamela_search(match='words'), missing editions to shamela_get_details(kind='book'). It also states when to flip search_all_categories (to find who CITES vs who NARRATES) and when the sparse takhrij result should not be over-interpreted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare a safe read-only, idempotent operation, and the description adds substantial behavior beyond that: results are in mushaf order not relevance, zero hits usually indicate a misspelling, error codes BAD_ARG and AYA_NOT_FOUND are named, `count` continues across surah boundaries, and single-word search expands stems with reports in stem_expanded_to/query_form_hits. This is well past the annotation bar.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Content is front-loaded with the two mode behaviors and organized by mode rather than by parameter, which reads well for a dispatcher-style tool. It is dense and somewhat long, with a few clauses that echo the schema, but nearly every sentence carries routing or failure-handling value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, dual-mode tool with an output schema and nested options, the description covers mode selection, argument constraints, error signals, pagination fields (has_more/next_offset), and sibling routing. Since an output schema exists it is not obliged to document return values, yet the response fields it does mention are accurate and helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter in depth (including mutual exclusivity of aya_id vs surah/aya and the wildcards caveat). The description restates the mode split and the 'never both or neither' constraint but adds little parameter detail the schema lacks, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise verb+resource pair for each mode: 'find verses by Arabic words' (search) and 'fetch verses you can already cite ... by aya_id OR surah + aya' (aya). It explicitly distinguishes itself from shamela_lookup_tafsir (commentary) and shamela_search (words inside books), so an agent can route without opening sibling schemas.

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

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

It gives explicit when-to-use per mode (search for recall, aya for known citations) and names the alternatives with the condition that selects them: 'Commentary → shamela_lookup_tafsir; the words inside books → shamela_search(match=words)'. It even prescribes a fallback when search returns zero hits (drop a word or use wildcards).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, but the description adds substantial context: specific error codes (RIJAL_UNAVAILABLE, NARRATOR_NOT_FOUND, etc.), paging behavior, the fact that empty isnad_search results are not errors but a scope limitation, and a strong quality directive ('Quote verdicts as worded; never synthesize a grade'). This goes well beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but it is well-structured with clear mode bullets and rules. For a 16-parameter, 4-mode tool, the length is mostly justified, and the purpose is front-loaded. A few sentences could be tightened, but it largely earns its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description covers the essential context: mode distinctions, scope limits (only ten books indexed), error handling, paging, and alternatives. An output schema exists, so return values need not be explained, and annotations cover safety. The description is complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description reinforces mode behavior and parameter interactions (e.g., contains vs. transmission, paging ceiling), but the schema itself already provides detailed, example-rich descriptions for every parameter. The description adds little new semantic detail for individual parameters beyond what is in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Hadith narrators and isnad chains, from Shamela's rijal register and isnad index,' naming a specific resource and scope. It explicitly distinguishes itself from siblings: 'Instead: book authors → shamela_find(kind='author'); a hadith by its text → shamela_lookup_hadith(mode='search').' An agent can immediately tell what this tool does and what it does not.

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

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

Each mode is given explicit when-to-use guidance, including conditions and expected inputs ('narrators (default): a narrator by name → narrator_id...', 'narrator: one dossier by narrator_id...'). It names alternatives for adjacent tasks and states a key rule: 'a parameter of another mode is refused.' Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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.

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.

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.

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.

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.

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

Annotations only cover the read-only/safe profile; the description goes well beyond them with a size-budget model (~12,000 chars, body_has_more/body_part+1, next_start_page_id), truncation flags, the fact that page ids have gaps so ±1 stepping is wrong, and a named error taxonomy (PAGE_NOT_FOUND, TITLE_NOT_FOUND, BOOK_NOT_FOUND, BOOK_NOT_DOWNLOADED with remediation). This is exactly the operational context annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the overview and the unit list, then rules, then errors, then alternatives — a deliberate and correct ordering. Despite its length, almost every clause carries load (mode behavior, budget, id semantics, error recovery), and the dash-per-unit format is scannable rather than prose-bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter, six-mode dispatcher with an output schema, the description covers everything an agent needs: which unit to pick, which parameters belong to which unit, continuation on truncation, id semantics, and recoverable errors. Return-value shape is delegated appropriately to structuredContent and the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the per-parameter unit scoping is largely already in the schema. The description still adds cross-parameter semantics the schema cannot express: 'a parameter of another unit is refused', the continuation contract (feed next_start_page_id back in), and the budget interaction between range and section reads. That is real added meaning, though it does not restate every parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Starts with a specific verb+resource ('Read an installed book's text and structure by internal ids') and then enumerates the six distinct modes, each with what it returns (page → body/foot/printed label/prev-next ids; toc → headings with title_ids; parts → volumes). The closing 'Instead:' block names sibling tools and the conditions that route away from this one, so an agent can distinguish it from shamela_find, shamela_search and shamela_get_details without opening a schema.

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

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

Gives explicit when-to-use guidance per mode ('to read on past a hit or through a span', 'for a printed «vol./page» call shamela_cite first') plus negative routing: headings by words → shamela_find(kind='heading'), untitled «فصل» headings → shamela_search(match='words'), metadata → shamela_get_details. It also states a hard rule about what will be refused, which is the kind of exclusion guidance that prevents wrong calls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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.

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.

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.

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.

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.

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

Annotations already declare this a safe, idempotent, closed-world read, so the description's job is to add operational context, and it does: result ranking order (exact phrase, then all words, madhhab-first for a school scope, main text before footnote), the relaxedToTokens/note weakened-match flag, and the crucial negative-result semantics (no passages means absent from that scope, not the library). It also discloses error behavior for non-Arabic queries and unknown scopes. Not a 5 only because the cap interaction with paging is left to the sibling reference rather than spelled out.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and payload, then usage, then ranking and edge cases — a sensible order with no filler sentences. It is dense and clause-heavy in places (the ranking and madhhab notes are packed into single sentences), which costs a little readability against a genuine 5, but every sentence carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a 12-value scope enum, a hard limit cap, and a non-obvious negative-result meaning, the description covers the decisions an agent must make: which shelf, when to widen scope, how results are ordered, how to read weak matches, and how errors surface. An output schema exists, so return-shape explanation is optional, yet the passage fields are still summarized helpfully.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: scope is one shelf per call and must be re-called to widen, and a madhhab scope ranks that school's own books first, which is a ranking behavior the enum text does not state. Query phrasing guidance (quoted wording works best) duplicates the schema slightly rather than extending it, keeping this from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search) and scoped resource (one named shelf of the classical Islamic library, 8,594 works) and names the payload returned: verbatim Arabic with book, author, volume/page, edition and a reader link. It explicitly contrasts itself with shamela_search and shamela_read, so an agent can place it among siblings without opening a schema.

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

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

Gives an explicit when-to-use ("the default first search for hadith, tafsir, fiqh or creed"), explicit exclusions (isnads, narrators, diacritic-exact wording), and names the alternatives with the exact condition that selects each: shamela_search with match "words" for pinning books/categories or paging past 10, shamela_read with unit "page" for full pages. The one-shelf-per-call rule plus "call again with another shelf to widen" removes the main usage ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare this as a safe, idempotent read; the description goes well beyond them with latency expectations (6–9 ms literal vs seconds morphological), the coverage_capped:true top-5,000 sampling contract where breakdown counts are floors while total_hits stays exact, and the EMPTY_SCOPE / zero-hit outcomes. This is disclosure an agent cannot get from the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose and the key routing sentence, and every clause carries information (sampling caveat, error names, examples). It is dense and parenthetical-heavy, which costs some readability, but there is little slack to cut.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nested-scoped statistics tool with an output schema, the description covers what is needed to call it correctly: scope composition and intersection, id-resolution path, mode semantics, capping behaviour, and named error states. Nothing an agent must know before invoking it is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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 genuinely new detail: the literal-vs-morphological latency difference and the warning that morphological is often far broader than expected. It also supplies two concrete scope-shaped examples, though the per-parameter semantics largely restate the already thorough schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and resource — counts matching pages for a term plus its distribution by category, Hijri century, book and author — and immediately scopes it as 'Statistics only, never passages', which separates it from shamela_search without the agent needing to open either schema.

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

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

Explicit routing: use shamela_search(match='words') to retrieve passages, run this first to size a topic and choose scope.category_ids, and map names to ids via shamela_find(kind='category'). It also states the when-not case for mode ('literal' before planning retrieval, 'morphological' only to trace a root), covering alternatives and exclusion conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Well beyond the readOnly/idempotent annotations, it explains matching normalization (diacritics, tatweel, alef forms), what 'exact' and 'differences' mean, that matchedIn 'foot' is the editor's words not the author's, and the critical caveat that 'not_found' means only not-found-in-scope. It also discloses the preconditions (3+ Arabic words) and the error behavior with the fix named, plus the epistemic limit ('not a ruling', 'does not say whether a passage is authentic').

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the outcome and immediately followed by the when-to-use sentence; every caveat after that (not_found semantics, foot vs. text, authenticity disclaimer) carries decision-relevant weight. The disclaimer is stated twice in near-equivalent wording ('not that the quotation is false' / 'not a ruling'), which is the only wasted space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a verification tool with four parameters, an output schema, and full annotation coverage, nothing an agent needs before calling is absent: purpose, preconditions, error behavior, scope defaults, and the interpretation of the ambiguous result fields are all present. The output schema handles the return shape, and the description covers the parts of the result most likely to be misread.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the structured fields already carry the parameter definitions and the scope enum. The description adds real operational meaning on top: the precedence rule is restated in behavioral terms, the no-parameter default (whole library searched) is spelled out, and the 3-word minimum is framed as a hard error with a fix rather than a silent filter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Checks whether an Arabic quotation occurs in the classical library') plus the shape of the answer (book, author, volume/page, edition, main text vs. footnote). It implicitly separates itself from the keyword-search siblings by framing the use case as verifying a passage quoted from memory, but it never names those siblings the way a 5 would.

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

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

'Use it on a passage an assistant quoted from memory' states the triggering situation clearly, and the closing sentence explains the scope/bookId narrowing decision and the default (whole library). It stops short of naming an alternative tool or stating when not to use this one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.