Tarteel MCP Server

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

Annotations already declare readOnlyHint true, destructiveHint false, so the tool is safe. The description adds 'interactive display' context but does not disclose any additional behavioral traits like auth needs or rate limits. Given annotation coverage, a score of 3 is appropriate.

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 long: one stating the core purpose, the other listing usage scenarios. No unnecessary words, and the most critical information is front-loaded.

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 moderate complexity (3 params, complete schema, output schema, good annotations), the description fully covers purpose, usage, and relationship to siblings. It does not need to explain return values due to existing output schema.

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

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

Schema description coverage is 100% (baseline 3), but the description adds meaning by explaining that the tool works for 'one ayah' and that it returns phrase IDs and counts, which is not in the schema. This elevates the score to 4.

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

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

The description uses a specific verb ('Show') and resource ('repeated phrase metadata for one ayah'), and explicitly distinguishes from the sibling tool 'phrase_mutashabihat' by positioning this as a preliminary step.

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 two explicit 'Use this when' scenarios and states that this tool should be used before calling 'phrase_mutashabihat', offering clear context for when to use it versus alternatives.

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

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

Beyond annotations (readOnlyHint, destructiveHint), the description reveals that diacritics and punctuation are ignored, matching is diacritic-insensitive and ranked by BM25, numeric-only queries match by ordinal number, and results are shown in an interactive widget. 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?

The description is compact (5 sentences), front-loaded with the primary purpose, uses bold for key terms, and each sentence adds essential information without redundancy. 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?

Given the tool's complexity, the presence of an output schema, and the rich context from annotations, the description covers usage guidelines, query behavior, numeric matching, and sibling distinction comprehensively. It leaves no obvious gaps for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, providing baseline 3. The description adds value by explaining the 'query' parameter behavior (diacritics ignored, numeric matching) and reiterating the 'max_results' default and range. Though the schema covers the basics, the description clarifies search semantics and ordinal matching.

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 the 'DEFAULT tool for user-facing Quran search', specifies the action ('find ayahs that contain X', 'search the Quran for X'), and distinguishes itself from the sibling tool 'search_ayahs_text' by stating it is the final tool call for user-facing searches.

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 this tool (ANY user-facing search) and when to use the alternative 'search_ayahs_text' (user asks for plain text/raw results, or results fed into another tool). Also provides guidance on numeric-only queries and the interactive widget behavior.

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. Beyond that, the description adds valuable behavioral context: this is a 'widget' (visual display), it's the 'FINAL tool call' for these requests, has limits (max 20 queries, max 50 items), and explains that guessed slugs fail validation. 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 fairly long but well-organized: it starts with the core purpose, then usage guidelines, slug handling, and limits. Each sentence adds value. It could be slightly tightened, but overall it's efficiently structured for agent consumption.

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 (nested queries, multiple optional fields, slug resolution, limits) and the presence of an output schema, the description covers the essential context: tool purpose, usage, slug handling, and constraints. It could possibly mention output format briefly, but the output schema already covers that. Good completeness.

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%, meaning all parameters are already described in the schema. The description reinforces key points like ayah key format and the need for at least one of languages or tafsir_slugs, but adds minimal new semantic meaning beyond the schema. 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's the 'DEFAULT tool for user-facing tafsir display' and lists concrete user requests ('show me the tafsir of…', 'what does Ibn Kathir say about…'). It distinguishes itself from sibling tool get_tafsir_text by specifying when to use which tool, providing strong purpose clarity.

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 request), when-not-to-use (explicit plain text request or piping), and names the alternative tool (get_tafsir_text). Also gives detailed slug-handling guidance: always call lookup_tafsirs first, not to guess slugs. This is comprehensive usage 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), the description discloses that this is a widget, that it is the final call for display, and includes constraints like Arabic unsupported and language code formats. 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 comprehensive yet efficient. Every sentence serves a purpose: purpose, usage guidelines, slug handling, and parameter formatting. No superfluous text.

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 (array of nested objects, multiple optional fields), the description covers all aspects: when to use, parameters format, constraints, and edge cases. With an output schema present, it is complete.

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

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

