Tarteel MCP Server

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering safety and scope. The description adds valuable context about the 'interactive display' behavior and the tool's role in a workflow (preparing for phrase_mutashabihat), which goes beyond what annotations provide. No contradictions with annotations exist.

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 perfectly concise and well-structured. It uses two sentences: the first states the purpose, and the second provides clear usage guidelines. Every word earns its place with no redundancy or unnecessary 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?

Given the tool's moderate complexity, rich annotations (readOnlyHint, destructiveHint, openWorldHint), 100% schema coverage, and existence of an output schema, the description is complete. It explains the tool's purpose, usage context, and workflow role without needing to detail parameters or return values, which are covered elsewhere.

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 all parameters well-documented in the schema. The description doesn't add any additional parameter semantics beyond what's in the schema, but it doesn't need to since the schema is comprehensive. Baseline 3 is appropriate when schema coverage is complete.

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: 'Show repeated phrase metadata for one ayah with an interactive display.' It specifies the exact resource (ayah) and action (show repeated phrase metadata), and distinguishes it from sibling tools like phrase_mutashabihat by focusing on a single ayah rather than phrase-level analysis.

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 usage guidelines: 'Use this when: the user asks which phrases in a specific ayah repeat elsewhere; the user needs phrase IDs and counts before calling phrase_mutashabihat.' This gives clear scenarios for when to use this tool versus alternatives, including a specific sibling tool reference.

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. Description adds valuable behavioral context: shows matches in an interactive widget, query is Arabic script only with diacritics ignored, numeric-only query matches by ordinal number, and it 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?

Front-loaded with purpose and usage guidelines; every sentence adds value. Slightly verbose but still efficient for the amount of information conveyed.

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 (search with widget, multiple siblings, 2 params, output schema present), the description covers all key aspects: usage scenarios, query behavior, output format (widget), exclusions, and finality of the call.

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% with descriptions for both parameters. Description adds meaning beyond schema: explains Arabic script requirement, diacritic handling, numeric query behavior (ordinal matching), and the BM25 relevance ranking for query parameter.

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

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

Description clearly states it's the default tool for user-facing Quran search, provides examples ('find ayahs that contain X'), and explicitly distinguishes from sibling search_ayahs_text by stating when each 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?

Explicitly states when to use (ANY user-facing search) and when not to use (when plain text/raw results are requested or results will be fed into another tool). Names the alternative (search_ayahs_text) and provides clear 'when in doubt' 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?

Beyond annotations (readOnlyHint=true, destructiveHint=false), the description adds critical behavioral details: limits (max 20 queries, 50 items), slug resolution requirement, ayah key format, and the constraint that each query must include languages or tafsir_slugs. No contradictions 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?

Well-structured and front-loaded. First sentence states purpose; subsequent sentences provide usage rules, slug handling, and limits. Every sentence adds value with no repetition or 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 complexity of tafsir selection, the description covers all essential aspects: purpose, usage guidelines, slug resolution, parameter constraints, limits. Output schema exists, so return values are covered elsewhere. Complete for agent decision-making.

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. However, the description adds value beyond the schema by explaining when to omit fields (e.g., 'languages' or 'tafsir_slugs' can be omitted but at least one required), format examples, and slug handling logic. Adds a necessary constraint not in the schema.

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

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

The description clearly states it is for user-facing tafsir display, with specific verb-resource combinations like 'show/see tafsir commentary'. It distinguishes itself from sibling 'get_tafsir_text' by specifying when to use each 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?

Provides explicit guidance: use for ANY user-facing request, skip only for plain text or piping. Also includes slug handling instructions: call lookup_tafsirs first, do not guess slugs. Explicit alternatives 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?

Beyond readOnlyHint and destructiveHint annotations, the description discloses that Arabic is unsupported, that guessed slugs fail validation, and that this widget is for display only. Adds significant 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?

Description is dense with valuable information but somewhat long. However, it is well-structured with clear sections (DEFAULT, SLUG HANDLING) and front-loaded with the most critical use case.

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, schema richness, and sibling tools, the description is thorough. It covers when to use, formatting details, common pitfalls, and exclusions, making it complete for safe 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?

Despite 100% schema coverage, the description adds crucial meaning: explains slug format (with examples), ISO 639-1 codes, ayah key format, and the requirement for at least one of languages/translations. Greatly enhances param understanding.

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?

