Tarteel MCP Server

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds context about the interactive display, metadata output, and its role as a prerequisite before phrase_mutashabihat, which is useful 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 two concise sentences, front-loading the core action and then providing explicit usage guidance without any wasted words.

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 full annotations, a 100% schema-described input, an output schema, and clear usage guidance, the description is complete for this read-only, single-ayah metadata 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 coverage is 100%, so the description need not explain parameters. It mentions 'one ayah' imprecisely but adds no new meaning beyond what the schema already provides, so 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?

The description clearly states the tool shows repeated phrase metadata for a single ayah with an interactive display, using a specific verb and resource. It also distinguishes itself from the sibling tool phrase_mutashabihat by noting it provides phrase IDs and counts as a prerequisite.

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 provides use-case triggers ('user asks which phrases in a specific ayah repeat elsewhere') and directs users to phrase_mutashabihat after obtaining IDs/counts, effectively delineating when to use this tool versus its sibling.

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 indicate a read-only, non-destructive operation, and the description adds meaningful behavioral context: it shows matches in an interactive widget, requires Arabic-script queries, and states this should be the FINAL tool call rather than chaining search_ayahs_text. No contradiction with 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 dense and front-loaded, opening with 'DEFAULT tool' before covering use cases, widget behavior, query constraints, and the alternative. Every sentence contributes essential decision-making information, making the length justified.

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 rich schema and annotations, the description covers all necessary context: purpose, widget display, query constraints, and the precise conditions for using the sibling tool. The output schema exists, so not explaining return values is fine.

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 input schema already provides thorough descriptions of both parameters (query semantics, numeric matching, max_results bounds). The description's mention of Arabic script and numeric matching largely duplicates the schema, so it adds little beyond the schema's coverage.

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 clearly states this is the DEFAULT tool for user-facing Quran search, with explicit example queries and the scope ('find ayahs that contain X'). It distinguishes from sibling search_ayahs_text by specifying this is the widget-based final call.

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 explicit guidance: use for ANY user-facing search, and ONLY skip when the user asks for plain text or results feed another tool. It names the alternative tool (search_ayahs_text) and gives a 'when in doubt' rule, making usage conditions 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: this is the FINAL tool call and must not be followed by get_tafsir_text, guessed slugs fail validation, and hard limits of 20 queries/50 items. These details go beyond annotation coverage and help the agent anticipate failures and constraints.

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 longer than average, but it is front-loaded with the core purpose and uses clear topic labels ('SLUG HANDLING', 'Limits') for scannability. Every sentence conveys necessary routing or formatting constraints, so the length is justified; no fluff.

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 description comprehensively covers purpose, alternatives, slug resolution, parameter semantics, formatting, and limits. Since an output schema exists, omitting return-value details is appropriate. No significant gaps for a tool with 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?

Input schema already documents all parameters with 100% coverage, so baseline is 3. Description adds meaning by explaining the 'surah:ayah' format, the requirement to include at least one of languages or tafsir_slugs, and clarifying that languages expect ISO codes while tafsir_slugs require slugs discovered via lookup_tafsirs. This helps the agent compose valid queries.

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?

Description explicitly identifies itself as the 'DEFAULT tool for user-facing tafsir display' and provides concrete example requests ('show me the tafsir of…', 'what does Ibn Kathir say about…'). It clearly distinguishes from sibling get_tafsir_text by specifying exact conditions for when that alternative is used.

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?

Offers explicit when-to-use ('ANY user-facing request to show/see tafsir commentary') and when-not-to-use (plain text or piped output → get_tafsir_text). Also instructs calling lookup_tafsirs first for named tafsirs, giving clear alternatives and precedence.

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, but the description adds critical behavioral context beyond that: it warns that guessed slugs 'routinely fail validation' and explains the naming pattern is inconsistent ('en-sahih-international' vs 'clearquran-with-tafsir'). It also discloses that Arabic is unsupported and that this tool must not be followed by get_translation_text, which are meaningful behavioral traits.

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 longer than typical but each section earns its place: purpose, usage exclusions, slug handling, and format constraints. It is front-loaded with the essential purpose in the first sentence. Slight redundancy exists (e.g., Arabic unsupported is mentioned both in description and schema), but overall the structure is logical and well-organized.

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 one parameter object containing nested fields, several sibling alternatives, and additional prerequisites (like lookup_translations), the description covers all necessary context. It explains when to choose this tool over get_translation_text, how to handle slugs, what constraints apply to languages/translations, and defines the final-call behavior. An output schema exists, so the lack of return-value details 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?