The input schema already has high coverage (100%), but the description adds crucial details: ayah key format, ISO 639-1 codes, avoiding language names, and that empty arrays are treated as omitted. It also warns against guessing slugs.

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 displaying translations of Quran ayahs for user-facing requests. It uses specific verbs ('show/see translations') and distinguishes itself from the sibling tool get_translation_text.

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 versus get_translation_text, including user-facing vs plain text or piped output. It also instructs on slug handling and the need to use 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 indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it does not render a widget, its internal nature, and usage limits (max 20 queries, 50 items). 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?

The description is well-structured: it begins with the core purpose and warning, then provides usage guidance, and finally parameter notes. While comprehensive, it could be slightly more concise; however, every sentence adds necessary context.

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

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

Given the tool's complexity (nested array parameters, optional fields, limits), the description covers essential aspects: when to use, format, constraints (max items), and key exclusions. Without an output schema, it does not describe return values, but that is acceptable as the focus is on input and behavior.

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 has 100% coverage for the only required parameter 'queries', including nested property descriptions. The description reinforces key constraints (format 'surah:ayah', at least one of languages or tafsir_slugs) and provides examples, but adds little beyond the schema's own detailed property descriptions.

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 as an 'INTERNAL/preparatory tool' for retrieving text-only tafsir data. It distinguishes itself from the sibling tool 'ayah_tafsir' by specifying its exclusive use cases, 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 usage guidelines: use only when the user explicitly requests plain text or when chaining results; never as a user-facing answer; prefer ayah_tafsir by default; and do not follow ayah_tafsir with this tool. This clearly differentiates from alternatives.

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

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

Annotations already indicate readOnlyHint=true, so no need to restate safety. Description adds valuable behavioral context: tool is internal/preparatory, never renders a widget, and Arabic is unsupported, enhancing transparency 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?

Description is fairly concise at six sentences, front-loaded with core purpose, and each sentence adds value. Could be slightly more streamlined but overall efficient.

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?

Completeness is good given no output schema: covers when to use, parameter details, and constraints. Omits return format but is adequate for a data retrieval tool with full schema coverage.

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 description adds crucial usage details: ISO 639-1 codes, no Arabic, ayah key format, and relationship with list_translations, which significantly aids correct parameter usage.

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 retrieves translation text data only, and distinguishes from the sibling tool ayah_translation by noting it is internal/preparatory and text-only without a 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 states when to use (raw text requests, chaining) and when not to use (as user-facing answer), and provides alternatives (ayah_translation). Also gives precise formatting instructions for parameters.

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 the description adds useful behavioral context: it returns an interactive widget for browsing and should be 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?

Description is clear and front-loaded with key purpose, though it could be slightly more concise. Every sentence adds value.

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

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

Given zero parameters, an output schema exists, and the description fully explains usage scenarios and output behavior (interactive widget), it is complete for the tool's 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?

No parameters are present, and schema coverage is 100% (empty schema), so description does not need to add parameter details; baseline score applies.

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

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

The description clearly identifies this as the DEFAULT tool for user-facing reciter listing, distinguishing it from the sibling `lookup_reciters` by specifying its interactive widget 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 this tool (user-facing queries like 'list Quran reciters') and when to use `lookup_reciters` instead (plain text requests or piping into another tool), providing 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?

Adds behavioral context beyond annotations: shows an interactive widget, is the final tool call, and does not return plain text. Annotations already indicate read-only and non-destructive.

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 efficient and front-loaded with the key point, though slightly verbose; each sentence adds value.

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

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

