quran-search-engine mcp

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so safety is covered. The description adds value by mentioning the inverted lemma index (implementation detail) and 'Paginated' (pagination behavior), which are not in annotations. It does not contradict 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 of 12 words, front-loaded with the action and resource. Every word contributes, with no redundancy or filler.

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

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

Given the rich annotations (read-only, idempotent, non-destructive) and the schema defining required and optional params with constraints, the description provides sufficient core context. No output schema exists, so return values need not be explained. The only notable gap is usage guidance versus alternatives, but overall it is adequate for a filtered-list tool.

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

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

Schema description coverage is 0%, so the description must compensate. It provides semantic meaning for the 'lemma' parameter by saying 'normalized lemma', and 'Paginated' hints at the page/limit parameters' role. However, it does not explicitly describe page or limit beyond what the schema already provides, so compensation is partial.

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 'Find' with a clear resource 'verses' and a specific criterion 'normalized lemma via the inverted lemma index.' It clearly distinguishes from sibling tools like 'find_verses_by_root' by explicitly saying 'lemma' rather than 'root', and mentions normalization, which adds precision.

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 when you want verses by a normalized lemma, but it does not explicitly state when to use this tool versus alternatives such as 'find_verses_by_root' or 'search'. No exclusions or alternative recommendations are provided, so context is present but only implicit.

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 behavioral details beyond annotations and schema: the root must be normalized, the search uses an inverted root index, and results are paginated. These are meaningful characteristics that affect how the agent invokes the tool, while remaining consistent with the readOnlyHint and idempotentHint 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 exceptionally concise: two short sentences that front-load the main action and convey the essential normalization requirement and pagination behavior. No superfluous 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 read-only, paginated search tool with annotations covering safety and a clear resource ('verses'), the description sufficiently conveys the purpose and key behavioral notes. It lacks an explicit return structure, but 'Find verses' adequately implies the result type. It could mention alternatives for full completeness, but the simplicity of the tool makes this adequate.

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 0% description coverage, so the description carries the burden. It clarifies that the 'root' parameter expects a normalized Arabic root and that pagination applies to the 'page' and 'limit' parameters, but it does not elaborate on each parameter's precise role or constraints 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 finds verses containing a normalized Arabic root using an inverted root index, distinguishing it from sibling tools like find_verses_by_lemma (root vs lemma) and get_verse (single verse). The verb 'find' and resource 'verses' 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?

The description implies usage for root-based verse queries but does not explicitly state when to use this tool over alternatives such as find_verses_by_lemma or search. There is no mention of exclusions or when-not-to-use guidance, leaving the decision to inference from the tool name and 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 establish read-only and idempotent behavior. The description adds the valuable detail that it returns null when no match is found, and clarifies the acceptable identifier formats, going beyond annotation coverage.

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

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

The description is two concise sentences with no wasted words. It front-loads the action and immediately explains input and output, earning its place 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 simple lookup tool with one parameter and no output schema, the description is complete: it defines all valid input formats, the resource type, and the return behavior. No additional context is necessary.

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

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

With 0% schema description coverage, the description fully compensates by explaining that 'identifier' can be a numeric id (1–114) or a name in various forms (Arabic, English, romanization). This gives complete meaning to the sole 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 action ('Look up'), the resource ('one surah'), and the accepted identifier forms (numeric id, Arabic name, English name, romanization). It also specifies the return value, distinguishing it from sibling tools that list all surahs or operate on verses.

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

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

The description gives clear context: use this when you need a specific surah's information by any of several identifier types. It doesn't explicitly name alternatives, but the scope ('one surah') implies it is not for listing all surahs, making the usage context 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 provide readOnly, idempotent, and non-destructive hints. The description adds the return behavior ('Returns the full verse record or null'), which is beyond the annotations. It does not contradict annotations and provides useful additional context about the output.

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

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

The description is two sentences, front-loaded with the primary action, and contains no filler. Every word adds value, making it 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?

Given the low complexity of a single verse fetch and no output schema, the description covers the key aspects: how to identify the verse and what to expect in return (full record or null). It is not comprehensive (e.g., no error behavior), but it is sufficient for 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?

