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

Annotations already state readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description contributes almost nothing beyond that: it does not explain pagination via limit/offset, what the candidate set contains, or that results depend on the reading_context, and the existing output schema is not referenced. 'Candidates' is the only behavioral signal, and it is unexplained.

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 a single noun phrase with no waste, but brevity here reflects under-specification rather than economy: for a six-parameter tool with a nested ReadingContext it gives the agent nothing to act on. A verb-first sentence stating what is returned would cost little and add much.

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

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

For a tool with a nested object schema, six parameters, and a paginated result (limit/offset), a one-line fragment is far short of what an agent needs to invoke it correctly, despite the output schema covering return shape. Neither the reading mode semantics nor the filtering parameters are addressed anywhere.

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 0%, so the description must carry parameter meaning, yet it only implicitly corresponds to the page parameter ('a page of the verified 559-page Qaloun layout'). reading_context with its wasl/waqf modes, stop_after_word, families, rule_ids, limit and offset are all left undocumented in both schema and description.

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 fragment does identify the resource (ayat that begin on a page of the 559-page Qaloun layout) and hints at a candidate-generation result, but it never states a verb and never explains what 'candidates' means or how the output differs from siblings like analyze_qaloun_tajwid or get_qaloun_passage. An agent can guess the domain but not the operation.

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 no when-to-use guidance at all: no conditions, no prerequisites, no mention of the alternative siblings (get_qaloun_passage, analyze_qaloun_tajwid, summarize_tajwid) that an agent would have to choose between. Usage is only implied by the tool name.

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 closed-world, so safety is covered. The description adds real context beyond that: results are 'candidate' occurrences rather than final verdicts, they are paged, and each carries its citations. It does not explain what paging means in practice or what the 1-100 ayat bound implies for behavior.

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?

One compact sentence, front-loaded with the returned artifact and finished with the scope and pagination qualifiers. No filler and nothing buried.

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?

This is a 7-parameter tool with nested selection and reading-context objects and no schema documentation at all. The description covers the output shape and the ayat cap but leaves the input surface, including the wasl/waqf distinction that drives Tajwid analysis, entirely to the agent's guesswork. An output schema exists, so return-value detail is rightly omitted, but the input gaps are too large for a tool of this complexity.

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 0% across 7 parameters, so the description carries the full burden and largely fails. 'Paged' gestures at limit/offset and '1 to 100 ayat' at the selection size, but families, rule_ids, include_candidates, and the entire reading_context (wasl vs waqf mode, preceding/following references, stop_after_word) go unexplained.

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 the resource precisely: candidate Tajwid occurrences for a Qaloun ayat range, paged, each carrying citations. That is specific enough to distinguish it from get_tajwid_rule or list_tajwid_rules, though it never contrasts itself with summarize_tajwid, which sounds like the closest sibling.

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 no when-to-use guidance and no named alternative. The word 'candidate' hints that results are unconfirmed and that summarize_tajwid might be the aggregation path, but the agent must infer that; nothing states prerequisites or 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 readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds the meaningful constraint of a 1-29 letter batch and the source provenance (Book A pp.40-45), but says nothing about what happens with letters outside the range or unsupported characters.

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?

A single compact phrase with the scope constraint and source citation front-loaded; nothing is wasted. It is a fragment rather than a sentence, which is efficient but reads slightly telegraphic.

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 explanation, and the tool is a simple one-parameter read. Still, for a mutation-free lookup with 0% schema coverage on its only parameter, the input format for `letters` should have been stated.

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 0%, so the description must carry the load for the single `letters` parameter. It clarifies that the input is Arabic letters and caps the count at 29, but a string array with maxLength 512 leaves unresolved whether entries are single Arabic characters, transliterations, or letter names.

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 resource and specifies exactly what is returned: place of articulation and characteristics for Arabic letters, scoped to Book A pp.40-45. The verb is only implicit (the tool name supplies 'get'), but the content is distinct from siblings like get_tajwid_rule or get_qaloun_passage.

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 no when-to-use guidance and no mention of alternatives such as get_tajwid_rule or analyze_qaloun_tajwid, so an agent must infer selection from the content noun phrase alone. The 1-29 letter bound hints at batch usage but is not framed as 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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety and idempotency are covered. The description adds meaningful behavioral context by stating that content is 'unchanged' and comes from 'checksum-pinned source files', which discloses provenance and integrity guarantees beyond the annotations.

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

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