While the schema covers 100% of parameters, the description adds substantial meaning beyond schema descriptions. It clarifies ayah key format with examples, specifies that language codes must be ISO 639-1 and not language names, and provides concrete slug examples while explaining the need to resolve slugs via lookup_translations. This directly addresses common parameter misuse.

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 clearly states the tool's purpose: 'DEFAULT tool for user-facing translation display' and specifies it is for 'ANY user-facing request to show/see translations of a Quran ayah'. It explicitly distinguishes itself from the sibling tool get_translation_text by noting this is the FINAL tool call for display requests, making the purpose unambiguous.

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 explicit when-to-use and when-not-to-use guidance: use for any user-facing translation display, but skip and use get_translation_text when plain text/raw text is requested or when the result will be piped to another tool. It also directs to lookup_translations for slug resolution, naming a specific alternative and the exact conditions under which to use 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=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context: no widget is rendered, it is internal/preparatory, there are hard limits (max 20 queries and 50 items), and it requires at least one of languages or tafsir_slugs. It also clarifies the output is text-only. This goes well beyond the annotations without contradicting them.

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 dense but every sentence serves a critical purpose: defining the tool's role, stating exclusions, listing use cases, warning against duplication, specifying requirements, and giving limits. It is front-loaded with the most important classification ('INTERNAL/preparatory tool') and structured with clear conditions (a/b) and a final preference rule. No wasted words given the complexity of the tool's placement in the workflow.

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 no output schema and a single parameter, the description covers the full context: what it returns (text-only data), when it should be used, how to structure queries, and all constraints (limits, required fields, key format). It also explains its relationship to ayah_tafsir, which is essential for correct selection. There are no obvious gaps for an agent to misuse the 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?

The input schema covers 100% of the single parameter (queries) with field-level descriptions, so the baseline is 3. The description adds extra semantic value by explaining the requirement to include at least one of languages/tafsir_slugs per query, the ayah key format ('surah:ayah'), and aggregate limits (max 20 queries, max 50 items) not fully spelled out in the schema. It also clarifies that an empty array is treated as omitted, which aligns with schema descriptions. This enrichment justifies a score above baseline, though not a 5 because the schema already does most of the work.

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 clearly identifies the tool as an internal/preparatory text-only retrieval tool, with a specific verb ('get tafsir text') and resource (Quran tafsir data). It explicitly distinguishes itself from ayah_tafsir by stating it renders no widget and is not for user-facing answers, making its purpose unambiguous and distinguishable from siblings.

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 gives explicit when-to-use and when-not-to-use guidance: use only for explicit plain-text requests or for chaining into other tools, never as a direct answer, and not after ayah_tafsir to avoid duplicated work. It names the alternative (ayah_tafsir) and even provides a preference rule ('When in doubt, prefer ayah_tafsir'), which is exemplary.

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 state read-only/non-destructive, but the description adds critical behavioral context: no widget is rendered, it is internal/preparatory, Arabic is unsupported, and each query requires at least one selector. These details inform the agent's execution strategy beyond annotation hints.

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?

Though long, the description is front-loaded with the core purpose and uses structured (a)/(b) lists for usage cases. Every sentence adds distinct guidance — exclusions, chaining rules, format constraints — 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?

Given the tool's internal nature, the rich schema, and the presence of annotations, this description is fully sufficient. It covers selection, parameter constraints, limitations, and relationship to sibling tools. No critical behavioral information is missing.

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

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

Schema coverage is 100% and the schema descriptions already cover ISO 639-1 codes, ayah format, exclusion of 'ar', and the languages/translations requirement. The description restates these details without adding new semantic meaning, so 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?

The description clearly identifies this as an internal/preparatory text-only tool that renders no widget, distinguishing it from the user-facing ayah_translation sibling. It states exactly what the tool returns conceptually (translation data) and when it should be used.

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 guidelines are exceptionally explicit: it names ayah_translation as the default alternative, lists two specific use cases (explicit plain-text request or chaining), warns against duplicating work after ayah_translation, and gives concrete parameter rules. This removes ambiguity about tool selection.

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 and destructiveHint=false, so the agent knows it's a safe read operation. The description adds valuable context beyond the annotations: it shows an 'interactive widget', is the final tool call for these requests, and warns against chaining with lookup_reciters. This extra behavioral detail justifies a score above the baseline.

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?