With 0% schema description coverage, the description compensates by explaining that gid is a global id and that ayaId/suraId are used as a pair. This adds meaningful semantics beyond the raw schema. However, it does not clarify mutual exclusivity or validation details, so it is not perfect.

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 'Fetch a single verse' with a specific verb and resource, and specifies two identification methods. This distinguishes it from siblings like get_verses_by_range (plural) and get_verse_morphology (morphology). High clarity and differentiation.

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 single verse lookup but does not explicitly mention alternatives or when not to use it. It says 'by global id or by (suraId, ayaId)', which indicates the main use case, but there is no explicit guidance on choosing this over get_verses_by_range for multiple verses. Guidance is implied but not stated.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds that it returns morphology or null, and that it supports two identifier modes, which are useful behavioral details. However, it does not discuss error cases, authentication, or rate limits, so the added transparency beyond annotations is modest.

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

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

The description is a single front-loaded sentence followed by a short return-value note. It covers the action, resource, identifier modes, and return behavior in 22 words, with no redundant phrasing or unnecessary details.

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 3 parameters, no required ones, and no output schema. The description explains the parameter selection modes and the return value (morphology or null). It does not define the exact structure of 'morphology', but for a simple read-only lookup this is likely sufficient for correct 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 zero schema description coverage, the description compensates by explaining the relationship between parameters: 'by gid or by (suraId, ayaId)'. This clarifies that gid is an alternative to the suraId/ayaId pair and that suraId and ayaId must be used together, which is not evident from the schema alone.

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 lemmas and roots for a single verse, using the specific verb 'get' and resource 'lemmas and roots'. It distinguishes itself from siblings like get_verse and find_verses_by_lemma by specifying the morphological data and identifier modes (gid or suraId/ayaId).

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 retrieving morphology for a single verse, but it does not explicitly state when to use this tool versus alternatives like find_verses_by_lemma or get_verse. The context of 'single verse' and 'lemmas and roots' gives an implied usage, but there are no direct instructions or exclusions.

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

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

The annotations already indicate a read-only, idempotent, non-destructive operation. The description adds the acceptable input patterns ('2:255', '1:1-7', '2:'), which clarifies the tool's behavior, but does not discuss return format or edge cases.

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-formed sentence that front-loads the purpose and immediately provides concrete syntax examples. It contains no filler and each part 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 tool's simplicity (one parameter, read-only, no output schema), the description is complete enough for an agent to invoke it correctly. It covers all supported input formats and clearly states the resource being fetched.

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 schema description coverage, the description fully compensates by explaining the one parameter's format and semantics. It clearly defines the three syntax forms with examples, making the regex pattern meaningful.

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 fetches verses using Quran range syntax, with specific examples covering single, range, and whole sura. This distinguishes it from sibling tools like get_verse (single verse) and search.

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 on when to use this tool: whenever a structured Quran range reference is provided. However, it does not explicitly mention alternatives or exclusions, such as using get_verse for a single verse or search for keyword queries.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns all 114 surahs (implying no pagination/filtering), but does not disclose additional behavioral details like ordering or performance.

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 that front-loads the main action (Return all 114 surahs) and then lists the returned fields. 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?

For a simple list tool with no parameters and no output schema, the description adequately specifies the return content. It could mention ordering (e.g., by surah number) but this is minor. Overall, it is nearly complete for its 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?

The tool has zero parameters, so the description carries no parameter burden. A baseline of 4 is appropriate; no further parameter clarification is possible or 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?

The description clearly states the tool returns all 114 surahs with a specific set of fields (id, names, verse count, juz list, page range). This distinguishes it from siblings like get_sura_info, which likely returns a single surah's details.

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 listing all surahs but does not explicitly mention when to use this over siblings like get_sura_info or search. It lacks explicit exclusions or alternative tool references.

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, idempotent, and non-destructive behavior. The description adds that the search uses Arabic normalization and lemma/root options, providing some extra behavioral context, but it does not detail output format, pagination, or other constraints. This adds some value but not rich behavioral disclosure.

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, front-loaded with the action and purpose. It contains no filler or redundant details, 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?

With five parameters, no output schema, and several sibling tools, this description is too terse. It fails to clarify the meaning of 'highlights', pagination behavior, or how the search relates to more specific tools like find_verses_by_lemma. The overall context leaves significant gaps for an agent to use 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?

The schema has 0% parameter description coverage, so the description must compensate. It only hints at the lemma and root boolean options, leaving query, page, and limit unexplained. This is insufficient for a tool with five parameters.

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 searches the Quran with specific options (Arabic normalization, lemma/root, highlights). It is a specific verb+resource, but it doesn't differentiate from sibling tools like find_verses_by_lemma or find_verses_by_root, which may offer overlapping functionality.

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

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

There is no guidance on when to use this tool versus its siblings, such as find_verses_by_lemma or get_verses_by_range. No context, exclusions, or alternative recommendations are provided.

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