The description is a single front-loaded sentence with no filler or redundant restatement. Every phrase contributes either the verb, the resource, or the integrity scope.

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?

The tool requires a nested reference object with corpus identifiers, numbering system, riwaya, tariq, surah, ayah, and end_ayah, but the description does not explain how to supply or interpret these fields. The output schema reduces the need to describe return values and annotations cover safety, but the input guidance remains inadequate for this complexity.

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 0%, so the description must compensate for undocumented parameters. It only vaguely implies ayat and page spans and gives no meaning for the nested selection fields such as start, end_ayah, corpus_id, corpus_version, numbering_system, riwaya, tariq, surah, or ayah.

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 uses a specific verb, 'Read', and names a specific resource, 'Qaloun ayat and verified page spans', plus its source, 'checksum-pinned source files'. It does not explicitly distinguish this tool from siblings such as get_source_page or analyze_qaloun_tajwid, but the purpose itself is clear.

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 provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives like get_source_page, search_source_pages, or analyze_qaloun_tajwid, so an agent must infer when this passage-specific reader is appropriate.

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, non-destructive behavior, so the safety profile is covered. The description still adds real value beyond that: the 1-to-5 page cap (which the schema does not enforce) and the fact that page numbers are printed-edition numbers rather than file or scan indices. It stops short of saying what happens if the range exceeds 5 or the pages are missing from the local copy.

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?

One sentence, front-loaded with the verb and resource, with the two most decision-relevant constraints (page cap, printed numbering) in parentheses. Nothing is redundant or 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?

An output schema exists, so return values need no explanation, and annotations cover the safety semantics. However, for a tool with three required parameters at 0% schema coverage, the description leaves the origin and format of edition_id unspecified and does not say how out-of-range or unavailable pages are handled.

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 0%, so the description must carry the load, and it only partially does: it clarifies the page_start/page_end range semantics via "1 to 5 pages" and "printed page numbers." It says nothing about edition_id — where an agent obtains a valid value or what editions exist — which is the parameter most likely to cause a failed call.

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 pairs a specific verb ("Read") with a specific resource ("pages of a locally placed source book") and adds scoping detail (1 to 5 pages, printed page numbers). That is enough to separate it from retrieval-style siblings like search_source_pages or get_qaloun_passage, although no sibling is named explicitly.

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 phrase "locally placed source book" plus "printed page numbers" implies the context in which this is the right tool (as opposed to a search or app-page tool), but the description never states when to choose it over search_source_pages or analyze_app_page, and gives no preconditions such as needing a resolved edition id.

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 closed-world, so the safety profile is covered. The description adds two genuinely useful facts beyond them: results carry page-level citations and are flagged "(unreviewed)", signalling data provenance/quality. It stays silent on what happens when rule_id+version match nothing and on the size of a returned record.

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?

A single tightly written sentence with the resource first and the qualifier "(unreviewed)" placed where it is immediately visible. Nothing is padded or repeated 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?

