Quran Gallery MCP

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is fully covered. The description adds the useful semantic note that footnotes are the editor's notes rather than the author's words, but the rest is return-shape detail already implied by the 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 the core action ('Read one library page by the id...') before the return details, with no filler sentences. The second sentence is long and packs several metadata items, but each earns its place as interpretive context.

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 single-page read tool with a full param schema, annotations, and an output schema, the description covers the essential concerns: where the id comes from and how the returned text/footnotes are organized. Nothing critical to correct invocation is missing, though sibling disambiguation could be stronger.

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 `id` parameter is fully documented there. The description reinforces the "{bookId}:{pageId}" format and its provenance from `search`, which is marginal added value over the schema, so 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?

States a specific verb (Read) and resource (one library page), and even gives the id shape "{bookId}:{pageId}". It ties itself to the `search` sibling that produces the id, so an agent can distinguish this retrieval tool from the many search_* 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?

It implies usage by telling the agent the id comes from `search`, which is genuine routing guidance. However, it offers no explicit when-not or comparison against near-neighbors like shamela_get_page, shamela_get_pages_range, or shamela_get_book_section, so the agent must infer when this is the right retrieval tool.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds substantial behavior: a 10-result cap, ranking by term frequency, the unscoped nature of the search, and the meaning of the '[footnote match]' and '[token match]' result qualifiers. These are result-interpretation behaviors an agent cannot infer from annotations or 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-loaded with purpose and return shape, then constraints, then the qualifier legend, then sibling routing. Every sentence carries distinct information (scope, return limit, tool chaining, language, result qualifiers, ranking, alternative) with no 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?

Even though an output schema exists, the description adds the fields an agent needs to act on results, including the id used for fetch, the result cap, and the qualifier legend. Combined with the sibling routing and language requirement, nothing essential to correct invocation 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 parameter is already documented as 'Arabic search text — a quoted wording or a topic.' The description's 'Query in ARABIC' and 'a quoted wording or a topic' largely restate the schema, so per the high-coverage baseline a 3 is correct.

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'), the exact resource scope ('all 8,594 works of the classical Islamic library'), and the return contract (up to 10 pages as {id, title, url}). It also explicitly contrasts itself with the sibling search_library ('unscoped... ranks by term frequency'). An agent can distinguish it from search_library and fetch 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 routing: 'for a hadith, tafsir or fiqh question, search_library with a scope ranks the standard sources first,' naming the alternative and the condition that selects it. It also chains usage to the fetch tool ('Pass an id to `fetch` to read that page') and imposes a hard input constraint ('Query in ARABIC').

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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the description is free to add real behavioral depth — and it does: the two-pass strategy (exact phrase first, token fallback), that it reports which pass answered, the scope requirement's rationale, and which optional metadata fields are only present 'when the library records them'. That is unusually informative beyond 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?

Four sentences, all doing work, with the corpus scope and return payload front-loaded and the escalation to the scope constraint last where it lands hardest. Density is high but no sentence is filler; slightly more compression of the output-field list would help.

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 spell out return values, yet it summarizes them usefully and covers the required-vs-optional parameter distinction. Nothing critical is missing for correct invocation, though a hint about result breadth relative to limit (max 10) or scope selection strategy is absent.

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 earns above baseline by explaining *why* scope is mandatory and how ranking degrades without it, which the enum alone cannot convey. The query parameter gets the same 'quoted wording works best' hint already in the schema, so that part adds nothing.

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 and resource (search a Maktabah al-Shamela library of 8,594 classical works) and enumerates exactly what comes back: book, author, printed edition page, verbatim Arabic, editor/publisher, and a sourceUrl. It is very clear on its own, but it never contrasts itself with the many sibling search tools (shamela_search_phrase, shamela_search_exact, shamela_search_boolean, search), leaving the agent to infer the boundary.

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 explains a usage-relevant constraint — that a scope is required because unscoped term-frequency ranking surfaces a poetry anthology above a hadith collection — and notes the exact-phrase-then-token fallback. However, it gives no when-to-use-versus-alternative guidance: nothing tells the agent why to pick this over shamela_search_phrase, shamela_search_exact, or shamela_search_boolean for the same query.

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 the safety profile (readOnly, idempotent, non-destructive), so the description spends its budget on non-obvious behavior: constraints AND-combine (intersection, never union), at least one of the four bounds is required, and the near-empty-result interpretation. It also discloses the hand-off artifact (`book_ids[]` to pass as `scope.book_ids`), which no annotation could 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 highest-value distinction (AND vs. union, and the composed/died column caveat) before the mechanics and return fields. It is dense but each paragraph carries a distinct load; the main cost is the duplicated Arabic header line and the 98.5% statistic restated from 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?

No output schema exists, and the description compensates by enumerating the returned fields (book_id, book_name, main author + death_year, book_date, category, downloaded flag) and the `book_ids[]` payload for chaining into `scope.book_ids`. With the filter semantics, requirement rule, and return shape all covered, an agent has everything needed to call it correctly.

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 docs already exist (including the 98.5% overlap note, which the description partly repeats). What the description adds beyond the schema is the cross-parameter rule that at least one of the four bounds must be supplied and the pairing guidance between `composed_*` and `died_*` — real value, but a substantial fraction of the text is duplicative of 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?

