Wesalna Islamic MCP

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

Annotations already establish read-only and idempotent behavior, lowering the burden on the description. The description adds valuable context: it uses Wesalna's daily cached metal price snapshot unless the caller overrides it. This makes the data source and default behavior explicit. There is no contradiction with 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 sentences with no filler and front-loads the core verb and the three calculation modes. The first sentence is dense with interrelated rules, but every clause carries information an agent needs. It remains appropriately sized for a 15-parameter tool.

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

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

The tool has no output schema, and the description never states what the result contains – such as the amount due, whether nisab was met, or a breakdown by category. While inputs and calculation rules are covered thoroughly, the missing return-shape information is a significant gap given the absence of an 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 coverage is 100%, so the baseline is 3. The description adds meaningful calculation semantics beyond the schema: the 2.5% rate above gold or silver nisab, conversion of karat weight to pure gold against the 85-gram threshold, and the sa' weight per person for fitr. This enriches parameters like nisabBasis, pieces, and staple.

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 – 'Calculate zakat' – then enumerates the three distinct calculation modes: money, gold, and zakat al-Fitr. It is the only zakat-related tool among its siblings, so there is no ambiguity about which tool to pick.

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 clearly explains when each mode applies: money for cash/savings/debts, gold for karat-weighted pieces, and fitr for per-person staple food. It also tells the agent that cached prices are used unless it supplies its own, which is useful guidance for customizing calls. It does not explicitly state exclusions, but no sibling tool competes for this purpose.

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 this a read-only, idempotent operation, so the bar for additional behavioral disclosure is lower. The description adds useful context by specifying the Umm al-Qura calendar system and the behavior when both parameters are omitted. It does not mention error handling for invalid inputs, but the annotation safety profile is well covered.

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 compact sentences contain all essential information with no filler. The primary conversion behavior is front-loaded, and the no-argument behavior is appended 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?

For a read-only tool with two optional parameters and no output schema, the description covers both conversion directions and the default return behavior. The main gap is that it does not specify whether supplying both parameters is invalid or how the system handles that case, leaving room for ambiguous calls.

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

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

Schema description coverage is 100%, so the schema already documents each parameter's meaning, type, and constraints. The description clarifies which conversion direction each parameter serves but adds no syntax or edge-case semantics beyond the schema. The baseline of 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 names the specific verb 'Convert' and the resource 'date', states both conversion directions, and identifies the Umm al-Qura calendar system. It also clearly distinguishes itself from the sibling tools, none of which perform date conversion.

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 defines two modes of use and a sensible no-argument default, so an agent knows when to call the tool for a date conversion. However, it does not state that the 'hijri' and 'gregorian' parameters should not both be supplied, nor does it provide explicit exclusions or alternative-tool routing.

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, the description explains what the agent receives (greeting wording and a link), what it should do with the link (show it to the user), and where the actual card image is rendered (on the external page). This prevents the common mistake of treating the link itself as the image. It aligns with readOnlyHint and idempotentHint.

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 focused sentences with the key output and user-facing instruction front-loaded. There is no filler; every clause earns its place.

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

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

With no output schema, the description correctly explains the return values: greeting wording and a link, with the card produced on the target page. It also covers how to present the URL. A small gap is that it does not describe the expected format or structure of the returned wording, but this is minor given the schema covers inputs fully.

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

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