Given the excellent annotations and output schema, the description fully covers purpose, usage differentiation, and behavioral aspects.

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 description only repeats the schema's parameter description ('Optional ISO 639-1 language code filters') without adding new 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 tafsir-listing questions, provides specific example queries, and distinguishes it from 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 states when to use this tool (user-facing queries) and when to use lookup_tafsirs instead (conditions a and b), including a 'when in doubt' directive.

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, openWorldHint=false, destructiveHint=false. The description adds behavioral context: it shows an interactive widget, filters out rows without usable slugs, and provides display labels for language_name. This 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 front-loaded with the key purpose and usage rules. It is moderately concise but contains necessary guidance. Could be slightly more terse, but every sentence serves a purpose.

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 2 optional parameters and an output schema, the description is completely adequate. It explains the widget nature, filtering, locale, and differentiation from sibling. No gaps remain for the agent to use it correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds important usage hints: for language parameter, it emphasizes using ISO 639-1 codes not names; for locale, it clarifies the purpose (response localization). This adds value 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 it is the DEFAULT tool for user-facing translation-listing questions and explicitly distinguishes it from its sibling lookup_translations by specifying when to use each. It uses specific verb+resource (list translations) and provides a clear 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?

The description provides explicit when-to-use (any user-facing query like 'what English translations are available'), when-not-to-use (use lookup_translations for plain text/raw data or when piping results), and includes a tie-breaking 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 indicate readOnlyHint=true and destructiveHint=false. The description adds that the tool returns text only and does not render a widget, which is behavioral context beyond annotations. No contradictions. Missing details on whether results are paginated or sorted, but adequate for a simple data 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 well-structured with clear sections and key information front-loaded. It uses capitalization for emphasis and provides examples, but is slightly verbose. Could be more concise but not wasteful.

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

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

No output schema exists, and the description does not explain what data is returned (e.g., fields, format). While the agent can infer from sibling tool list_reciters, this gap could lead to confusion about the exact output structure.

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 schema coverage is 100%. The description does not need to add parameter semantics. Baseline 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 it is an internal/preparatory tool that returns text-only data about Quran reciters, distinguishing it from list_reciters which is the interactive widget. The verb 'lookup' is appropriate for a data retrieval 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?

Explicitly states when to use (internal purposes, chaining with play_ayahs) and when not to use (not for user-facing answer, prefer list_reciters). Provides two specific use cases, making the decision clear 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?

Annotations already declare readOnlyHint=true and safe operation. Description adds that it is an internal/preparatory text-only tool with no widget, providing useful 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?