Every sentence earns its place: the first establishes default usage, the second gives example queries, the third clarifies finality, the fourth describes the widget, the fifth gives two precise exceptions, and the final sentence is a decisive fallback. It is longer than average but dense and well-structured, with no fluff.

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 has no parameters, a rich output schema (not shown but stated as present), and clear annotations, the description fully covers when and how to use it. It explains the widget behavior, the finality of the call, and decision rules versus lookup_reciters, leaving no ambiguity for an agent.

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 no parameters (schema coverage 100% with empty properties). Per the rubric, zero parameters warrant a baseline of 4. The description appropriately emphasizes behavior rather than parameter details, which would be redundant.

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 clearly states the tool lists Quran reciters in an interactive widget, using a specific verb ('list') and resource ('reciters'). It explicitly distinguishes itself from the sibling tool lookup_reciters by positioning itself as the default for user-facing queries and by detailing when the alternative should be used.

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?

Extremely explicit guidance: starts with 'DEFAULT tool for user-facing reciter-listing questions' and provides concrete examples ('what reciters are available', 'who can recite for me'). It clearly states when NOT to use it (plain text/raw data, or when piping to another tool) and names the alternative (lookup_reciters).

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?

Beyond the annotations (readOnlyHint, destructiveHint), the description discloses that this tool renders an interactive widget, is meant to be the final tool call for a request, and should not be followed by lookup_tafsirs. This added context about output modality and tool orchestration is valuable and contradicts nothing in 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 longer than a minimal two-sentence blurb but every sentence carries operational value: default role, usage examples, finality rule, widget behavior, and alternative conditions. It is front-loaded with 'DEFAULT tool' and structured as a priority order, making it easy for the agent to parse. Slightly verbose 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?

Given a simple single-parameter schema, existing output schema, and annotations already covering the read-only/destructive nature, the description fully covers the operational context: when to call, what it displays, how it relates to sibling tools, and when to prefer the alternative. No significant gaps remain.

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 schema already describes the 'languages' parameter with an example, so schema coverage is 100%. The description does not add parameter-level detail beyond the schema, which is fine per the baseline rule. The examples in the description ('list English tafsirs') tangentially imply language filtering but do not enhance the schema's meaning.

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 clearly states the tool's purpose: it is the default for user-facing tafsir-listing questions, showing the catalog in an interactive widget. It uses specific verbs ('list', 'browse', 'shows') and explicitly distinguishes itself from the sibling lookup_tafsirs by framing itself as the widget-based display tool.

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 provides explicit when-to-use guidance with concrete query examples ('what tafsirs are supported', 'list English tafsirs'), and when-not-to-use conditions: only use lookup_tafsirs when the user wants plain text/raw data or when piping into ayah_tafsir without showing the list. Ends with 'When in doubt, use this widget', giving a clear decision 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?

Beyond the readOnly/destructive annotations, the description discloses that the tool shows an interactive widget (not plain text), filters out rows without usable slugs, and returns language_name values as display labels. It also emphasizes this is the final tool call for these requests.

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?

Every sentence earns its place. The description is front-loaded with the default-tool classification, then covers usage alternatives, parameter format, output format, and data filtering. No fluff or 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?

The description is fully complete for the tool's complexity: it covers usage context, alternatives, output behavior, and parameter nuances. With an output schema present and good annotations, the description adds all necessary context for effective tool selection and 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 already documents both parameters with descriptions. The description adds the explicit instruction to use ISO 639-1 codes like 'en' rather than names like 'english', reinforcing the language param format 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 clearly states this is the 'DEFAULT tool for user-facing translation-listing questions' with concrete examples ('what English translations are available', 'list French translations'). It explicitly distinguishes itself from lookup_translations and describes the interactive widget output, giving a specific verb+resource+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?

Provides explicit when-to-use ('ANY user-facing query') and when-not-to-use conditions: only use lookup_translations for plain text/raw data or piping into ayah_translation without showing the list. Also instructs to use ISO 639-1 codes and not follow this call with lookup_translations.

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 and destructiveHint=false, covering safety. The description adds behavioral context beyond annotations: 'text-only, no widget rendered' and 'INTERNAL/preparatory tool' clarify that it produces no visible UI and is intended for backend chaining. No contradiction with 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 front-loaded with the most critical information ('INTERNAL/preparatory tool — text-only, no widget rendered') and then provides clear exclusionary and conditional guidance. Every sentence serves a distinct purpose and there is no wasted text, despite the length being justified by the need for sibling disambiguation.

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 empty input schema, rich annotations, and the presence of closely related siblings (list_reciters, play_ayahs), the description is fully complete. It covers use cases, exclusions, alternatives, and chaining behavior, leaving no ambiguity about when and how to invoke 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?