Schema description coverage is 100%, so the parameters are already well documented in the schema. The main description adds no parameter-specific meaning beyond the schema, so the baseline score of 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 states a specific verb and resource: compose an Islamic greeting card and return the wording plus a link to the finished card. It is clearly differentiated from sibling listing tools like list_greeting_card_occasions, and the title aligns tightly with the described behavior.

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 intended use is implied clearly: generate a greeting card for occasions like Ramadan, Eid, or Friday. However, it does not explicitly state when to use it versus alternatives or when not to use it, though no competing sibling tool exists for card creation.

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 and idempotentHint. The description adds useful behavioral context beyond those: it clarifies that only published content is returned, that stories include all chapters, and that the output covers both Arabic and English. No behavioral surprises are hidden.

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, compact sentence that front-loads the core action ('Return the full text') followed by the key qualifications. Every clause earns its place with no redundant or vague wording.

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 read-only two-parameter tool with full schema coverage and idempotent annotations, the description provides enough contextual detail: scope, language, published status, and story chapter behavior. It does not describe the response format, but it states the content returned, which is sufficient given the tool's simplicity.

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 both 'kind' and 'slug' already described meaningfully, including the enum and the URL-based slug explanation. The description does not add new parameter-level meaning; it simply references the same concepts, so the baseline of 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 identifies a specific verb and resource: returning the full text of one published article or one prophetic story with all chapters. It also clearly distinguishes itself from siblings like list_content, which lists content, and get_surah, which fetches Quran surahs.

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 implies when to use the tool: to fetch the full text of a single article or story by kind and slug. However, it does not explicitly mention alternatives such as list_content for discovering slugs, nor does it state when not 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 cover read-only/idempotent safety, so the description adds real value beyond them: the required attribution link in the output, dataset breadth (226 countries, 2,500+ cities, English/Arabic), and the extra time values beyond the five prayers. Missing only notes on default-resolution behavior when no location is supplied.

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

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

A single front-loaded sentence covering scope, inputs, and the attribution constraint with no filler. It is dense and slightly run-on, but every clause carries information.

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

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

With no output schema, the description correctly notes the attribution requirement and enumerates returned time values. The only real gap is the zero-required-parameter case, where the resolution rule for a location-less call is unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the either/or semantics between coordinate and city/country modes that the schema only hints at per-parameter. It does not, however, explain what happens when neither coordinate nor place is given.

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

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

States a specific verb (calculate) and resource (five daily prayer times plus sunrise, imsak, midnight, last third), plus both input modes (lat/long or city/country). This clearly separates it from siblings like list_prayer_cities and get_qibla.

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 is implied by the input modes described, but there is no explicit guidance on when to prefer this over list_prayer_cities (to discover valid city names) or get_qibla. No exclusions or prerequisites given.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety and repeatability. The description adds specific output behavior—bearing from true north and great-circle distance to the Kaaba—which goes beyond the annotations and helps the agent understand what the call returns.

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, focused sentence with zero filler. It front-loads the primary output (bearing) and then the secondary (distance), making it immediately clear and 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?

For a simple read-only tool with two numeric parameters and no output schema, the description covers the core purpose and outputs. It does not specify units for the distance (e.g., kilometers or miles) or the bearing (degrees), which is a minor but useful detail that is absent.

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

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

The schema provides 100% description coverage for both parameters (latitude and longitude), so the baseline is 3. The description adds only the implicit 'location' context and does not elaborate on parameter formatting or units beyond what the schema already documents.

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

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

The description states a clear verb (Return), a specific resource (Qibla bearing and great-circle distance to the Kaaba), and the scope (for a location). It distinctly differentiates from sibling tools like get_prayer_times or convert_hijri_date, leaving no ambiguity about what this 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?

The description clearly implies this tool is for location-based Qibla direction, and given the sibling list, no other tool appears to serve this function. However, it does not explicitly mention when not to use it or name an alternative, so it lacks explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful content-level detail about the returned text variants, but it does not disclose behavioral details such as the default verse range when fromAyah/toAyah are omitted or error behavior for invalid surah slugs. 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 sentence with a front-loaded verb phrase and a colon that cleanly separates the operation from the payload details. There is no filler, repetition, or unnecessary elaboration.

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

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

With no output schema, the description carries some responsibility for describing return contents, and it does name the three text forms. Minor gaps remain, such as unspecified metadata fields and default verse-range behavior, but these are not critical for a low-complexity retrieval tool with well-documented parameters.

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

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

Schema description coverage is 100%, and the description adds no additional parameter semantics beyond what the schema already provides for surah, fromAyah, and toAyah. Baseline 3 is appropriate when the schema carries the full parameter documentation burden.

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 clear verb and resource: 'Return one surah's metadata and its verses,' and it enumerates the exact content included (Uthmani Arabic, simplified Arabic, Saheeh International translation). This differentiates it from siblings like list_surahs or search_quran, which serve different retrieval purposes.

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 implies usage for fetching a single surah's content, but it does not explicitly state when to use this instead of alternatives like list_surahs or search_quran. No when-to-use, when-not-to-use, or alternative-naming guidance is given.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate them. It adds valuable behavioral context by enumerating the output fields and the optional filter, giving the agent a clear expectation of the response content. No contradictions found.

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, tightly written sentence that front-loads the action and includes all necessary details without redundancy. Every word contributes 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?