An output schema exists, so return-value explanation is rightly omitted, and annotations carry the safety semantics. The remaining gap is the complete absence of information on how to supply the two required keys, which for a two-required-param lookup is a meaningful shortfall.

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 0% and both parameters are required, yet the description says nothing about rule_id or version — no format, no hint that version identifies a Tajwid edition, no pointer to a tool that yields valid values. With low coverage the description should compensate, and it does not.

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+resource ("Read a local Tajwid rule record") plus what is attached (page-level citations), which separates it from list_tajwid_rules (collection) and analyze_qaloun_tajwid (analysis). The word "local" hints at a distinction from a remote/source counterpart, but no sibling is named explicitly.

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 no statement of when to call this rather than list_tajwid_rules, get_source_page, or analyze_qaloun_tajwid, and no prerequisites or exclusions. The only steer is implicit in the word "local" and the singular "record", leaving the agent to infer it from the name alone.

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 carry the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's marginal contribution is the disclosure that it touches no source or private data — a real guarantee an agent can rely on when deciding it is safe to probe. It does not add anything about latency, caching, or what 'configuration' surfaces, so it is useful but not rich.

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?

One short sentence, front-loaded with the action and resource, with the security scope riding immediately behind it. No filler, no restatement of the name beyond what is needed.

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 zero parameters, rich annotations and an output schema defining return values, the description only needed to establish purpose and safety, which it does. The one residual gap is that 'configuration' is left vague about which settings are reported, but the output schema covers that.

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?

The tool takes zero parameters, which is the baseline-4 case: there is nothing for the description to disambiguate and no schema gap to compensate for.

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?

A concrete verb-plus-object ('Report process readiness and configuration') tells the agent exactly what is returned, and the scope clause 'without accessing source or private data' separates it from the content-fetching siblings like get_source_page or search_source_pages. It stops short of naming any sibling explicitly, so differentiation is inferred rather than stated.

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?

Usable context is only implied: an agent reads 'process readiness' as a pre-flight check before calling the Quran/tajwid content tools. There is no explicit when-to-use rule, no stated preconditions (e.g. call before other tools), and no mention of alternatives or when not to call it.

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 openWorldHint=false, so the safety profile is covered. Beyond that the description adds nothing: no mention of the max_combinations cap, how wasl vs waqf modes affect results, or what 'the book's tables' means as a data source.

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 a single short sentence, but brevity here is under-specification rather than economy. The trailing parenthetical '(the book's tables)' consumes space without clarifying anything actionable.

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?