States a specific resource (books) and an explicit filter axis (Hijri period bounds on composition/`book_date` and on the main author's death year), and names the sibling family it must not be confused with (`scope.period_*`). An agent can tell it apart from `shamela_search_books` or a period scope 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?

Explicitly says when to use it ('when a question distinguishes books composed in a period from books by authors who died in a period') with a concrete example (`died_from:700, died_to:800`). It also says when the tool is the wrong instrument — a composed-vs-died question — and warns that a near-empty result means the distinction is unavailable rather than that no book exists.

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 substantial behavioral context beyond them: strict validation makes unknown arguments a hard failure (not silently ignored), the brief works even without the Shamela install, brief_hash supports caching, and traps[] pairs failure modes with the exact response field that proves them. This is rich disclosure that the annotations alone do not 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?

Dense and front-loaded — the purpose and 'call first' instruction lead, followed by return contract, validation caveat, traps explanation, and caching. It is long, but nearly every sentence carries distinct operational information; a modest trim would still improve it.

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 values need no prose, yet the description still enumerates the key returned fields (capabilities, server_version, limits, traps, brief_hash). For a 1-param meta tool this is fully complete.

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?

With only one parameter and 100% schema coverage, the schema already carries the semantics; baseline is 3. The description adds value by clarifying the response_format examples and tying 'none' to the capability gate, but most parameter detail lives 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?

States a specific function: a capability handshake and operating brief that returns capabilities[], server_version, limits, and traps[]. It is unmistakably a meta/discovery tool, clearly distinguished from all the shamela_get_*/shamela_search_* siblings that do actual retrieval.

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 sequencing instruction: 'Call this FIRST, before sending any argument you are not certain this build accepts.' It also gives the negative case (gate each new argument on its capability string) and explains why tools/list cannot substitute. 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description then adds genuinely useful behavioral detail the annotations cannot: death_year is null if unknown or modern, death_text is a display string, and the book list includes co-authored works with a downloaded flag. With no output schema present, this return-shape disclosure carries real weight.

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, then returns, then the parameter hint and example — a sensible order with no wasted discussion. Minor redundancy: the Arabic line 'جلب بيانات مؤلف' merely restates the English opening sentence, and the example sentence is somewhat elaborate.

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?

Because no output schema exists, the description does the work of enumerating the return payload (author_name, death_year, death_text, per-book fields), which is exactly what an agent needs to consume the result. The only real gap is that it never tells the agent how to find a valid author_id, which matters for a tool whose sole required input is an opaque id.

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 goes beyond the schema by explaining the purpose of include_books (skip the book list when only name/death year is needed) and by giving a concrete call example (author_id:57). It adds a modicum of meaning over the structured fields, though response_format's elaborate schema text needs no help.

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 ('Fetch metadata for an author by author_id') and enumerates what is returned, so the agent knows exactly what this tool produces. However, it never differentiates itself from the many sibling lookup tools (e.g. shamela_search_authors as the way to obtain an author_id), so sibling disambiguation is left implicit.

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?

There is usable guidance for one parameter ('Use include_books=false to skip the book list when you only need name/death year'), but nothing about when to choose this tool over alternatives such as shamela_search_authors or how a candidate author_id is discovered in the first place. Usage is implied by the description rather than stated.

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, and the description adds substantial non-obvious behavior: the three renderings returned (body/amiri/majma), the surah_ayat total-count field, that runs continue across surah boundaries with per-verse surah/aya, and that response_format 'none' is preferable when the caller parses structuredContent due to a shared character budget.

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, followed by resolution modes and then examples that each illustrate a distinct invocation pattern. It is longer than strictly necessary but nearly every sentence carries operational information; the examples in particular earn their 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?

With no output schema and five parameters, the description compensates by naming the returned fields (body, amiri, majma, surah_ayat) and explaining the two-channel response_format behavior. An agent has everything needed to call it correctly and interpret the result.

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 cross-parameter constraints (mutual exclusivity of aya_id vs surah+aya) and semantic mapping of each field to a real call, e.g. count=4 returning all of al-Ikhlas. The worked examples meaningfully extend beyond the schema text.

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 ('Fetch Qur'anic verses') and immediately names the two resolution modes (cumulative aya_id 1..6236 OR surah+aya). An agent can distinguish this from shamela_search_quran or shamela_get_tafseer_of_aya 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 tells the agent how to invoke it: 'Pass either aya_id alone OR both surah and aya', with four concrete worked examples covering basmala, mid-surah, full short surah, and a run. It does not explicitly name an alternative tool (e.g. search_quran) or state when not to use it, which keeps it just short of a 5.

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 read-only/idempotent/no-destruction, and the description still adds substantial non-obvious behavior: book_date is usually the author's death year (not composition), downloaded is true only under a dual condition, cover absence does not imply no scan, and same_group entries must not be double-counted as sources. This is exactly the kind of field-level semantics annotations cannot carry.

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 core purpose is front-loaded in the first sentence, and most of the parenthetical caveats (book_date, downloaded, same_group, notes) earn their place given there is no output schema. It is dense and slightly redundant with the schema on cover-token cost, but not padded.

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 no output schema, the description carries the full burden of return-value documentation, and it delivers: it names the returned fields and their pitfalls, explains the notes array as non-fabricable citation fields, and gives id-resolution guidance. Nothing an agent needs to interpret the response 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 the baseline is 3, but the description adds genuine decision context for include_cover (why to suppress it, that absence is not meaningful, that ~1,368 of 8,594 books have one) and reinforces the cover/scan distinction. It does not, however, add anything about response_format beyond what the schema states.

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 ('Fetch full metadata for a book by book_id') and immediately enumerates the fields returned, so an agent knows exactly what this provides versus shamela_get_book_parts, shamela_get_toc, or shamela_get_page. It also disambiguates scope from shamela_list_downloaded_books by stating it 'works on any catalog book whether downloaded or 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?

Explicitly routes id discovery to shamela_resolve('book name') or shamela_list_downloaded_books, and clarifies the downloaded-vs-catalog scope. It stops short of stating when to prefer a sibling like shamela_brief or shamela_get_book_parts, but the context for use is clear.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the edge-case behavior: single-volume books return is_multi_volume:false and an empty parts array, except one retained part label because get_citation prints it. That is meaningful behavioral disclosure 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?

Front-loads the purpose, then the return shape, then the edge case, then the example and the id-lookup pointer. Most sentences earn their place, though the leading Arabic restatement of the title adds no information and the return-field enumeration is dense.

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?

There is no output schema and no rich annotation surface for return values, so the description carries the full burden — and it does, spelling out every returned field plus the single-volume special case. An agent has everything needed to call and interpret this tool.

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 enum on response_format is fully documented in the schema itself, so the description adds little parameter meaning. It provides an example call, which is mildly reinforcing but not new semantics — 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?

States a specific verb+resource: list the volumes/parts of a multi-volume book, then enumerates the exact returned fields (is_multi_volume, total_pages, parts with part name/page_count/first_page_id/last_page_id). This lets an agent distinguish it from siblings like shamela_get_toc and shamela_get_book 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 a clear motivating context ('Useful to know whether a citation needs a part designator') and routes the agent to shamela_list_downloaded_books for obtaining book ids. It does not, however, state when to prefer this over shamela_get_toc or shamela_get_book, so no explicit exclusions are offered.

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, yet the description adds substantial context beyond them: truncation via max_pages, early stop on a character budget, the truncated flag, and continuation via next_start_page_id plus a _display hint. This more than meets the reduced bar annotations impose.

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 definition is front-loaded with a short purpose statement followed by mechanism, limits, and workflow, and every sentence carries information. The bilingual opening is slightly redundant but not wasteful.

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 no output schema, the description carries the burden of describing returns and does so: it explains the truncated flag, next_start_page_id continuation, the _display hint, and how structuredContent/response_format interact. An agent has everything needed to call it correctly and to paginate through long sections.

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 behavioral meaning to max_pages by tying it to the truncation flag and to continuation semantics. It does not go deeper on response_format, which the schema already documents thoroughly.

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 a specific verb+resource ('Fetch every page under a chapter title') and immediately clarifies the resolution mechanism (next-sibling-title boundary in per-book SQLite). This is clearly distinguishable from sibling tools like shamela_get_page (single page) and shamela_get_pages_range (arbitrary range) because it is keyed on a chapter title_id.

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 states the workflow explicitly ('Use shamela_get_toc to find title_ids, then this tool to read the matching section') and supplies a concrete invocation example. It does not, however, name when a caller should prefer a sibling (e.g. get_page or get_pages_range) instead, so it lacks exclusions.

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, idempotent read profile, so the bar is lower; the description still adds real value by naming the backing mechanism (pre-built service/hadeeth.db join), the default downloaded-only filter, the per-result fields, and the response_format character-budget caveat. It does not state ordering or empty-result behavior, but the added context is substantive.

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 lead sentence is front-loaded and the following sentences each carry distinct information (mechanism, default filter, result shape, pairing). Some overlap with the schema's own hadith_key explanation is the only redundancy.

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?

There is no output schema, and the description compensates by enumerating the result fields (book_id, book_name, author_name, page_id, downloaded flag). Combined with the downloaded_only default and the shamela_get_page handoff, an agent has enough to call it correctly; only result ordering and empty-case behavior are unstated.

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 each parameter carries a detailed description, including the response_format capability requirement, so the schema does the heavy lifting. The description restates that hadith_key is a shared numeric identifier but adds no syntax or format detail beyond the schema, 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 gives a specific verb and resource ("list every book that cites" a given hadith key) and explains the underlying join, so the agent knows exactly what comes back. It pairs explicitly with shamela_get_page, but never contrasts itself with the close sibling shamela_search_hadith, which an agent might otherwise reach for.

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?

Usage context is implied rather than stated: "Useful for cross-collection hadith research" sketches a scenario, and the downloaded_only default is disclosed. There is no explicit when-to-use-this-vs-shamela_search_hadith routing, which matters given a sibling with overlapping hadith scope.

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 the safety profile (readOnly, idempotent, closed-world, non-destructive), and the description goes well beyond them: it discloses the never-fabricate rule for missing bibliography fields, the notes[] array of gaps, the digit-system split (Western for bibtex/ris vs Arabic-Indic elsewhere), the stable cite key format, and the response_format/character-budget interaction.

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?

It is dense but front-loaded, leading with the five styles before details. There is noticeable overlap between the description and the already-thorough schema prose (style, text, response_format are all re-explained), plus a redundant Arabic heading, keeping it just short of a 5.

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 no output schema and five parameters, the description must carry the return-value burden itself, and it does: it documents the two-line shamela block, the notes[] gaps, the cite key, and the digit conventions across styles. Nothing an agent needs to call 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%, so the schema already documents all five parameters including the style enum and the text param's two-line behavior. The description restates much of this rather than adding new semantics, so the baseline 3 applies; the examples of parameter combinations add only marginal value.

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 opening line ('Format a citation in five styles') give a specific verb and resource, and the description then enumerates each of the five styles with their distinct output shapes. An agent can tell this is the citation-formatting tool rather than a retrieval sibling like shamela_get_page 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 states exactly when to pick each style: 'shamela' for UI copy-with-citation, 'short' for one-line inline references, 'full' for long-form with death/composition years, and 'bibtex'/'ris' for Zotero/EndNote/Mendeley. It also flags the conditional behavior of the optional text param and supplies two concrete invocation examples, leaving little 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 cover safety (readOnly/idempotent/non-destructive), but the description adds substantial context they do not: chain direction ('ASCENDING: first link is the Companion, last is the collector'), the ten-book indexing ceiling, the two distinct no-data outcomes with literal flag values ('no_marker_on_page' vs 'marked_but_unindexed'), and the changed error behavior for a nonexistent page_id. This is behavioral disclosure well beyond 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?

It is front-loaded with the core purpose and every clause is informative, but it lands as a single dense paragraph rather than scannable segments, which makes it harder to navigate for a five-parameter tool. Slightly over-packed, though not padded.

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?

No output schema exists, so the description carries the burden of explaining the return surface — it names variants, no_isnad_indexed, variants.truncated, and no_isnad_reason with its enumerated values. Combined with the ordering semantics and next-step routing, an agent has everything needed to call and interpret this tool correctly.

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 a 3 would be the floor, but the description adds interpretive meaning for include_variants — counting routes to judge whether a report is ghayr (غريب) or mashhūr (مشهور) — which the schema's own phrasing only gestures at. It does not add format/syntax detail beyond that, so it sits just above baseline.

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+resource (resolve the isnād chain(s) on one page plus the other ṭuruq of the same ḥadīth) and clearly separates itself from nearby siblings like shamela_search_pages (the feeder step) and shamela_get_narrator (the follow-on). The opening line alone lets an agent identify the tool 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?

Gives an explicit workflow: 'run shamela_search_pages, then pass a (book_id, page_id) here,' and names a follow-on ('Pair a narrator id from the chain with shamela_get_narrator'). It also states the scoping limitation (only ten ḥadīth books indexed) so the agent knows when this tool will be useful versus when it will return nothing.

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 carry the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: the critics list is paged with a cursor, total_critics/total_verdicts let you tell a page from the whole file, the network is computed live from the isnād index, and response_format.none requires a capability. This is unusually rich disclosure.

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 content is dense but front-loaded, with the core dossier contents stated before operational details. It is long (a single sprawling paragraph) and includes some illustrative statistics, but nearly every sentence carries deciding information for an agent.

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 no output schema, the description still describes the return shape adequately: the dossier fields, the verdict grouping by critic with citations, and the network fields (narrates_from/narrates_to with counts). Nothing essential for correct invocation appears 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 the baseline is 3. The description still adds meaning: it flags that critics are the only paged section, explains the cursor/total semantics, and clarifies that total_critics lets the caller distinguish a page from the full file — context the schema does not carry.

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+resource ('the full dossier on one narrator') and enumerates what the dossier contains — lineage, death year, ṭabaqa, grades, kunya/nasab/cities, and al-jarḥ wa-l-taʿdīl verdicts. It is clearly distinguishable from shamela_search_narrators, which it explicitly points to for id acquisition.

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 clear operational guidance: get the id from shamela_search_narrators, quote verdicts verbatim rather than synthesizing a grade, and set include_network=false when only the biography is needed. It lacks an explicit 'when not to use this vs. X' routing statement, but the id-sourcing prerequisite is spelled out.

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, and the description adds substantial traits beyond that: the BOOK_NOT_DOWNLOADED failure condition, the ~4000-char body splitting with body_part/body_total_parts/body_has_more, footnotes/comment arriving with part 1, and the keep_html stripping behavior. This is rich, non-redundant behavioral context.

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?

Dense and front-loaded, with the core action stated first and routing/edge cases following. The leading Arabic 'جلب صفحة' duplicates the title rather than adding information, a minor bit of waste in an otherwise efficient paragraph.

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 no output schema, the description carries the full burden of describing the return payload (body, foot, comment, printed_page, prev/next, chapter ancestor chain, category path) plus error and splitting behavior. Nothing essential for correct invocation 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%, so baseline is 3. The description restates keep_html marker handling and body_part splitting that the schema already documents in full, adding only marginal meaning beyond the structured fields.

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?

Specific verb+resource: 'Fetch the full text of one Shamela page (book_id, page_id)'. It also names the exact operation's scope and differentiates from siblings by naming shamela_get_pages_range (batch) and shamela_get_book_section (chapters).

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: 'For batch reads use shamela_get_pages_range; for full chapters use shamela_get_book_section', plus the prerequisite that the book must be downloaded. An agent knows exactly when to pick this tool versus its alternatives.

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 lower, but the description adds real behavioral value: it explains that esnad entries are Shamela's raw markers and 'mean nothing on their own', warns of the format, and discloses the clean has_services:false path for many books. It stops short of covering response shape or budget behavior beyond the schema's own note.

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 key purpose and the raw-marker caveat are front-loaded, and each sentence carries information (return fields, warning, follow-up routes). It is denser than strictly necessary, 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?

With no output schema, the description fully carries the burden of explaining the return shape (has_services, ayat, hadeeth, esnad, esnad_count) plus the interpretation caveat and next-step tools. An agent has everything needed to call it and act on the result.

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 identifies book_id/page_id and reused field meanings but adds no syntax or constraint detail beyond the schema; the response_format parameter's semantics live entirely 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 opening states a specific verb+resource: read per-page service markers (Qur'anic verses, hadith keys, isnād markers) for a (book_id, page_id). It enumerates the return fields and explicitly distinguishes itself from shamela_get_isnad, so an agent can separate it from 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?

It gives explicit when-to-use (pivot from a search hit to what the page cites), names the follow-up alternatives (shamela_get_aya for aya_ids, shamela_get_books_for_hadith for hadith keys, shamela_get_isnad for resolved chains), and warns when-not (non-hadith books return has_services:false). 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?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, yet the description still adds real context: the size-budget truncation rule, the next_start_page_id and `_display` continuation hint, and the has_more flag. It also enumerates the returned page fields, which no structured field supplies.

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 core action and bounded by an example, with each sentence carrying distinct information (defaults, truncation, alternative). Minor waste in the Arabic opener that restates the title rather than adding meaning.

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 no output schema, the description carries the return-shape burden and discharges it by naming the per-page fields, the has_more flag, and the truncation continuation keys. A caller has everything needed to invoke it and to resume a cut-short range.

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 value the schema does not: it restates the 1–20/default-5 constraint in context and points to shamela_list_downloaded_books for obtaining book_id. count and start_page_id semantics are otherwise fully owned by 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?

States a specific verb and resource: fetch N consecutive pages from a downloaded book starting at start_page_id. It explicitly names two siblings it is not — shamela_get_page (loop) and shamela_get_book_section (full chapters) — so an agent can disambiguate 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 ('Faster than calling shamela_get_page in a loop'), a when-not with the alternative named ('For full chapters use shamela_get_book_section instead'), and the prerequisite discovery path via shamela_list_downloaded_books. Nothing about selection 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?

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), and the description adds genuinely new behavioral context: it depends on a pre-built service/tafseer.db join, uses a CURATED index that can omit downloaded tafsirs, may degrade to only al-Tabari on some installs, and surfaces a coverage_note in the result. That is exactly the kind of limitation disclosure an agent needs before trusting the output.

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, then addressing modes, default behavior, and the caveat. Dense but each sentence carries information. Slightly long, though the length is justified by the real coverage caveat rather than 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?