For a simple listing tool with one optional parameter and no output schema, the description covers the returned fields and the filter capability. It omits pagination or ordering details, but these are not critical for a straightforward list and the tool's simplicity reduces the need for more.

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 only parameter 'category' is fully described in the schema with an example ('morning, evening, sleep'), and the description merely restates the optional filter. Since schema description coverage is 100%, the description adds no new semantic meaning 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 clearly states the tool lists authentic azkar and supplications with specific fields (Arabic text, transliteration, English meaning, repetition count, source reference) and optional category filtering. This distinguishes it from generic siblings like list_content and from specific tools like get_surah.

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 purpose implies when to use the tool (to list azkar) but does not explicitly contrast with alternatives such as get_content for individual items or list_content for general content. There is no statement about when not to use it, only an implied context.

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 idempotentHint, and the description does not contradict them. It adds that only 'published' content is returned, and specifies the fields included (titles, summaries, URLs), which goes beyond the annotations and provides useful behavioral context.

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

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

The description is a single, well-structured sentence that front-loads the core purpose (listing editorial content) before detailing the content types and return fields. There is no redundancy or wasted words, making it appropriately concise.

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 read-only list tool with two parameters (one required enum, one optional) and no output schema, the description covers the key return fields. It does not mention pagination, ordering, or limits, but given the tool's simplicity and the annotations covering safety, this is sufficient for an agent to invoke 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?

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description does not add significant meaning beyond the schema; it mentions articles and stories but these are already defined in the enum. The category parameter's behavior is already described in the schema, and the description adds no extra syntax or edge-case details.

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 Wesalna's published editorial content, specifically knowledge-base articles or illustrated stories of the prophets, with titles, summaries, and canonical URLs. It identifies the exact resource and output, and distinguishes it from sibling list tools like list_azkar and list_surahs which cover other content types.

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 implies the tool is for listing editorial content, but it does not explicitly state when to use it over alternatives such as get_content for fetching a single item or other list tools. There is no mention of exclusions or conditions that would guide an agent to choose this tool specifically.

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 idempotentHint=true, lowering the burden. The description adds meaningful behavioral context not in annotations: the tool returns supported occasions, backgrounds, shapes, and default Arabic/English wording, and the ids are intended for later card creation. 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?

Two sentences with zero waste. The first sentence states the full scope of what is listed; the second provides essential usage direction. Everything earns its place.

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

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

For a zero-parameter, read-only list tool with no output schema, the description is complete: it names the resource, the contents, the wording language, and the correct calling context relative to create_greeting_card. Nothing essential 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?

With zero parameters, the schema has nothing to document and the description carries no parameter burden. Baseline 4 applies since no parameter semantics are needed.

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

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

States a specific verb ('List'), a precise resource ('every occasion, background and shape supported by the Wesalna greeting card designer'), and additional output ('default Arabic and English wording'). It is clearly distinguishable from siblings like create_greeting_card and list_content.

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 instructs when to use the tool: 'Call this before create_greeting_card to use valid ids.' This directly routes the agent to the prerequisite step and names the sibling that depends on 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, openWorldHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the 'every city' scope and the optional filter behavior, but does not disclose output size, ordering, or pagination. With annotations present, this is adequate but not rich.

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

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

The entire description is one dense sentence that front-loads the core action and resource, then enumerates return fields and the filter. There is no filler, repetition, or tangential detail.

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?

Despite having no output schema, the description lists every return field (Arabic/English name, country, coordinates, timezone, calculation method, canonical URLs) and documents the optional filter. Annotations cover safety and idempotency. Nothing essential is missing for an 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 description coverage is 100%: the search parameter is already documented as filtering by city/country name in Arabic/English or by slug. The description adds the word 'optionally' and restates the name/country filter, which is marginal value beyond the schema. This matches the baseline for full schema 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 uses a specific verb ('List') plus a specific resource ('every city that has a dedicated Wesalna prayer timetable page') and enumerates the exact return fields. This clearly distinguishes it from sibling tools like get_prayer_times or list_content.

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 makes clear that this is a discovery/list operation over prayer cities and that an optional filter by name or country exists. It does not explicitly name alternatives or give when-to-use versus get_prayer_times, but the purpose is specific enough that the intended context is evident.

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

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