The input schema has zero parameters, so there are no parameter descriptions to provide. The rubric assigns a baseline of 4 for 0-parameter tools; the description reinforces the purpose by mentioning resolving reciter_id, which is the implicit output.

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 'Browse Quran reciters (data only)' and description clearly identify this as a text-only, internal/preparatory data lookup tool, distinct from the user-facing list_reciters. It specifies the verb 'lookup' and the resource 'reciters', and explicitly scopes it as non-widget, internal use.

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 gives explicit when-to-use and when-not-to-use guidance: NEVER use as user-facing answer, use list_reciters instead; use only for plain-text requests or when chaining into play_ayahs. It also provides a tie-breaker rule ('When in doubt, prefer list_reciters'), making tool selection 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 establish readOnlyHint=true and destructiveHint=false, so the read-only safety is covered. The description adds useful behavioral context: it renders no widget, is internal/preparatory, and is intended for chaining. It does not describe the return value shape, but given the simple data-only nature, this is adequate.

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 concise and front-loaded: it opens with the internal/preparatory and text-only nature, then gives explicit do/don't guidance, and closes with a clear fallback rule. Every sentence earns its place; no filler or repetition.

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 one optional parameter, full schema coverage, and read-only annotations, the description is fully complete. It tells exactly when to use it, when not to, how it differs from the sibling list_tafsirs, and how it fits into a chained workflow. No output schema is needed for this simple data lookup.

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 sole parameter 'languages' is fully described in the schema with an example ('en', 'ar'). Since schema description coverage is 100%, the description does not need to add parameter details. Baseline 3 applies because description adds no parameter-specific semantics 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 clearly states the tool is an internal/preparatory, text-only lookup for tafsir collections, and explicitly distinguishes it from list_tafsirs. The verb 'lookup' plus the resource and the 'data only' scope fully clarify what the tool does.

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 guidelines are exceptionally explicit: NEVER use as the user-facing answer, use list_tafsirs by default, and use this only for plain-text requests or when chaining into ayah_tafsir in the same turn. It even says 'When in doubt, prefer list_tafsirs,' leaving no ambiguity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it is text-only, renders no widget, and is intended as a preparatory/internal step. This goes beyond the annotations by clarifying the output mode and its non-interactive nature.

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 dense but organized: it leads with the core nature, follows with an explicit prohibition, then conditions, and ends with a format note. Every sentence adds distinct information. It is longer than strictly necessary but not padded, and the structure aids comprehension.

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 that the tool has no output schema and only two optional params, the description effectively covers the essential context: when to use it, its output mode (text-only, no widget), and the expected purpose (e.g., resolving a slug for ayah_translation). It does not enumerate the exact fields returned, but for an internal preparatory tool this is sufficient.

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 input schema already provides full descriptions for both parameters, including the ISO 639-1 language code filter and the prohibition on names. The description's language guidance ('Use ISO 639-1 codes like 'en', not names') is redundant with the schema. No additional parametric meaning is added, so 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?

The description clearly states it is an 'INTERNAL/preparatory tool — text-only, no widget rendered' and explicitly contrasts it with list_translations. The verb 'browse' combined with 'data only' and the tangible example of chaining to ayah_translation give a concrete sense of purpose.

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 gives explicit when-to-use and when-not-to-use guidance: 'NEVER use as the user-facing answer... use list_translations' and 'Use this ONLY when EITHER (a) ... OR (b) ...'. It also adds a preference rule 'When in doubt, prefer list_translations' and a format requirement for language codes.

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 and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations by mentioning 'interactive display' and 'all matches,' which clarifies the output/display style without contradicting 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 exactly two sentences, front-loaded with the main purpose and then immediately providing usage conditions. Every word earns its place; no filler or 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?