Clearly states it is the DEFAULT tool for user-facing translation display, distinguishes from get_translation_text, and specifies the resource (Quran translations) and action (show/display).

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 vs get_translation_text, rules for slug handling (use lookup_translations), language code format, and ayah key format. Provides clear decision criteria and 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=true and destructiveHint=false, so safety is clear. The description adds behavioral context: 'text-only, no widget rendered', 'INTERNAL/preparatory tool', and that it returns data suitable for chaining. No contradictions. Adds value beyond 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 moderately long but well-structured, front-loading the critical warning. Each sentence serves a purpose, though some minor redundancy could be reduced. Overall efficient for the amount of guidance provided.

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 no output schema and nested parameters, the description covers usage constraints, input format, limits, alternatives, and chaining behavior. It is complete enough for an agent to correctly select and invoke the tool without 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 has 100% description coverage, so baseline is 3. The description adds context beyond the schema: it explains the 'surah:ayah' format with example '2:255', specifies limits (max 20 queries, max 50 items), and clarifies that each query must include at least one of languages or tafsir_slugs. This adds meaningful guidance.

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 text-only tool, distinguishes from ayah_tafsir, and specifies it should not be used as a user-facing answer. The verb 'get' combined with 'text' and the explicit exclusion of widget rendering makes 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 (plain text request or chaining) and when-not-to-use (user-facing tafsir requests, duplicating ayah_tafsir). It names the alternative tool (ayah_tafsir) and warns against redundant chaining. Excellent 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 indicate readOnlyHint=true (safe read). Description adds key context: no widget rendered, internal/preparatory nature, and input format rules (surah:ayah, ISO codes). Does not contradict annotations and provides behavioral insight beyond 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 key purpose and usage rules. Every sentence adds value, but the text is somewhat lengthy. Could be slightly more concise while retaining all 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?

Given the complex input schema (nested array with 4 subfields), no output schema, and 17 sibling tools, the description is highly complete. It covers the tool's role, input constraints, ordering relative to siblings, and when to avoid. No essential context 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% with descriptions for all parameters. Description adds meaning: ayah key format example '2:255', ISO 639-1 requirement, prohibition of Arabic, and that each query must include at least one of languages or translations. This clarifies usage beyond 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 retrieves translation text as plain text, no widget. It distinguishes from the sibling ayah_translation by specifying it's internal/preparatory and not user-facing. The verb 'get' and resource 'translation text' are specific and 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?

Explicitly states when to use: user asks for plain text or chaining without showing. Explicitly states when not to use: never as user-facing answer, prefer ayah_translation for default, avoid Arabic. Names alternative ayah_translation and warns against duplicated work.

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, destructiveHint, openWorldHint. Description adds that this tool shows an interactive widget and is the FINAL call for these requests (no follow-up with lookup_reciters). This adds behavioral insight beyond 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 somewhat verbose but every sentence adds value. It front-loads the primary purpose and usage constraints. Could potentially be tightened slightly, but still effective.

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 zero parameters, presence of annotations, and an output schema (not detailed but known to exist), the description fully covers what the tool does and when to use it vs. alternatives. No 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?

No parameters exist, so the baseline is 4. The description does not need to explain parameters; it instead focuses on behavioral context. With 100% schema coverage (no parameters), it adds sufficient 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 it is the DEFAULT tool for user-facing reciter-listing questions, using specific verb 'Browse' and resource 'Quran reciters'. It distinguishes itself from the sibling tool 'lookup_reciters' by explaining that this tool shows an interactive widget.

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 when to use ('what reciters are available', 'who can recite for me') and when NOT to use (when user wants plain text or pipe to another tool). Names the alternative tool 'lookup_reciters' and gives a clear rule: 'When in doubt, use this widget.'

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 minimal extra beyond stating it shows an interactive widget, but does not elaborate on behavior like return format, pagination, or performance. 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 a single, front-loaded paragraph. Every sentence provides essential guidance (default nature, usage rules, alternative distinction). No 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?

For a simple listing tool with one optional parameter, annotations covering safety, and an output schema present, the description covers purpose, usage, and alternatives completely. No gaps.

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 provides 100% coverage for the single optional parameter, including a description and example. The tool description adds no additional meaning beyond what is already in the schema.

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

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

The description clearly states the tool is for browsing tafsir collections for user-facing queries, with a specific verb ('browse', 'list') and distinguishes it from the sibling tool lookup_tafsirs.

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 specifies when to use this tool (user-facing queries, final call) and when to use the alternative lookup_tafsirs (plain text or piping), with 'when in doubt, use this widget'.

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?

Goes beyond annotations: discloses interactive widget, filters rows without slugs, notes language_name as display labels. 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?