Annotations already declare the operation read-only and idempotent, so the description does not need to restate that. It adds useful context by enumerating the returned fields and noting the optional filter, but it does not disclose details like ordering, partial-match semantics, or whether the full 114-item list is always returned unfiltered.

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 with no filler. The primary behavior and output fields are front-loaded, and the optional filtering behavior is stated plainly in the second sentence. Every word earns its place.

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

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

The description compensates well for the absence of an output schema by explicitly naming the returned attributes. It also covers the single input parameter adequately. Minor gaps remain, such as matching behavior for search and sort order, but these are low-stakes for a simple catalog listing.

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

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

Schema description coverage is 100%, and the input schema fully documents the 'search' parameter as filtering by Arabic/English name or slug. The description repeats the optional filtering idea but adds no new semantic detail beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states a specific verb ('List'), a concrete resource ('the 114 surahs of the Quran'), and enumerates the fields returned. Its plural scope clearly sets it apart from sibling tools like get_surah, which implies retrieving a single surah.

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 makes the core use case clear: list all surahs or optionally filter by name/slug. However, it does not explicitly contrast itself with siblings such as get_surah or search_quran, so an agent must infer when this tool is preferable to those alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the read-only nature. The description adds valuable behavioral context: it returns daily portions in multiple units, a day-by-day schedule with exact surah:ayah boundaries and wesalna.com links, and explains the page-weighting logic. This goes beyond what annotations convey.

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

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

Three sentences with no fluff. The first sentence states the purpose and modes, the second summarizes the output content, and the third explains the weighting behavior. This is concise and front-loaded, though the third sentence could be seen as extra but it is relevant.

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 6 optional parameters and no output schema, the description does an excellent job of explaining the return value: daily portion in pages, juz, verses, estimated minutes, and a full day-by-day schedule with exact surah:ayah and links. The agent can predict the result without needing an 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?

The input schema has 100% coverage with descriptive text for every parameter, including the semantics of the two date-based modes. The description does not add extra parameter details beyond what the schema already provides; it merely restates the two modes. Thus the baseline of 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 specific verb 'Build' and the resource 'Quran completion (khatma) plan', and elaborates on what it does: splitting the mushaf across days or a date range. It also distinguishes itself from any sibling tools by its unique function, since none of the siblings relate to planning a khatma.

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 clear context for when to use the tool: when a khatma plan is needed, either over a number of days or between two dates. It does not mention alternatives or exclusions, but given the sibling list contains no overlapping planning-related tools, the intended usage is sufficiently clear.

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

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

Annotations already establish readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavior beyond annotations: it states that matching supports partial, whole-word, and Arabic-root modes, and that results include surah/ayah numbers plus a distribution of matches across surahs. This gives the agent a concrete picture of output and matching semantics without contradicting 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 only two sentences, front-loaded with the core action, then a compact enumeration of the key features and return format. Every clause earns its place; there is no filler or repetition of schema descriptions. It is appropriately sized for an 8-parameter search tool.

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 (8 parameters, 2 enums, no output schema), the description covers the essential deciding factors: searchable languages, matching modes, filter dimensions (juz, surah range), and return contents. It does not explicitly mention pagination or the default limit, but those are already described in the schema. The addition of 'how the matches spread across surahs' is a nice completeness touch, leaving only minor 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 the schema already documents all eight parameters and their meanings. The description essentially paraphrases those meanings (e.g., 'all-words or any-word mode' maps to wordMode, 'Arabic-root matching' maps to matchType=root) without adding new detail. It groups them helpfully but does not go beyond the schema to explain syntax, defaults, or edge cases, so a 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 opens with a specific verb and resource: 'Search Quran verses by Arabic wording or by the English translation.' It clearly distinguishes this from sibling tools like get_surah and list_surahs by framing it as a cross-cutting search over verses rather than a retrieval or listing operation. The supported match modes and filters further define its unique role.

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 conveys clear context for when to use the tool: when a user wants to search across Quran verses by wording/translation with flexible matching. It does not explicitly name alternatives or provide 'when not to use' guidance, but the contrast with siblings (get_surah, list_surahs, plan_khatma) is implicit and clear from the search-focused wording.

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