Given the tool's low complexity (3 params, no required) and the presence of an output schema, the description sufficiently covers the core use cases and constraints. It explains how to invoke via phrase_text or phrase_id and notes the source of a phrase_id, making it complete for an agent to decide and call 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 descriptions already cover all three parameters at 100% coverage, including the mutually exclusive relationship between phrase_id and phrase_text. The description adds practical semantics by explaining when to use each parameter (e.g., phrase_id from ayah_mutashabihat), which enriches the schema's baseline information.

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 and resource: 'Show phrase mutashabihat occurrences with an interactive display.' This clearly distinguishes the tool from siblings like ayah_mutashabihat (which deals with ayahs) and search_ayahs_text (text search), by focusing specifically on phrase-level mutashabihat occurrences.

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 states 'Use this when:' followed by two concrete scenarios: user provides phrase text asking where it appears, or user has a phrase_id (e.g., from ayah_mutashabihat) wanting all matches. This clearly guides when to invoke this tool over alternatives, even though no exclusions are 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 state readOnlyHint=true and destructiveHint=false; description adds that this tool presents an interactive player widget, has a default reciter ID behavior, and contains a caution about guessed reciter IDs pointing to the wrong reciter. Also discloses the 200-total-ayah limit. No contradiction.

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?

Description is front-loaded with purpose, then uses short labeled sections (RECITER HANDLING, Limits). Every sentence carries necessary operational information, no filler. Well-structured for an AI to parse.

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 nested query objects, the description covers use case, reciter resolution, ayah key format, defaults, and limits. Output schema exists, so return values need not be described. The description is sufficient to invoke the tool correctly with no ambiguity.

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 already documents each parameter thoroughly (100% coverage). Description adds value by explaining the reciter lookup procedure, the default_reciter_id behavior, and the aggregate limit of 200 ayahs per request, which is not present 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?

Clear verb+resource: 'Play Quranic ayah audio'. It specifies the interactive player widget and explicitly states when to use ('when the user asks to play/listen to ayahs'), distinguishing it from sibling search/translation tools.

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 when to use, provides concrete conditional logic for reciter_id (always call lookup_reciters first, omit if not specified), and documents request limits. This goes beyond simple context to include a mandatory cross-tool prerequisite.

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 and destructiveHint=false, so the safety profile is known. The description adds the behavioral trait of an 'interactive timetable display' and the ability to handle specific prayer methods, which goes beyond annotations. No contradictions.

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 two sentences, front-loaded with the core purpose and followed by a concise 'Use this when' clause. Every sentence earns its place with no waste.

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 moderate complexity, the description covers purpose and usage triggers while the schema and annotations handle parameters and safety. An output schema exists, so return format details are not needed. The description is complete for this lookup 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% for all three parameters, so the schema fully documents city, method, and country. The description mentions method examples (ISNA, MWL) that are already in the schema, adding no new semantic meaning.

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 clearly states the tool 'Get Islamic prayer times for a city with an interactive timetable display', with a specific verb, resource, and scope. It is easily distinguished from sibling tools, which focus on ayah search/translation/tafsir, not prayer times.

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 usage conditions are provided: 'Use this when: the user asks for salah times in a location; the user asks to calculate times with a specific prayer method'. This gives clear, actionable guidance on when to invoke the tool, even though no alternatives are named.

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=true and destructiveHint=false, so the description doesn't need to re-explain safety. It adds meaningful behavioral context beyond annotations: the tool renders no widget, is internal/preparatory, ignores diacritics and punctuation, and treats numeric-only queries as ordinal matches. These are non-obvious behaviors that help the agent understand what this tool actually does at runtime.

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 front-loaded with the most critical information ('INTERNAL/preparatory tool — text-only, no widget rendered') and every sentence serves a purpose: usage restrictions, chaining context, anti-pattern warning, and query constraints. It is dense but not bloated, and the structure guides the agent through decision-making efficiently.

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 simplicity (2 parameters, full schema coverage, no output schema, annotations present), the description covers all necessary context: when to use, when not to use, specific query behavior, and what to do with results (chain). It leaves no critical gaps for an agent to invoke the tool incorrectly, making it complete for its 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 100% because both query and max_results have descriptive text in the schema. The description's main body adds no new parameter semantics; it only echoes the Arabic-script and numeric-ordinal behavior already present in the query parameter description. Thus, the description adds no value beyond the schema, warranting the baseline score.

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 clearly specifies the tool's purpose: 'search the Quran by Arabic text' and is explicitly tagged as 'INTERNAL/preparatory tool — text-only, no widget rendered.' It distinguishes itself from the sibling tool ayah_search by positioning itself as the data-only variant for raw results or chaining, making its purpose unambiguous from the start.

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 explicit when-to-use guidance: ONLY when the user asks for plain text/no widget, or when chaining into other tools (play_ayahs, ayah_tafsir, ayah_translation) in the same turn. It also gives a clear when-not-to-use: never as the user-facing answer, and 'Do not follow ayah_search with this tool — that is duplicated work.' It names the preferred alternative ayah_search and even says 'When in doubt, prefer ayah_search.'

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