Description is concise at three sentences, each sentence serves a distinct purpose (role, when not to use, when to use). No 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 simplicity (0 required params, no output schema), the description covers usage boundaries and intent adequately. Lacks explicit output description but acceptable for an intermediate 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 has 100% description coverage for the one parameter, so the description adds no additional semantic value beyond what the schema already provides.

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 specifies the tool is for browsing tafsir collections in text-only mode, distinguishing it from list_tafsirs which renders a widget. It uses clear verb ('browse') and resource ('tafsir collections').

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 NEVER use as user-facing answer for supported tafsirs, directs to list_tafsirs for that, and provides two allowed scenarios (explicit plain text request or chaining with ayah_tafsir). Also includes a fallback preference rule.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds that it's internal/preparatory, text-only, no widget rendered, and explains chaining behavior to ayah_translation, providing valuable context 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 slightly lengthy but well-structured with critical info front-loaded (INTERNAL/preparatory, text-only, etc.) and clear case breakdown. Every sentence adds value with no obvious 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 lacks any mention of the output format or structure, which is problematic given no output schema exists. The agent needs to know the return type to chain correctly with ayah_translation. Otherwise, the description covers usage context well.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the language parameter format (ISO 639-1 codes) and mentions locale for localization, but adds minimal new semantic information beyond the schema descriptions.

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 an internal/preparatory tool for raw data, contrasting with list_translations. The verb 'browse' is specified, and it distinguishes from the sibling list_translations by emphasizing no widget and text-only output.

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 defines when to use (cases a and b) and when NOT to use (never as user-facing answer), provides an alternative (list_translations), and gives a decision rule ('when in doubt, prefer list_translations'). It also specifies format requirements (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 declare readOnlyHint=true, so the description doesn't need to reiterate non-destructiveness. It adds 'interactive display' but doesn't elaborate on the behavior or output format. With existing output schema, the burden is lower, so a 3 is appropriate.

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?

Two sentences that front-load the action and purpose, followed by specific usage conditions. No wasted words; every sentence is essential.

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 existence of an output schema and comprehensive annotations, the description provides enough context for an AI agent to understand when and how to use this tool. It covers the core functionality and usage triggers.

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 detailed parameter descriptions. The description only restates the mutual exclusion of phrase_id and phrase_text, adding no new semantic information 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 action ('Show phrase mutashabihat occurrences') and the resource, distinguishing it from the sibling tool 'ayah_mutashabihat' by specifying the input types (phrase text or phrase_id).

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

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

Explicitly provides two use cases: when the user provides a phrase text and asks for occurrences, or when the user has a phrase_id from another tool. No explicit when-not-to-use, but context is clear.

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

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

Annotations declare readOnlyHint=true, consistent with a playback tool. The description adds important behavioral context: the interactive player widget, the risk of guessed reciter IDs pointing to wrong reciter, and the default reciter behavior. 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 a single paragraph, front-loaded with purpose, and structured with key guidelines. It is efficient but could be slightly improved by using bullet points for the reciter handling and limits. However, it is still quite concise with no redundant text.

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 presence of an output schema, the description does not need to explain return values. It covers purpose, usage context, reciter handling, format, and limits, making it fully informative for an AI agent to invoke this tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by specifying ayah key format ('surah:ayah'), clarifying that reciter_id is optional and default_reciter_id applies, and reiterating the 50/200 limits. This complements the schema well.

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?

Title 'Play Quran audio' and description 'Play Quranic ayah audio with an interactive player widget' clearly state the tool's function. It is distinct from siblings like ayah_translation or ayah_tafsir which focus on text/tafsir, not audio playback.

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 says when to use ('when user asks to play/listen to ayahs') and provides detailed reciter handling instructions: call lookup_reciters if reciter is named, omit reciter_id otherwise. Also states limits (max 50 queries, max 200 total ayahs), giving complete usage 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 this is read-only and non-destructive. The description adds that it provides an 'interactive timetable display' and supports specific calculation methods, offering helpful behavioral context 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 two sentences, concise, and front-loaded with the main purpose. No unnecessary 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?

Given the presence of an output schema, the description is complete in explaining the tool's purpose, usage conditions, and parameters. 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?

Schema description coverage is 100%, so baseline is 3. The description doesn't add significant additional meaning beyond what the schema already provides for city, method, and country.

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 gets Islamic prayer times for a city with an interactive timetable. It specifies the resource (prayer times) and action (get), and distinguishes itself from sibling tools that focus on ayahs, tafsir, translations, etc.

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 when to use the tool: when the user asks for salah times in a location or to calculate with a specific method like ISNA or MWL. This provides clear context for 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 declare readOnlyHint and destructiveHint. Description adds non-obvious behaviors: Arabic script only, diacritics ignored, numeric query matches ordinal numbers, BM25 ranking. All consistent. 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 critical purpose and usage constraints. Each sentence adds value, though the list of 'play_ayahs, ayah_tafsir, or ayah_translation' could be slightly trimmed. Generally efficient.

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

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

No output schema, but description explains it returns ayah keys for chaining. Covers query constraints, ranking, and linkage to other tools. Slightly lacking explicit return format details, but sufficient 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 100% and description adds context: for 'query' it explains diacritics/punctuation stripping and numeric matching; for 'max_results' it gives default and range. Adds BM25 relevance info 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?

Title states 'Search the Quran by Arabic text (data only)'. Description immediately clarifies it is an internal/preparatory tool with no widget, and distinguishes from sibling 'ayah_search' (user-facing widget). Verb 'search' plus resource 'ayahs_text' is specific.

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: only for text-only raw results or when chaining to other tools. Says 'NEVER use as the user-facing answer' and 'when in doubt, prefer ayah_search'. Also warns against duplicating work after ayah_search.

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