No output schema exists, and the description compensates by enumerating the result fields (book_id, book_name, author_name, page_id, downloaded flag) and the coverage_note. Combined with the pairing instructions and index caveat, an agent has everything needed to call and interpret it.

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. The description nonetheless adds meaning beyond the literal schema text, interpreting downloaded_only=false as 'the full catalog of tafsirs that COULD comment on this verse if downloaded', and clarifying the aya_id vs surah+aya addressing choice.

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 with scope: 'list every tafsir book in the catalog that has a page commenting on it' given a Qur'anic verse. The scope (books, not tafsir text) is clear. However, it never distinguishes itself from the near-identical sibling shamela_list_tafsirs_for_aya or from shamela_get_tafseer_texts, which an agent could easily confuse.

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 states the two mutually exclusive addressing modes (aya_id OR surah+aya), the default filter behavior (downloaded_only=true) and when to flip it, and routes the agent to companions: shamela_get_page(book_id, page_id) to read the text, and shamela_list_downloaded_books(category_id=3)/(category_id=4) for the full picture. The condition under which each alternative applies is spelled out.

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?

Far exceeds the readOnly/idempotent annotations: it explains the strict index-driven behavior, the deliberate absence of a text-search fallback and why (verse misattribution via shared phrases/basmala), explicit statuses for unindexed books, a character budget with continuation hints, and the semantics of verse_located_in_page and the per-source note. This is unusually rich behavioral disclosure.

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 opening line and the dense material is largely load-bearing (statuses, continuation, the verse_located_in_page rationale). It is still a very thick paragraph whose parenthetical explanations run long, 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?