Front-loaded with purpose and usage, but somewhat lengthy. Every sentence adds value; minor trimming possible but justified by richness.

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 sibling tools and annotations, description fully covers selection criteria and behavior. Output schema exists, so return details not needed.

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%, baseline 3. Description adds value by emphasizing ISO 639-1 codes for the language parameter, but locale parameter is already well-described in 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?

Clearly states it is the default tool for user-facing translation-listing questions, with examples. Distinct from lookup_translations and explicitly marks it as the 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?

Provides explicit when-to-use (user-facing queries), when-not-to-use (plain text or piped), and alternatives (lookup_translations). Also specifies ISO 639-1 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 indicate readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds that it's text-only, no widget, and internal/preparatory, which provides useful behavioral context beyond the 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 three sentences, front-loaded with the most critical information (internal, text-only, no widget). Every sentence adds value, and there is no redundancy or fluff. Highly concise and well-structured.

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 zero-parameter tool with no output schema, the description fully covers what the tool does, its context of use, and its relationship to sibling tools. It is complete and leaves no gaps for the 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 input schema has zero parameters, so schema description coverage is 100% by default. The description does not add parameter information, which is unnecessary. With 0 parameters, a baseline of 4 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 'Browse Quran reciters (data only)' and specifies it's an internal/preparatory tool that returns plain text without a widget. It distinguishes itself from list_reciters, which is the interactive widget for user-facing answers. Purpose is specific and 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 explicitly tells when to use (when plain text is requested or chaining to play_ayahs without showing raw data) and when not to use (prefer list_reciters for user-facing answers). It names the alternative tool (list_reciters) and provides clear decision criteria.

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 and destructiveHint=false. Description adds that it is text-only, no widget, and internal/preparatory, which provides additional behavioral context 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 concise and front-loaded with key distinctions. However, it could be slightly shorter by merging the two sentences.

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 simple tool (one optional parameter, read-only, no output schema), the description fully covers its purpose, usage, and limitations in the context of sibling tools.

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 'languages' parameter is documented in the schema). The description does not add extra meaning about the parameter, 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 for browsing tafsir collections in text-only mode, and explicitly distinguishes it from list_tafsirs, which is the user-facing widget.

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 guidance: never use as direct answer to user, use only when plain text requested or when chaining to ayah_tafsir, and default to list_tafsirs when in doubt.

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 readOnlyHint=true and destructiveHint=false; the description adds that the tool is internal/preparatory, returns text-only results with no widget. This context about the internal nature and non-interactive behavior goes beyond what annotations capture, though additional details like rate limits or authorization are not needed for this simple lookup.

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, well-structured paragraph that front-loads the key purpose ('INTERNAL/preparatory tool — text-only') and then provides usage rules. It contains no unnecessary words, but the density of information could be slightly improved with bullet points for readability.

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 optional parameters, no output schema) and the rich context from annotations and sibling tools, the description completely covers what an agent needs to know: when to use it vs alternatives, the data-only nature, and proper parameter usage. No 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?

Schema covers both parameters with descriptions (100% coverage). The description reinforces the correct usage of language codes ('ISO 639-1 codes like 'en', not names like 'english''), adding practical guidance beyond the schema's basic description. This clarifies the expected format for the language parameter.

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

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

The description clearly states the tool browses Quran translations as text-only data, explicitly distinguishing itself from the interactive widget sibling list_translations. The verb 'browse' and resource 'translations (data only)' are specific, and the scope is well-defined.

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 NOT to use (as user-facing answer) and when TO use: plain text requests or chaining into ayah_translation. Also provides a default recommendation ('when in doubt, prefer list_translations'). This provides clear decision guidance for the AI 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?

The description adds valuable behavioral context beyond what annotations provide. While annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, the description reveals this is an interactive display tool (suggesting potential UI elements or pagination) and clarifies the relationship with ayah_mutashabihat for obtaining phrase_id. It doesn't contradict annotations but provides additional operational 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?

The description is perfectly concise and well-structured with two sentences: the first states the core functionality, and the second provides specific usage scenarios. Every word earns its place, with no redundancy or unnecessary elaboration, making it easy to parse quickly.

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

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