The tool takes two required nested objects with enums and constraints and exposes a complex recitation-domain result, yet the description covers none of that. An output schema exists, so return values need not be explained, but the invocation contract is wholly 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 0% and the description explains none of the three parameters. The most consequential inputs — reading_context.mode (wasl/waqf), basis, following/preceding QalounReference, stop_after_word, and max_combinations — are entirely undocumented, leaving an agent unable to construct a valid call from the description.

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 indicates the resource — combinations of madd readings permitted together within each ayah — but supplies no verb and leans on domain jargon ('madds', 'the book's tables') that an agent without tajwid background cannot resolve. It does not differentiate this from siblings such as analyze_qaloun_tajwid or get_tajwid_rule.

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 no when-to-use guidance, no statement of prerequisites, and no named alternative among the eleven sibling tools. The agent is left to guess whether this complements or duplicates analyze_qaloun_tajwid.

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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely new fact beyond that — the result includes detector availability per rule, i.e. coverage metadata rather than rule definitions. It does not say anything about ordering, filtering behavior, or what happens when a family has no rules, but with rich annotations this is acceptable.

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?

One short sentence, front-loaded with the action and scoped by a second clause that carries real information. No filler, though the phrasing 'available local rules' is slightly compressed at the cost of clarity.

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 not be described, and the annotations cover safety. What is missing for a simple enumeration tool is the meaning of the optional family filter and any hint about how this listing relates to the analysis tools in the sibling set.

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?

There is a single optional parameter, 'family', with 0% schema description coverage, and the description never mentions it. An agent reading only the description would not know it can scope the listing by family, nor what values 'family' accepts; the description should compensate for the missing schema documentation and does not.

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 (list) and resource (local tajwid rules) plus an unusual detail — it reports whether a detector exists for each rule — which an agent can use to distinguish it from get_tajwid_rule. It stops short of explicitly naming that sibling, and 'local rules' is slightly ambiguous (local to what?).

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 no guidance on when to call this versus get_tajwid_rule or analyze_qaloun_tajwid; the agent must infer that this is a discovery/enumeration step. Nothing indicates whether it is meant as a first call to see coverage before running an analysis.

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, and non-destructive, so the safety profile is covered. The description adds real value by noting the mapper is pinned/reusable and that some ranges are flagged review-required and unsafe for retrieval, but it does not explain what 'pinned' or 'review-required' concretely mean in 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?

It is a single short sentence, but brevity here comes from under-specification rather than economy; the front-loaded clause 'Reuse the pinned mapper' is cryptic and consumes the position where the actual purpose should sit.

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 not be described, but for a four-parameter nested mapping tool with an opaque purpose the description leaves the core contract unstated. Too little context for an agent to invoke it confidently.

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?

All four required parameters (selection, target_corpus_id, target_corpus_version, target_numbering_system) have 0% schema description coverage, and the description never mentions any of them. It does not clarify that the selection is a source passage and the target_* fields describe the destination corpus, so the crucial source-to-target semantics must be guessed.

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 sentence names a 'pinned mapper' and 'source retrieval' but never states the actual operation: resolving a Qaloun passage selection into a target corpus/numbering system. An agent cannot infer from this that it converts references across corpora, nor how it differs from get_qaloun_passage or get_source_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?

'review-required ranges are unsafe for source retrieval' hints at a when-not condition, but it is vague and names no alternative tool or fallback behavior. There is no positive guidance on when to call this instead of the sibling retrieval tools.

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 the safety profile: read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context beyond that by specifying the search is literal rather than semantic/fuzzy, is limited to locally placed pages, and returns page hits rather than full page content.

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 a single front-loaded sentence with no filler. It is appropriately compact, though the extreme brevity leaves important parameter details unstated elsewhere in the definition.

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?

The presence of annotations and an output schema reduces what the description must cover. Still, for a tool with three parameters and zero schema description coverage, the description is incomplete because edition_ids and limit receive no explanation, and sibling alternatives are not addressed.

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 0%, so the description carries the burden of explaining parameters. It gives some meaning to query by calling it a literal Arabic search, but it does not explain edition_ids, its required status, or the limit parameter and its default.

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 uses a specific verb and resource: "search" over "source pages." It also narrows the operation to "literal Arabic" search and says it returns "page hits only," which distinguishes it from a content-retrieval sibling like get_source_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?

The phrasing implies when this tool is appropriate: literal Arabic lookup across locally placed source pages. However, it does not explicitly compare against get_source_page or other siblings, nor does it state when not to use this search.

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, non-destructive, and closed-world, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact — that results are paged and broken down per-ayah as well as per-rule — but says nothing about ordering, total counts, or what happens at range boundaries.

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?

One short sentence, front-loaded with the output type and scope, with no wasted words. Brevity here shades into under-specification rather than verbosity, but the structure itself is clean.

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 not be described, but the tool has 8 parameters including a required nested reading_context and zero schema documentation. A single clause cannot make an agent confident about how to set reading_context or the families/rule_ids filters before calling.

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 0% schema description coverage across 8 parameters, the description carries the full explanatory burden and mostly fails. It only implies surah, ayah range, and paging; the required reading_context object (mode/basis/preceding/following), plus families and rule_ids filters, are never mentioned or explained anywhere in prose.

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 output ('per-rule candidate counts') and scope ('a surah or an ayah range'), which is more than a tautology. However, 'candidate counts' is unexplained jargon and the description never distinguishes this tool from the sibling analyze_qaloun_tajwid, so an agent cannot confidently pick between them without opening both 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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives. It does not tell the agent whether this is a light summary versus the heavier analysis performed by analyze_qaloun_tajwid, nor what preconditions (e.g., a known corpus/reading context) must hold.

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