With no output schema, the description carries the full return-value burden and does so thoroughly: it enumerates the per-source attribution fields (book_name, author, death_year, printed_page, page_id), continuation fields (text_part/text_total_parts/text_has_more, next_page_id), status strings, and the budget/continuation protocol. An agent has what it needs to call and continue correctly.

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 a genuine cross-parameter constraint the schema cannot express: pass EITHER aya_id OR surah+aya. It also restates max_sources default and explains book_ids status behavior, giving it an edge over pure schema duplication.

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 — 'Fetch the actual tafsir texts of one aya across multiple sources in a single call' — and adds scope detail (multi-source, index-driven). It routes away from the search tools but never explicitly distinguishes itself from the very close sibling shamela_get_tafseer_of_aya, leaving an ambiguity an agent must resolve on its own.

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 a concrete workflow ('Use shamela_list_tafsirs_for_aya first to see coverage'), the alternative parameterization (aya_id OR surah+aya), and two worked examples. It clearly frames when the index-driven path is required versus a text search, but does not state when to prefer this over the near-identical sibling shamela_get_tafseer_of_aya.

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 the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add operational context — it discloses the return fields (title_id, title_text, page_id, has_children), the two-mode behavior, and depth recursion semantics. It stops short of discussing pagination or large-book limits, so it is strong but not exhaustive.

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 purpose, then modes, then return shape, then examples — a clean information hierarchy. Slightly long because it carries two examples and a mode enumeration, but each sentence earns its place. The duplicated Arabic title line is minor padding.

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?