Given the tool's moderate complexity, comprehensive annotations (readOnly, non-destructive, closed-world), 100% schema coverage, and the presence of an output schema, the description provides exactly what's needed. It explains the purpose, usage context, and behavioral aspects without needing to cover technical details already documented elsewhere.

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 100% schema description coverage, the input schema already fully documents all three parameters, including their types, constraints, and the mutual exclusivity rule between phrase_id and phrase_text. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline expectation without adding extra 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 description clearly states the tool's purpose with specific verbs ('Show phrase mutashabihat occurrences with an interactive display') and distinguishes it from siblings by focusing on phrase-level mutashabihat occurrences rather than ayah-level analysis or other Quranic functions. It explicitly identifies the resource (phrase mutashabihat occurrences) and the interactive nature of the display.

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 usage guidelines with two clear scenarios: when the user provides phrase text and asks where it appears, and when the user has a phrase_id from ayah_mutashabihat and wants all matches. It names a specific sibling tool (ayah_mutashabihat) as a potential source for phrase_id, giving concrete context for when to use this 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering safety and scope. The description adds valuable behavioral context beyond annotations: the interactive player widget detail, the critical reciter resolution workflow (calling lookup_reciters), and specific limits (max 50 queries, max 200 total ayahs). No contradiction with annotations exists.

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 efficiently structured with clear sections (purpose, usage conditions, reciter handling, format example, defaults, limits). Every sentence serves a distinct purpose: the first states the core function, the second provides usage context, and subsequent sentences offer critical implementation details without 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 complexity (multiple queries with optional parameters), rich annotations, and the presence of an output schema, the description is complete. It covers purpose, usage guidelines, parameter semantics, behavioral limits, and integration with sibling tools (lookup_reciters). No gaps remain for effective agent 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?

With 100% schema description coverage, the baseline is 3. The description adds meaningful semantic context: it explains the 'surah:ayah' format with an example ('1:1'), clarifies reciter_id handling (defaults to default_reciter_id if omitted, with a resolution workflow), and mentions the max limits which aren't in the parameter descriptions. This provides practical usage guidance 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 specific action ('Play Quranic ayah audio with an interactive player widget') and distinguishes it from siblings like ayah_search, ayah_tafsir, or ayah_translation by focusing on audio playback rather than text retrieval or analysis. The verb+resource combination is precise and 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 guidance on when to use this tool ('when the user asks to play/listen to ayahs') and detailed instructions on reciter handling, including when to call lookup_reciters first and when to omit reciter_id. It also distinguishes usage from text-based sibling tools by focusing on audio playback.

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 description adds valuable context beyond annotations: it mentions 'interactive timetable display' which suggests richer output than basic data, and specifies calculation methods. Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the description doesn't need to repeat safety aspects. No contradictions with annotations exist.

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 perfectly structured with two sentences: first states the core functionality, second provides explicit usage guidelines. Every word earns its place with zero redundancy, and the 'Use this when:' format makes guidelines immediately accessible.

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, rich annotations (readOnlyHint, openWorldHint), 100% schema coverage, and existence of an output schema, the description provides complete contextual information. It covers purpose, usage scenarios, and behavioral context without needing to explain parameters or return values that are already documented elsewhere.

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 100% schema description coverage, the input schema already thoroughly documents all three parameters (city, method, country) with descriptions, enum values, defaults, and constraints. The description mentions 'specific prayer method (for example ISNA or MWL)' which aligns with but doesn't significantly expand upon the schema's method parameter documentation.

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 with specific verbs ('Get Islamic prayer times') and resources ('for a city'), distinguishing it from sibling tools focused on Quranic content like ayah search, tafsir, or reciters. It explicitly mentions 'interactive timetable display' which adds unique functionality not implied by the name alone.

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 usage guidelines with 'Use this when:' followed by two concrete scenarios: when users ask for prayer times in a location, and when they ask to calculate times with specific methods like ISNA or MWL. This clearly defines when to use this tool versus alternatives (though no explicit exclusions are needed given distinct sibling 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 indicate read-only, non-destructive. Description adds diacritic-insensitive matching, BM25 ranking, and numeric query behavior, which are useful beyond 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 purpose and usage warnings. Every sentence adds unique value. No redundancy. Appropriate length for the tool's complexity.

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 no output schema, description explains it returns raw text and suggests chaining to other tools. All necessary context for correct usage is provided.

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%, baseline 3. Description adds meaning for 'query' (diacritic stripping, numeric matching) but 'max_results' only restates schema defaults. Overall adds some 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 description clearly states it's a text-only search tool for the Quran, distinguishing itself from ayah_search (the interactive widget). The verb 'search' and resource 'ayahs' are specific and 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?

Explicitly tells when to use (user asks for plain text, chaining) and when not to (user-facing answer, after ayah_search). Provides clear alternatives and exclusions.

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