Server Quality Checklist

Tool Scores

• search_fatwasA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral details: it returns ranked results with title, madhhab, source and URL, and explicitly says the full text requires a separate get_fatwa call. However, it does not mention pagination, sorting behavior, or any rate limits, so transparency is only partially enhanced 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.

  Conciseness5/5

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

  The description is two well-structured sentences, with the core purpose front-loaded and the usage guidance following. Every sentence earns its place, providing purpose, scope, result format, and a directive to the next step without any fluff or repetition.

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

  Completeness4/5

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

  For a search tool with an existing output schema and clear annotations, the description provides sufficient context: when to use, what results contain, and how to proceed (call get_fatwa). It omits any explanation of limit semantics or result ordering, but the schema covers limits and the output schema defines the return structure, so the description is adequate.

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

  Parameters3/5

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

  Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds value by giving an example query ('wiping over socks in wudu') and by explicitly pointing to list_sources when using the source parameter. Yet it does not explain parameter relationships or default behaviors beyond what the schema already states.

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

  Purpose4/5

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

  The description clearly states a specific action (search) on a specific resource (fatwas on IslamQA.org) and the scope (keyword or question). It also distinguishes itself from siblings like get_fatwa by noting that it returns summaries and that full answers require a follow-up call, though it doesn't explicitly contrast with browse_fatwas.

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

  Usage Guidelines4/5

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

  The description gives explicit guidance on when to use the tool ('whenever a question concerns Islamic rulings, fiqh, worship or practice and you want sourced scholarly answers rather than your own knowledge') and provides a clear trigger condition. It also hints at an alternative (using own knowledge) but does not explicitly mention when to use siblings like browse_fatwas, so a small gap remains.

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

• get_fatwaA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it discloses local caching after first read and the existence of a refresh parameter to bypass cache. 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.

  Conciseness5/5

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

  Two sentences with no fluff. The main purpose is front-loaded, and the caching/refresh detail is placed logically after. Every sentence earns its place.

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

  Completeness5/5

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

  With annotations covering safety and an output schema present (stated in context), the description covers the essential usage details: what it fetches, the source URL, and caching behavior. An agent can call it correctly without additional information.

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

  Parameters3/5

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

  Schema coverage is 100%, with both url and refresh already well-described in the schema. The description adds the note 'as returned by search_fatwas' for url and mentions caching for refresh, but both are also implied in the schema. Baseline 3 is appropriate since the description adds minimal extra meaning.

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

  Purpose5/5

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

  The description clearly states the tool fetches one full fatwa by URL and enumerates the specific content (question, answer, citations, issuing darul ifta, link). This is a specific verb+resource and distinguishes it from sibling tools like search_fatwas (search) and browse_fatwas (browse).

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

  Usage Guidelines4/5

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

  The description notes the URL comes from search_fatwas, which implies its usage context, and mentions caching behavior. However, it does not explicitly state when to prefer this over alternatives or provide when-not-to-use guidance. The context is clear but lacks explicit exclusions.

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

• index_statusA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is clearly a safe read operation. The description adds valuable context by specifying exactly what metrics are reported (number indexed, number in cache, last rebuild time), which goes beyond the annotations. It does not contradict the annotations and provides helpful detail about the tool's output.

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

  Conciseness5/5

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

  The description is a single, concise sentence that immediately states the core function. It is front-loaded with the action ('Report') and lists the three key metrics in a clear, organized manner. There is no redundancy or filler, making it highly efficient and well-structured.

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

  Completeness5/5

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

  Given the tool's simplicity (no parameters, no complex inputs) and the presence of an output schema, the description is complete. It explains what the tool reports without needing to describe return values (which are covered by the output schema). For a status-reporting tool with this straightforward scope, nothing essential is missing.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema is trivially 100% described. The description does not need to explain parameters, and the baseline for zero-parameter tools is 4. The description focuses on the output, which is appropriate given there are no inputs to clarify.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: reporting on fatwa index status, including counts and last rebuild time. It uses the specific verb 'report' with a clear resource 'index status', and it distinguishes itself from siblings like search_fatwas, list_sources, get_fatwa, and rebuild_index by focusing on status metrics rather than data retrieval or modification.

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

  Usage Guidelines3/5

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

  The description implies usage for checking index health and statistics, but it does not explicitly state when to use this tool versus alternatives. For instance, it doesn't mention 'use this before searching to ensure the index is up-to-date' or 'use this to diagnose why search results may be incomplete.' The purpose makes usage obvious, but there is no explicit guidance or mention of exclusions.

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