No output schema exists, so the description carries the return-value burden and does so by enumerating the per-entry fields. Combined with dual-mode explanation, id-lookup guidance, and downstream usage, an agent has everything needed to invoke and interpret this correctly.

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 already 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema cannot express — that parent_id=0 means top level, that depth 1–5 controls tree recursion, and that containing_page_id switches modes entirely. Worked examples with concrete values reinforce this.

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+resource ('Fetch a downloaded book's table of contents') and explicitly distinguishes itself from sibling shamela_get_book_section, which it routes users to for reading the section. An agent can tell what this returns 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?

Gives explicit modes with the conditions that select each: subtree mode (default, via parent_id/depth) vs ancestor-chain mode (via containing_page_id). It also names the alternative tools for finding book ids (shamela_list_downloaded_books, shamela_resolve) and the downstream consumer (shamela_get_book_section).

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 read-only, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: counts are precomputed/cached so include_counts=false yields negligible savings, categories are flat with no transitive expansion, and downloaded_count is machine-local rather than catalog-wide.

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?

Core purpose is front-loaded and the flag guidance is efficiently packed. There is mild redundancy — '41 categories' appears three times and the Arabic heading restates the title — but the tafsir example and cost note each earn their place.

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 no output schema, the description carries the return-value burden and does so, naming category_id, category_name, book_count, and downloaded_count. Combined with annotations covering safety and the schema fully describing all three parameters, an agent has everything needed to call this correctly.

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. The description still adds meaning: it explains the performance tradeoff of include_counts and motivates downloaded_only with a concrete example (tafsir spanning categories 3, 4, and 5), which is information the enum/default schema alone does not convey.

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 opening sentence states a specific verb and resource (list all 41 categories in Shamela's catalog) and adds the flat-structure detail, which distinguishes it from any hierarchy/expansion query. It doesn't name a sibling alternative, but the operation is unambiguous against neighbors like shamela_search_titles or shamela_get_toc.

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?

The description explicitly tells the agent what to do with the output ('Use category_id values with scope.category_ids in search_pages / search_books') and when each flag helps ('downloaded_only=true ... useful because ...'). It stops short of saying when to prefer this tool over sibling catalog/search tools, so it's clear context without exclusions.

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 safe read-only idempotency, and the description adds substantial semantics beyond them: the exact tri-state vocabulary and what each state means, the warning that 'not_indexed_coverage_unknown' is explicitly NOT evidence of missing commentary, the category 3/4 scoping and the in_tafsir_categories:false marker for out-of-category hits. It also discloses the return shape (totals per status plus a curated-index caveat note).

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, then the tri-state definitions, then parameters, navigation escape hatch, and examples. The tri-state enumeration is dense but each clause carries load; the bilingual Arabic title line is mildly redundant with the English title.

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?

No output schema exists, yet the description covers the return contents (per-book tri-state with page_id and printed page, totals per status, index-limitation note) and the idempotent read semantics. An agent has everything needed to call it and interpret the result correctly.

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 the mutual-exclusivity/alternative semantics (aya_id OR surah+aya) that the all-optional, zero-required schema does not itself express, plus concrete value examples. The response_format capability requirement is already fully documented 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?

States a specific verb and resource — a per-aya tafsir coverage report that cross-references the user's downloaded tafsir shelves (categories 3 and 4) against the curated tafseer.db index. It also draws its boundary against siblings by declaring 'Never text-searches', distinguishing it from shamela_get_tafseer_of_aya and shamela_get_tafseer_texts.

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 calling modes ('Pass either aya_id (1..6236) OR surah+aya'), two concrete examples, and routes the agent to shamela_get_toc for books in unknown-status. It does not, however, explicitly say when to prefer this over the tafseer-text siblings, leaving that to inference from 'Never text-searches'.

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?

Although annotations already declare the safety profile, the description adds substantial behavioral context: exact return composition, runtime (6–9 ms), the literal-vs-morphological counting difference with a concrete worked example, and a crucial interpretation caveat about tafsir inflating profiles. That goes well beyond what the annotations provide.

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 is front-loaded and most sentences carry weight, including the comparison, return description, warning, and examples. It is somewhat long for a description and could be trimmed, but the complexity of the tool and nested scope justify the additional length.

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?

There is no output schema, so the description must carry the return-value burden, and it does: it describes the exact page total, distribution dimensions, and speed. Combined with the 100%-covered input schema and annotations covering safety, the description is complete enough 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 coverage is 100%, so the schema already documents all parameters in depth. The description adds operational meaning by explaining that the by_category output should drive scope.category_ids in later searches and by showing scope usage in the examples, but it does not add much syntax beyond 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 names a specific operation (round-zero reconnaissance) and a clear resource (topic coverage across the library), and explicitly distinguishes it from shamela_root_stats by noting the different default mode. An agent can tell what the tool produces and how it differs from the nearest sibling without opening 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?

It states the precise moment to use the tool: before committing to a retrieval plan. It also gives mode-selection guidance, warns against reading distribution as authority, and directs the caller to use the by_category ranking to set scope.category_ids for follow-up searches, which is explicit when-to-use and how-to-continue guidance.

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 safety is covered. The description adds real behavioral context beyond that: it uses pre-built s_book/s_author n-gram indexes for partial matching and returns per-type results with confidence scores. It stops short of describing result ordering or ambiguity handling, but the value added is genuine.

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 body is tight and front-loads the mechanism, the type behavior, and the redirect to sibling tools. The opening Arabic line "تحويل اسم إلى معرِّف" duplicates the title verbatim, which is a small piece of dead weight in an otherwise efficient description.

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 no output schema, the description carries the return-value burden and does state that it returns up to `limit` results per type with confidence scores, which is what an agent needs to consume the result. It could go slightly further on ordering/tie-breaking, but the essentials are present for this read-only resolver.

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 both enums are documented in-schema, so the description's explanation of type='book'/'author'/'any' largely restates it. The examples for query add marginal color but the schema already carries the semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (disambiguate/resolve) and resource (Arabic name fragments to book_ids/author_ids), and the opening line tells the agent exactly what outcome to expect. It distinguishes itself from search_pages/search_books/search_authors, which it explicitly names as the tools it precedes.

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 this BEFORE search_pages / search_books / search_authors when the user mentions a name but doesn't know the exact ID" gives an explicit when-to-use rule plus the alternative tools it replaces in that scenario. 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?

Adds substantial context beyond the readOnly/idempotent/destructive annotations: the cardinality warning that one printed page maps to several ids and all must be read, the specific error taxonomy ('book_not_downloaded', 'no_printed_pagination', 'part_not_found', 'page_not_in_part'), and the meaning of `citable` false. This is exactly the behavior an agent cannot infer from 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?

Front-loaded with the core purpose and the cardinality warning early, then failure modes, then parameter notes and examples. It is dense and nearly every sentence earns its place, though the leading Arabic line restating the title is redundant padding.

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?

There is no output schema, yet the description discharges that burden by naming the return field (`page_ids[]`), its multiplicity semantics, and supporting fields (`parts_matched`, `citable`). Combined with the failure taxonomy, an agent has everything needed to call and interpret the result.

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 schema already documents the four parameters; the description nonetheless adds meaning the schema lacks, notably that different printings paginate differently, that omitted `part` triggers an ambiguity report via `parts_matched`, and worked examples of parameter shapes. It repeats some schema content but the incremental value is real.

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 ('turn a printed citation into the internal page ids') and explicitly frames the transformation problem (a printed page number and a page_id have no arithmetic between them), which distinguishes it from siblings like shamela_get_page and shamela_resolve_work. An agent can tell exactly what this tool produces 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?

Gives clear prerequisites and routing: resolve the title with shamela_resolve_work first, use the printing the citation came from, and omit `part` for single-volume works. It doesn't explicitly state when NOT to use the tool, so it stops short of the top band, but the workflow guidance is concrete.

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/closed-world, and the description adds genuinely non-obvious behavior on top: three prefix/author/edition guarantees, the refusal contract, the `rejected[]` vs ranked-down distinction, the ambiguity:'edition' vs ambiguity:'work' split, and the explicit 'catalogue-only, no index, no library read' scope limit.

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 key contrast against `shamela_resolve`, then the three numbered guarantees, then status semantics, then examples — a sensible order. It is long and repeats some schema content, but for a tool with three subtle matching rules and no output schema, most sentences carry weight.

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 no output schema, the description carries the full burden of describing returns — status values ('exact'/'ambiguous'/'not_found'), the reason code, `match`, `rejected[]`, and `available_editions[]` are all explained. Combined with the refusal contract and scope limits, an agent has everything needed to call and interpret it.

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 each parameter already carries a rich description (title's edition-tail/author-append rules, author-as-FILTER, edition miss behavior, response_format capability). The description largely restates this, adding the concrete example calls but no syntax or constraints the schema lacks — 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?

States a specific verb and resource — resolving a CITED work (title + optional author/edition) to a catalogue entry — and explicitly distinguishes itself from sibling `shamela_resolve`, noting that the other RANKS while this one refuses ambiguity. An agent can pick between the two siblings without opening 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?

Gives an explicit when-to-use rule ('Use this instead of `shamela_resolve` whenever a citation is being verified') plus the reason (ranking always produces a confident winner, so ambiguity yields a wrong answer). When-not semantics are implicit in the refusal behavior but the routing condition is unambiguous.

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 profile, so the bar is lower; yet the description adds substantial context beyond them: it discloses the one-search execution, the 5,000-hit COVERAGE_CAP and that bucket counts become floors, that total_hits is exact, and the ~0.80 morphological accuracy caveat. This is exactly the behavioral context an agent needs to interpret results correctly.

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 core purpose, then tight caveats (cap, accuracy, scope), then two concrete call examples. Every sentence earns its place and nothing is redundant.

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 a nested scope object, no output schema, and a mutation-free read operation, the description covers purpose, cost/cap behavior, accuracy limits, and scoping, including worked examples. Nothing essential for correct invocation or interpretation 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 includes rich enum/mode semantics, so the baseline is 3. The description adds the derived-forms example (صابر/يصبر/اصطبار) and scope slicing, but mostly reiterates what the schema already documents in depth.

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 (profile) and resource (Arabic root distribution across the library), with an explicit enumerated aggregation (by category / Hijri century / book / author). This clearly distinguishes it from search/retrieval siblings like shamela_search_pages or shamela_get_page, which return snippets rather than a distribution.

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?

Implies when to use it (profiling spread of a root, not retrieving snippets) and gives examples plus scope slicing. However it never names an alternative sibling for the closely related task of actually retrieving pages on a topic, leaving some routing inference to the agent.

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 readOnly/idempotent/non-destructive, so the description's job is to add context — which it does by disclosing the pre-built index (no downloads), the absence of scope filtering, the exact return shape, and the chronological sort behavior. It doesn't discuss result-set size limits or how absence/misses surface beyond the naming heuristic, so it falls slightly short of full behavioral coverage.

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, the bilingual heading is compact, and the workflow plus examples are ordered sensibly. It loses a point for redundancy: 'No scope (authors aren't scoped by category/period)' appears both in the body and verbatim inside the options description.

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 5-parameter nested-object search with no output schema, the description covers what is searched, what is returned, the sort semantics, the naming-variant edge case, and the next tool to call — while annotations carry the safety profile. Nothing an agent needs to call it 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%, with limit/offset/options fully documented in the schema, so the baseline is 3. The description reinforces options.sort ('chronological' orders by death year, earliest first) and demonstrates options.wildcards in an example, but adds no parameter detail the schema lacks.

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 ('Search Shamela's ~3,200-author catalog by name or biography text'), names the return fields (author name, Hijri death year, book count), and differentiates itself from the page/book search siblings by noting authors carry no category/period scope. An agent can tell exactly what this tool 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 routes the agent downstream: use the resulting author_id with shamela_get_author for details, or with scope.author_ids in shamela_search_pages/_books. It also gives a concrete recovery heuristic for misses (try kunya, nisba, shuhra variants before concluding absence) and two runnable examples.

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 cover safety (readOnly, idempotent, etc.), but the description adds substantial operational context: a probe failure does not discard the others, `incomplete` flags a thin result, `qualifiers` are present only on status:'ok' and a probe without them has not been checked, `scope_resolution.dropped` exposes invented ids, and deduplication is by (book_id, page_id) with `probe_ids` showing corroboration. This is exactly the kind of behavior beyond annotations that helps an agent interpret results correctly.

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 front-loaded: the first sentence states the purpose and scale, the second explains the merge and deduplication, and the third describes the output metadata. It is dense but each sentence carries unique, useful information. The example at the end is helpful. Slightly over-long for a description, but the length is justified by the tool's complexity and the need to prevent misreading of merged results.

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 (batch of up to 24 probes, nested scope objects, merged output with metadata like `match_quality`, `matched_in_section`, `probe_ids`, `work_group_id`), the description is remarkably complete. It explains execution model, scope requirements, deduplication, timeout handling, and how to interpret caveats. With an output schema present, it appropriately does not repeat field returns but instead teaches how to read them correctly in a merged context.

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. However, the description adds meaning beyond the schema by explaining the required nature of `scope` ('unscoped, Lucene ranks by term frequency across all 8,594 books...') and the practical impact of `limit`, `max_total_passages`, and `deadline_ms` (timeout behavior). It also clarifies `mode` semantics and the concurrent execution model, which are not obvious from field names 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?

Opens with a specific verb and resource: 'Run up to 12 scoped searches in ONE call and get back a single merged, deduplicated result set.' It then distinguishes itself from the sibling single-query search tools by naming the exact use case – assembling evidence for one question from several wordings at once – which is something shamela_search_pages or shamela_search_phrase cannot do.

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 when-to-use ('Built for assembling evidence for one question from several wordings at once') and when-not-to-use ('do not read absence as "no school said this"; for comparative questions leave madhab unset and scope by category instead'). It also warns that a timeout is not a negative finding, which is a critical selection rule.

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 the safe-read profile, yet the description adds substantial behavior: the `matched_in` field distinguishing bibliography from description hits, the pre-built index working before any download, and the full shape of a paginated result (name, author, category, book_date, downloaded flag, snippet). This is real value beyond the structured 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?

Front-loaded with the core purpose and the subject-search insight, and the examples are placed at the end so they do not obstruct the first read. It is dense but nearly every clause adds a distinct fact; the duplicated Arabic title line is minor overhead.

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 no output schema, the description carries the return-value burden and does so: it names the fields each hit reports, the snippet behavior, and the pagination contract. Together with the rich input schema, an agent has everything needed to call it correctly.

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 adds meaning by explaining the subject-vs-title semantics of the query field, the matched_in discriminator, and the explicit rejection of scope.book_ids. It stops short of adding the full wildcard/morphology reasoning that lives 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?

States a specific verb and resource (search the Shamela catalogue of ~8,500 books) and specifies the exact indexed fields (name, author, bibliography, editorial description). It also carves out its niche against siblings by contrasting subject-search versus title-search and noting pre-built index scope.

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 concrete guidance: use the description field to find a book by SUBJECT, and lists which scope filters apply (author_ids, category_ids, period_*, downloaded_only) while explicitly ruling out scope.book_ids. It provides runnable examples but does not explicitly name which sibling to use instead when the target is page content or chapter titles.

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 read-only/idempotent/non-destructive, and the description adds material behavior: the whole expression is one Lucene BooleanQuery over the entire index (exact total_hits, exhaustive MUST_NOT, not a sample), the zero_hit_terms distinction, and the scope-for-speed caveat. This is exactly the extra context annotations cannot carry.

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?

Dense and front-loaded, with the Boolean semantics explained before the example and the scope rationale. The leading Arabic restatement of the title is redundant, but the body sentences all carry 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 search tool with a nested scope object and no output schema, the description covers query semantics, return-count meaning, empty-term handling, and scoping tradeoffs. It stops short of explaining pagination/output shape, but the schema covers has_more/next_offset and response_format.

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 a real constraint not in the schema ('At least one of all_of/any_of is required') and clarifies the scope/filter semantics and intersection behavior. The remaining parameter detail is already well covered by 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?

States a specific verb and resource (Boolean search combining AND/OR/NOT) and explicitly positions it against the 'AND-only regular search' it extends. The named parameters (all_of/any_of/none_of) let an agent distinguish it from shamela_search_exact or shamela_search_pages without opening 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?

Gives a clear condition for use (when you need OR/NOT beyond AND-only search) and a worked example call, plus a note that scope is for speed not correctness. It refers to the alternative only as 'the AND-only regular search' without naming the specific sibling, so routing is slightly less than explicit.

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 safety (readOnlyHint, idempotentHint, destructiveHint=false), and the description layers on genuinely new behavior: the two-stage normalized-candidate then raw-SQLite-verification pipeline, the folding rule, the bounded candidate window with candidate_cap_hit/total_candidates_scanned reporting that broad searches may miss matches, and the OPTION_NOT_SUPPORTED error path. That is rich, non-obvious behavioral detail beyond 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?

The purpose and the routing constraint are front-loaded, and the concrete examples are high-value. It is dense and slightly long with some restated ideas, but nearly every sentence earns its place given the tool's complexity; no 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 a 6-parameter, nested-schema, two-stage tool with no output schema, the description covers mechanism, limits, required flags, error signals, and examples. It references response fields (candidate_cap_hit, structuredContent) but does not fully frame the return shape, which is the only notable gap.

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: the query is NOT auto-diacritized and must be typed with the target form, at least one preserve flag must be true, and scope matters specifically to widen the candidate window. It does not add much syntax for limit/offset, but it meaningfully enriches the two mandatory and the scoping parameters.

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 (exactness-preserving search over pages) and pinpoints the distinguishing feature in the title and first sentence: honor diacritics, hamza/alef forms, and digit systems. It explicitly separates itself from the sibling shamela_search_pages, so an agent can route without opening 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?

Names the alternative (shamela_search_pages), states exactly what that tool cannot do (folds these distinctions, preserve_* returns OPTION_NOT_SUPPORTED), and gives operational conditions: type the query WITH the features to enforce, enable at least one preserve flag, and pass scope for large libraries. This is explicit when/when-not/alternative guidance.

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 the safety profile (readOnly, idempotent, openWorld=false, non-destructive), and the description adds substantial context beyond them: the deliberate shelf scoping and its ranking rationale, the distinction between `books_searched` (text-search scope) and takhrij key books, and what `takhrij[].books` vs `index_entries` count. This tells the agent how to interpret the result rather than just that it is safe.

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 core selector ('by its TEXT, not its numeric key') is front-loaded, and the discussion of scoping and the two counts each earns its place by preventing a common misread. It is nonetheless dense, with install-specific figures ('ten on this install', '1,746 pages') that are illustrative rather than necessary for invocation.

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?

There is no output schema, so the description carries the burden of describing returns — and it does, explaining matched pages with snippets (e.g. the printed takhrij «رواه البخاري ومسلم») plus cross-book takhrij, and the two distinct counts. For a 5-parameter search with no output schema, nothing an agent needs to call or interpret 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 description coverage is 100%, so each of the five parameters is already documented in the schema (including the rationale for search_all_categories and the response_format budget guidance). The description largely reiterates rather than extends parameter meaning, so the baseline 3 applies; the two-number framing adds interpretation context but no new argument syntax.

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 opening line states a precise verb+resource: find a hadith by its TEXT, explicitly 'not its numeric key', which cleanly separates it from key-based siblings like shamela_get_books_for_hadith. It further scopes the operation to the hadith shelves (كتب السنة، شروح الحديث، التخريج، علوم الحديث) and names the return shape (matched pages + takhrij). An agent can select this over the other search_* 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?

It gives an explicit when-to-use branch: default scoping finds who NARRATES, while search_all_categories:true finds who CITES across fiqh/tafsir. It also justifies the default (unscoped ranking buries collections under quoting works with no service keys), effectively stating when-not to widen. The only minor gap is that it does not name a specific sibling as the alternative for key-based lookup, but the behavioral boundary is unambiguous.

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 the read-only/idempotent safety profile, but the description adds substantial behavioral context: the mandatory-constraint rule, ascending chain order (chain[0] is the Companion, last is the collector), what each result contains (book, page, resolved names and death years), and the response_format character-budget tradeoff.

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 scope, then constraints, then examples. Dense and mostly waste-free, though the single long paragraph packs a lot and could be slightly tighter; every clause still carries substantive 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?

With no output schema, the description compensates by describing exactly what results include (book, page, resolved chain with names and death years) and how to verify them. It covers the constraint requirement, ordering, examples, and output-format behavior, leaving no significant gap for calling the tool correctly.

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 adds value beyond the schema by giving worked examples (transmission:[[1580,2779]], contains:[2779] with scope_book_ids) and emphasizing the ordering/adjacency semantics and the capability requirement for response_format='none'.

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 (search isnād chains) with concrete scope: 45,220 chains across ten named ḥadīth books. It clearly differentiates itself from siblings like shamela_search_narrators (source of the ids) and shamela_get_page (for verifying against the printed page).

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 explains when to use each constraint: `contains` for narrators anywhere in the chain, `transmission` for adjacent teacher→student pairs, and notes `transmission` is the strictly stronger claim. It also states 'At least one constraint is required' and routes the agent to shamela_search_narrators for ids and shamela_get_page for verification.

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 the safety profile (readOnlyHint=true, destructiveHint=false, idempotentHint=true), yet the description adds substantial behavior beyond them: the Arabic-folding rules that make «شعبه» find «شعبة», AND-token matching across name/lineage/nisba fields, the ranking rule (dossier size, death-year tiebreak), and an explicit warning that common names must be disambiguated by death year and grade.

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 Arabic title and the core purpose before diving into folding, ranking, and examples. It is dense but nearly every sentence carries distinct information; it runs slightly long, which keeps it off a 5.

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 search tool whose annotations already declare it a safe read, the description covers everything an agent needs: the resource, normalization behavior, result ranking, disambiguation pitfalls, and example invocations. No output schema exists, but the caller consumes narrator_ids, which the description explains, so 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 each parameter is already documented in the schema, so the baseline is 3. The description mostly restates the schema's own folding/AND/ordering text rather than adding new parameter-level meaning, though it does add the paging motivation with a concrete figure («محمد بن» matches 3,620).

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 — find a ḥadīth narrator by name in Shamela's rijāl register — and pins down the scope (18,989 narrators, death years 2-774 AH). It also distinguishes itself from siblings by declaring itself 'the entry point for ʿilm al-rijāl: every other narrator/isnād tool takes the narrator_id this returns.'

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?

Clearly frames when to reach for it (searching for a narrator by name, before calling any narrator/isnād tool that needs a narrator_id) and supplies two concrete call examples. It stops short of explicit when-not guidance, so it falls just under a 5.

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, and the description goes well beyond them: it discloses that morphology yields a SUPERSET with ambiguous roots (with the كتب→تبب/توب/وتب example), that coverage is EXACT only when coverage.sample_is_complete and otherwise a top-scoring sample, that by_book/by_author are truncated to top_n so shares are non-censal, and that edition_groups are one work in several printings.

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?

Long but front-loaded, with the core scope statement first and the routing/exclusions after. Nearly every clause carries operational detail an agent needs; the main cost is some duplication of schema text, which is the only thing keeping it from a 5.

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, a 100%-covered input schema, and full annotations, the description still covers everything an agent needs to call correctly: scope semantics, morphology/wildcard caveats, citation-citability flag, response shape, coverage interpretation, and cross-tool redirects.

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 genuine meaning beyond the schema: it summarizes scope keys, explains the interplay of scope.madhab with school categories, warns that wildcards cannot combine with morphology, and notes preserve_* return OPTION_NOT_SUPPORTED here. It largely restates the schema's own parameter text, which caps it below 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+resource (search) and scope (body/footnotes of locally downloaded Shamela pages), and explicitly distinguishes itself from siblings by naming shamela_search_exact for preserve_* options and shamela_search_titles for chapter-title search. An agent can route to it without opening another 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 concrete when-to-use rules: set scope.madhab for school-specific fiqh but leave it unset for comparative questions, set citable_only whenever quoting a page, and route to shamela_search_exact/shamela_search_titles when the wrong tool would be chosen. Alternatives and exclusions are explicit, 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral context: the two-stage execution (find co-occurring candidate pages, then verify adjacency/proximity in full page text) and the reliability implication of using `scope` on large libraries. It does not discuss rate limits or cost beyond the 'regular search lacks' framing.

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 core distinction, then mode semantics, then the two-stage mechanism, then scoping advice, then return fields and examples — a logical order for a 14-parameter tool. It is appropriately sized, though the bilingual Arabic header duplicates the English title and the return-fields sentence overlaps with the output 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 14 parameters, a 100%-covered schema, an output schema, and full annotations, the description only needs to supply the conceptual layer — mode choice, execution model, scoping advice — and it does exactly that with worked examples. Nothing an agent needs to call it 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%, so baseline is 3, but the description goes further by showing a full invocation example with `query`, `mode`, `distance`, and nested `scope:{category_ids:[17]}`, which clarifies how the parameters compose. It does not add semantics for the many exclusion/shape/pagination params, all of which the schema handles.

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 ('exact-phrase and proximity search') and immediately defines the two modes with concrete Arabic examples («خيار المجلس» for phrase, «بيع» near «قبض» within 5 words). It also distinguishes itself from 'the regular search' by naming what that search lacks, so an agent can tell what this tool adds 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?

It clearly states when to pick phrase vs near ('ideal for fiqh questions where related terms sit close but not adjacent') and recommends scoping for large libraries. However it never names the closest siblings (shamela_search_exact, shamela_search_boolean) or states when NOT to use this tool, 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 declare read-only, idempotent, closed-world safety. The description adds substantial behavioral detail: pre-built zero-config index, returned fields (aya_id, surah, surah_name, aya, body, snippet), stem expansion behavior (ال-stripped and prefixed forms) with reporting fields, and that results come in mushaf order not relevance. This goes well beyond what annotations provide.

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 return fields, then structured into query behavior, stem expansion reporting, and pairing suggestions. Long but dense; minor redundancy with schema on stem expansion and an Arabic title, but every paragraph informs invocation.

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?

No output schema exists, so the description must explain return values; it names aya_id, surah, surah_name, aya, body, snippet, and the stem-expansion report fields. Given nested options and query complexity, this is complete enough 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%; the schema already documents query semantics, limit/offset, options (wildcards), and response_format in detail. The description largely repeats the query-expansion behavior and adds only example counts (e.g., «الملك» 60 vs 28), providing minimal new parameter semantics.

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), resource (the Qur'an), scope (6,236 verses, Hafs from Asim, Egyptian إملائي orthography), and implementation (pre-built aya/ Lucene index). Distinguishes from sibling search tools by naming the Quran-specific index and follow-up tools (shamela_get_aya, shamela_get_tafseer_of_aya).

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?

Provides clear context: used to search Quran verses, pair with shamela_get_aya for single-verse rendering or shamela_get_tafseer_of_aya for tafsir. Does not explicitly state when to choose this over other search siblings (e.g., shamela_search_library, shamela_search_exact), so no exclusions are given.

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 and destructiveHint=false, so safety is settled. The description adds real behavioral value beyond that: it names the Lucene index being queried, notes the shared parameter shape with shamela_search_pages, and specifies the follow-up read workflow. It does not describe result format or pagination behavior, which is the main remaining gap.

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 core purpose, then sibling differentiation, then routing, then two concrete invocation examples. Tight and no filler; the bilingual heading is minor redundancy but the rest is well ordered and 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?

For a search tool with a nested scope object, six parameters and no output schema, the description supplies the two things an agent most needs: how it differs from shamela_search_pages and what to call next. Return-value shape is left to the response_format parameter and structuredContent, which is acceptable.

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 query, scope, options and pagination in depth. The description's examples show the query and scope.book_ids shape in use, which adds slight context, but does not explain parameter semantics beyond what the schema provides. 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?

States a specific verb and resource ('Search Shamela's title/Lucene index for chapter and section titles') and immediately distinguishes the tool from its closest sibling: it matches title text rather than page bodies, unlike shamela_search_pages. An agent can tell this apart from the many other shamela_search_* tools 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 names the sibling it shadows (shamela_search_pages) and clarifies the selecting condition (title text vs page bodies), then routes the agent onward with shamela_get_book_section to read the section found. It lacks a when-NOT-to-use clause, but the sibling differentiation is clear.

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