• rebuild_indexA
  4.4/5.0
  Behavior4/5

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

  Annotations (readOnlyHint: false, destructiveHint: false, openWorldHint: true) are already present, but the description adds concrete behavioral details: it takes ~1 minute and makes ~22 requests to an external site. This discloses side effects (network traffic, delay) beyond the annotations without contradicting them.

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

  Conciseness5/5

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

  Three efficient sentences: purpose, when-to-use, and cost. Every sentence adds value and the most important guidance (rarely needed) is front-loaded.

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

  Completeness5/5

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

  For a zero-parameter, side-effectful maintenance tool, the description covers purpose, usage context, behavior, and cost. The presence of an output schema further reduces the need to explain return values. Nothing essential is missing.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema already fully documents this aspect (coverage 100%). No parameter description is needed; the baseline of 4 applies since there's nothing to add.

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

  Purpose4/5

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

  The description states a specific verb ('Rebuild') and resource ('local URL index from islamqa.org's sitemap'), making the core function clear. It does not explicitly differentiate from siblings like index_status, but the uniqueness is implied given it's a one-off maintenance operation.

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

  Usage Guidelines5/5

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

  Explicitly says 'Rarely needed' and explains the index 'builds itself on first search and refreshes when stale.' This gives clear guidance on when NOT to call it and contrasts with automatic behavior. Also adds cost information (time, requests) that discourages casual use.

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

• browse_fatwasA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns the 'most recent' fatwas (ordering behavior) and mentions optional filters, which goes beyond annotations. It omits details like pagination, but that is standard and the bar is lower given 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.

  Conciseness5/5

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

  Two sentences, no filler. The first sentence delivers the core function, the second gives usage guidance. It is front-loaded and every sentence earns its place.

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

  Completeness5/5

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

  The tool has an output schema, so the return format is covered. Annotations handle safety. The description covers the purpose, filtering, and usage distinction. For a read-only browse tool with optional filters, nothing essential is missing.

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

  Parameters3/5

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

  Schema coverage is 100% with each parameter (limit, offset, source, madhhab) already described. The description only reiterates the madhhab and source filters ('optionally filtered to one madhhab or issuing source') without adding new semantics, so it adds marginal value 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.

  Purpose5/5

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

  The description states a specific verb ('List') and resource ('most recent fatwas'), and explicitly differentiates from the sibling search_fatwas by noting that browsing is for exploration while search is for specific questions. This makes the tool's purpose unambiguous.

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

  Usage Guidelines5/5

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

  It explicitly says 'For browsing; prefer search_fatwas to answer a specific question.' This gives clear when-to-use guidance and a direct alternative, which is exactly what the dimension asks for.

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

• list_sourcesA
  4.5/5.0
  Behavior4/5

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

  Annotations already cover readOnlyHint and destructiveHint, so the description adds value by disclosing that the list is exhaustive ('every'), grouped by madhhab, and includes answer counts. These are behavioral traits beyond the safety annotations.

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

  Conciseness5/5

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

  Two sentences with zero waste: the first states the core function, the second gives actionable usage guidance. The most important information is front-loaded.

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

  Completeness5/5

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

  An output schema exists, so return format details are unnecessary. The description covers purpose, scope, grouping, and ties to sibling usage, making it fully adequate for an agent to know when and why to call it.

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

  Parameters4/5

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

  The tool has zero parameters, and the schema coverage is 100%, so there is nothing to explain. The description correctly focuses on what the output provides (grouped list with counts), which still aids the agent in interpreting results.

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

  Purpose5/5

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

  States a specific verb (list) and resource (darul ifta indexed by IslamQA.org), with grouping and count detail. It also explicitly ties to searching for valid source values, distinguishing it from sibling tools like search_fatwas.

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

  Usage Guidelines4/5

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

  Gives clear, explicit use cases ('discover valid source values' and 'see how schools are represented') and implicitly positions it as a prerequisite to search_fatwas. It does not state when not to use it, but the purpose is sufficiently distinct from siblings.

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