Quran

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

Annotations already show readOnly, idempotent, non-destructive. Description adds detailed behavior: returns per-model object with score, confidence, signals, raw_response; explains that Anthropic requires BYO key and direct payment. 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?

Single paragraph, front-loaded with key action. Every sentence adds information: purpose, default model, optional model, return structure, use cases. 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?

Covers input, output format, and use cases. Lacks details on scoring methodology or error handling, but for a read-only probe tool with clear annotations, it's sufficiently 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?

All 4 parameters have schema descriptions (100% coverage). Description adds value: clarifies default model for 'models', explains '_apiKey' pass-through, gives examples for 'context'. Improves understanding 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?

Description clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100). Specific verb (probe), resource (LLMs), and output (score). Distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on direct LLM querying.

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 lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Explains when to use _apiKey (for Anthropic probing). Lacks explicit 'when not to use', but context is clear enough.

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 disclose readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about returning structured answers with stable citation URIs, which goes beyond annotations. It also implies non-destructive behavior. No contradictions; the description complements annotations well.

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 directive 'PREFER OVER WEB SEARCH', then provides domain examples and trigger words. It is efficient with no wasted sentences, though slightly lengthy due to comprehensive coverage. Overall, well-structured for quick comprehension.

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 (routing to thousands of tools), the description fully covers: purpose, when to use, input format, output type (structured with citations), and examples. No output schema exists, but the description adequately explains return value characteristics. Annotations provide safety context. Complete for an agent to use 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 all parameters described, including aliases. The description adds domain examples and illustrative trigger phrases, which enriches parameter semantics beyond the schema. While the schema already does heavy lifting, the description provides valuable context for crafting the question.

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 function: routing questions to the appropriate specialized tool among 3,436 tools, returning structured answers with citation URIs. It distinguishes itself from web search by explicitly stating 'PREFER OVER WEB SEARCH' and lists many domains, making the purpose specific and differentiating it from sibling tools.

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 guidance: for factual questions about current or historical data across numerous domains, and even lists trigger phrases like 'what is', 'look up', 'find', etc. It implies alternatives by contrasting with web search and provides concrete examples, enabling the agent to select this tool correctly.

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, idempotentHint=true, destructiveHint=false. The description goes far beyond: explains resolution process, fan-out, safety measures (low-confidence short-circuit, closed market detection), response shapes, and tradeability flags. 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?

Description is long but well-structured with sections, examples, and bullet points. Every sentence adds value. Could be more concise but the format aids readability.

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

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

No output schema, so description fully explains return values: result.market fields, result.analysis, result.evidence, resolver contract, parent event, news fields, and error/edge cases. Covers all scenarios and behaviors comprehensively.

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 adds context for the market parameter (slug, URL, or question text) but mostly reiterates schema details. No significant new meaning beyond what's in the input schema.

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

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

Clearly states the tool researches a specific Polymarket bet by pulling Pipeworx data. Distinct from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different aspects.

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 says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. Provides concrete examples. Does not mention when not to use or alternatives, but the use cases are 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 declare readOnlyHint, openWorldHint, idempotentHint, and not destructive. The description adds valuable behavioral details: for companies, it pulls from SEC EDGAR/XBRL, handles off-calendar fiscal years, and returns sorted data with citation URIs. 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 somewhat lengthy but front-loaded with key use cases. Every sentence provides necessary information; no redundancies. A minor improvement could be grouping related details, but overall it's 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 tool has only 2 parameters and no output schema, the description thoroughly covers usage triggers, entity types, data sources, sorting behavior, and citation URIs. It is complete for the tool's complexity and fully compensates for the lack of 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 schema already documents both parameters. The description adds meaning by explaining what each enum value does (e.g., 'company' pulls financial data, 'drug' pulls FAERS data) and specifying valid input formats (tickers/CIKs vs drug names), which enhances clarity 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 tool performs side-by-side comparison of 2–5 companies or drugs in one call, listing specific natural language triggers like 'X vs Y' and 'rank these companies'. It distinguishes itself from sequential single-pack lookups.

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 says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also specifies when to use 'company' vs 'drug' based on the type of entity, providing 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results include full input schemas with curated examples and are ready to call directly, aligning with annotations and providing 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 front-loaded with the purpose and includes a list of domains, which is informative but slightly lengthy. It is well-structured and clear.

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

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

Given no output schema, the description fully explains what the tool returns (names, descriptions, schemas, examples) and when to use it. It is complete for a discovery 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 100% with all 6 parameters described. The description mentions aliases for query but adds no significant meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description explicitly states 'Find tools by describing the data or task' and lists specific data domains. It clearly differentiates from sibling tools which are specific data tools, making it a general discovery 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?

The description advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It provides example queries, though it doesn't specify when not to use 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 indicate read-only, idempotent, non-destructive. Description adds rich behavioral context: fans out across multiple data sources (SEC, XBRL, USPTO, news, GLEIF) in one parallel call; mentions USPTO PatentsView API sunset (May 2025) soft-failing; describes news fallback from GDELT to GNews; specifies data returned (e.g., 'recent_filings up to 5' with URIs, 'fundamentals (LATEST 10-K...)'). 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?

Description is front-loaded with example queries and clear purpose. While somewhat lengthy, every sentence adds value (data sources, return fields, fallback behaviors). Could be slightly more concise, but structure is logical and no fluff.

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

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

Given the complexity (multiple data sources, fallbacks, no output schema), the description is impressively complete. It explains what each source returns and notes limitations (patents soft-fail, name unsupported). Missing exact structure of fundamentals but provides key fields (Revenues, NetIncomeLoss, Cash). Overall, highly informative for an agent.

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

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

Schema coverage is 100% with descriptive properties for both 'type' (enum 'company') and 'value' (ticker or CIK). The description reiterates these but adds the note about using resolve_entity for names, which is helpful but not essential beyond schema. Baseline 3 is appropriate as description adds marginal value beyond schema.

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

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

The description clearly states the tool's purpose: providing a holistic cross-source profile of US public companies. It uses specific verbs ('profile', 'brief me on') and lists return components like CIK, filings, fundamentals, patents, news, and LEI. It distinguishes itself from siblings by recommending preference over chaining single-pack lookups.

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

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

Explicitly tells when to use: when user asks for a holistic view of a company, prefer this over chaining individual lookups. Also specifies when not to use: names are not supported; instructs to use resolve_entity first if only a name is available. Provides example queries and input formats (ticker or CIK).

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 (destructiveHint=true, idempotentHint=true) are clear. Description adds value by mentioning 'clear sensitive data' but does not detail behavior on missing key (e.g., error vs. no-op). 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?

Two sentences, front-loaded with action, no wasted words. 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?

Simple tool with one param, ample annotations, no output schema. Description covers purpose, usage, and behavior comprehensively for a deletion 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 100%, with property description 'Memory key to delete'. Description does not add beyond schema, so baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key' – a specific verb and resource, distinguishing it from siblings like remember and recall.

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: when context is stale, task done, or clearing sensitive data. Also pairs with remember and recall for 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds value by detailing the fetch-and-extract process, but it does not disclose potential failure modes or limits beyond the max_links parameter.

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

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

The description is a single, well-structured paragraph that front-loads the purpose and provides all necessary information without redundancy. Every sentence contributes useful 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?

For a tool with no output schema, the description adequately explains the output as a text blob for site-root/llms.txt. It covers typical use cases but could mention error handling or edge cases for complete transparency.

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 clear descriptions for both parameters (url and max_links). The description adds an example for url but does not significantly enhance understanding 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 the tool generates an llms.txt file for AI crawlers, specifying the actions (fetches, extracts, emits) and the output format. It distinguishes itself from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on creating a standard file for indexing.

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 lists three concrete use cases, providing good context for when to use the tool. However, it does not explicitly mention when not to use it or directly reference alternative sibling tools, which would improve 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, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds that the tool returns verse text in the chosen edition, which is useful but not extensive behavioral detail beyond what annotations imply.

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, each serving a clear purpose. The first sentence defines the action and reference format. The second explains return value and edition options. No fluff.

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

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

Given no output schema, the description sufficiently explains that the return is verse text in the specified edition. It also notes global ayah number range (1-6236) which is helpful. Complete for a simple lookup 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 coverage is 100% (both parameters described), baseline 3. The description adds significant meaning with examples for reference (e.g., '2:255', '262'), explains edition default ('en.asad'), and clarifies that 'quran-uthmani' is for Arabic, going 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 gets a single ayah by reference, with specific examples (surah:ayah or global number). This distinguishes it from sibling tools like search_quran (search) and get_surah (entire 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 explains how to use the tool (by reference, with examples) and implies its specificity for single verses, but does not explicitly state when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns 'every ayah' which is slightly beyond annotations but does not disclose additional behavioral traits like rate limits or error handling. 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?

Two sentences: first sentence defines purpose and scope, second provides usage guidance. No unnecessary words, front-loaded with key information.

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

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

Given the tool's simplicity, schema coverage, and annotations, the description is complete. It covers what the tool does, what it returns, and how to use editions. Could mention potential large response size for long surahs, but not required.

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% with descriptions for both parameters. Description adds value by recommending concrete edition examples (en.asad, en.sahih, quran-uthmani) and explaining which to use for English vs Arabic, going beyond schema basics.

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

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

Clearly states verb 'Get', resource 'surah' (chapter of Quran), scope 'full text' and 'every ayah', and constraint 'by its number (1-114)'. Distinguishes from siblings like get_ayah and list_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?

Provides explicit guidance on which edition to use for English vs Arabic (e.g., en.asad, en.sahih, quran-uthmani). Implicitly indicates when to use this tool (need full surah text) but does not explicitly state alternatives or when not to use.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds value by specifying the exact fields returned (Arabic name, English name, etc.), confirming it is a safe list operation.

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?

Single sentence, front-loaded with the action and result, no fluff. 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?

For a parameterless list tool, the description fully specifies what is returned. It does not mention ordering or pagination, but 'list all 114' implies complete list. Adequate for the 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?

No parameters exist, so the description compensates by explaining the output fields. Baseline is 4 for zero parameters with 100% schema coverage; the description adds meaningful context.

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 'List all 114 surahs' with specific details (Arabic name, English name, etc.), effectively distinguishing it from siblings like get_surah (single surah) and get_ayah (verse-level).

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?

No explicit when-to-use or exclusion criteria, but the description implies use for a comprehensive list of surahs. Given no parameters and simple scope, the usage context is clear enough.

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?

Discloses rate limit (5 per identifier per day) and that the call doesn't count against quota. Notes that team reads digests daily. Annotations provide no additional behavioral info, so description fully covers transparency.

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?

Concise (~100 words) with no fluff. Front-loaded with purpose, then usage, then behavioral notes. 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?

Complete for a feedback tool: covers purpose, when to use, how to write feedback, behavioral constraints (rate limit, free), and impact (affects roadmap). No output schema needed.

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

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

Schema coverage is 100%, so baseline is 3. Description adds specific explanations for enum values (type) and guidance for message content (specific, 1-2 sentences, max 2000 chars). This enhances understanding 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?

Clearly states the tool is for giving feedback to Pipeworx team about bugs, missing features, data gaps, or praise. Specifies each feedback type, making 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?

Explicitly describes when to use each feedback type and provides guidance on how to write feedback (describe in terms of tools/packs, avoid pasting prompts). Also mentions rate limits and that it's free.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), output structure (pack, tool, count), and caching duration (5min-1h). 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 concise (four sentences) and well-structured: purpose, use cases, technical details. No filler sentences; 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?

With only one parameter and no output schema, the description fully covers the tool's behavior, use cases, and technical caveats. It is complete for an agent to understand when and how to use it.

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% for the single parameter 'window'. The description adds semantic guidance ('hot right now' vs 'steady-state demand') beyond the enum values, enriching the agent's understanding of parameter choice.

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 trending tools, packs, and call volume over a recent window, using specific verbs and resources. It distinguishes from siblings by focusing on aggregated usage data rather than individual queries or discovery.

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?

Three explicit use cases are provided (discovering hot data sources, confirming canonical tools, checking alignment). It also notes caching behavior. It lacks explicit 'when not to use' but the positive guidance is strong.

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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral context: monotonicity checks, partition sum deviation threshold (>3pp), Jaccard similarity (≥0.30), and placeholder filtering (>20% placeholder leads to null signal). 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 verbose with detailed algorithmic steps (e.g., Jaccard threshold, placeholder filter). While structured with headings like REQUIRES, SEMANTIC ANCHOR, PARTITION FILTER, it could be more concise. Every sentence adds value but the length may deter quick parsing.

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 (multiple modes, filters, output fields), the description is thorough. It explains prerequisites, mode-specific behavior, filtering criteria, and response structure. However, no output schema is provided, and the response structure is described only in text.

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 enriches each parameter: for 'event' it explains walking child markets, date-axis/threshold-axis ordering, and partition_check; for 'topic' it describes cross-event search, flattening markets, and similarity filtering. This adds meaning well 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 tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes two distinct modes (event and topic). This differentiates it from sibling tools like polymarket_edges or polymarket_kalshi_spread.

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 requires one of 'event' or 'topic' and warns that calling with no args fails. It recommends event for specific markets and topic for cross-event scanning with examples. However, it does not clearly state when NOT to use this tool or mention alternatives among siblings.

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 extensive behavioral details beyond annotations: edge calculations, Kelly fractions, slippage adjustments, segment grouping, diagnostics, cache duration. Annotations (readOnlyHint, etc.) are consistent with the description; 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?

The description is very long and detailed, but it is well-structured with sections for segments, knobs, and response shape. While every sentence is informative, it could be more concise without losing clarity.

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, lack of output schema, and rich annotations, the description covers nearly everything needed: output structure (by_segment), diagnostics, cache behavior, and edge methodology. It is self-contained enough for an agent to use 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?

All 9 parameters have descriptions in the input schema (100% coverage), so baseline is 3. The description adds some context on parameter interactions (e.g., min_liquidity and max_spread_pp for tradeable-edge) but does not significantly augment 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 the tool scans Polymarket for opportunities where Pipeworx data disagrees with market price, and specifies three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT). It distinguishes itself from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on Pipeworx's proprietary signals.

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 'what should I bet on today' and provides filtering knobs (min_liquidity, max_spread_pp, etc.) for when to use. It mentions Fed bets are excluded from ranking. It does not explicitly state when not to use this tool versus alternatives, but the purpose 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 already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds extensive behavioral context: response structure (leg-by-leg prices, spreads, safety fields), meaning of compatibility_warning in two cases, temporal_alignment, and skipped_cross counters. It explains that the tool does not create arbitrage but reports potential existence. 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 verbose, spanning multiple paragraphs with detailed explanations of response fields and edge cases. While front-loaded with the main purpose, it could be more concise by omitting repeated warnings. For an AI agent, a shorter, more structured description might be preferable, but the detail ensures clarity at the cost of brevity.

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 (cross-venue spread, two modes, safety fields, temporal alignment, skipped cross types), the description is very complete. It explains the response structure, caveats (compatibility_warning, temporal_alignment), and provides usage examples. No output schema exists, so the description carries full burden and meets it thoroughly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning beyond the schema by explaining the two modes ('topic' vs explicit), how explicit parameters override topic-mapped sides, and provides examples in the schema (e.g., 'fed', 'btc'). This clarifies parameter usage effectively.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies that it compares prices across venues and identifies spreads. It distinguishes itself from siblings like polymarket_arbitrage (likely intra-venue) and polymarket_edges (edge detection) by focusing on cross-venue comparisons.

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 explains two modes ('topic' and explicit parameters) and provides context on when spreads are meaningful (when bet shapes are equivalent). It warns that most pre-mapped topics return compatibility warnings, indicating limited true spreads. However, it doesn't explicitly state when not to use or list alternatives, though sibling tools imply this is the primary cross-venue tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context: scoping by identifier, ability to list all keys, and the relationship with other tools. 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 front-loaded with the main action, uses only three sentences, and every sentence adds value. No fluff or repetition.

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, so the description should explain the return format. It mentions retrieving a value or listing keys but does not specify the type or structure of the output (e.g., string, array). This is a notable gap.

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 already describes 'key' as optional string to retrieve or omit to list. The description reinforces this but does not add significantly 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 uses specific verbs 'Retrieve' and 'list' with clear resource 'values saved via remember'. It distinguishes itself from siblings 'remember' and 'forget' by stating the pairings.

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: to look up context stored earlier without re-deriving it. It also explains how to list all keys by omitting the argument, and pairs with 'remember' and 'forget' for complementary actions.

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, openWorldHint, idempotentHint true and destructiveHint false. The description adds significant behavioral context: fan-out to multiple sources (SEC, GDELT, GNews, USPTO), fallback behavior (GDELT→GNews), USPTO soft-fail, and output structure (grouped by source, citations). 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 fairly long but well-structured, starting with common queries, then explaining fan-out, parameters, output, and sibling reference. Every sentence adds value. It could be slightly more concise, but it's effective.

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

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

The description covers all three parameters, explains the multi-source fan-out, mentions limitations (USPTO soft-fail), and describes the output structure (grouped by source, total_changes count, citation URIs) despite no output schema. 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'since' parameter formats and recommending '30d' or '1m', and by giving examples for 'value' (ticker or CIK). This goes 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 the tool provides a change feed for a company over a time window, with example queries like 'What's new with X'. It distinguishes from sibling tool 'entity_profile' by specifying when to use each. The verb 'get' is implied and the resource 'change feed' is explicit.

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 vs 'entity_profile' for static profiles. It also recommends using '30d' or '1m' for typical monitoring. However, it does not explicitly state when not to use this tool beyond the alternative, which is a minor gap.

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 context about persistence (24-hour vs permanent), scoping by identifier, and idempotent hint is consistent; no annotation 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?

Concise, front-loaded with main purpose; could streamline slightly but still 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?

Covers usage, persistence, related tools; no output schema needed for this simple store operation.

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

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

Schema covers both parameters with descriptions, and description adds example keys 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?

Description clearly states the verb 'save' and resource 'data the agent will need to reuse later', distinguishing it from sibling tools like recall and forget.

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 says 'Use when you discover something worth carrying forward' and mentions pairing with recall/forget, but does not explicitly state when not to use.

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 significant behavioral context beyond the annotations (which already indicate read-only, idempotent, and non-destructive). It reveals that each call 'cascades through several lookup endpoints internally' and replaces '2-3 manual lookups,' informing the agent about efficiency and internal complexity. It also details return fields for each supported type, which is not present in 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 well-structured, starting with an attention-grabbing list of example queries, then stating the purpose, followed by usage, and finally detailed supported types. It is informative without being excessively verbose. However, it could be slightly more concise by merging repetitive elements, but overall it is effective and clear.

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 absence of an output schema, the description fully compensates by detailing the return values for each entity type (company: ticker, CIK, company_name, citation URI; drug: RxCUI, ingredient, brand, citation). It also explains that the tool replaces multiple manual lookups, providing a complete understanding of its behavior and output.

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 covers both parameters with short descriptions, but the tool description greatly enriches them. For the 'type' parameter, it explains the enum values in context (company vs. drug). For 'value,' it provides concrete examples (e.g., 'AAPL', '0000320193', 'ozempic') and clarifies that for company it accepts ticker, CIK, or name. This adds meaningful usage guidance beyond the schema's minimal 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 identifies the tool's purpose: resolving user-spoken names to canonical/official identifiers. It provides specific examples of queries ('What's the ticker for…') and explicitly states the supported entity types (company and drug) with their respective outputs. This specificity distinguishes it from sibling tools like 'entity_profile' or 'compare_entities'.

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 includes a clear usage directive: 'Use FIRST whenever you have a name but need an ID.' It elaborates with examples of when to use the tool (e.g., for ticker, CIK, RxCUI lookups). While it doesn't explicitly mention when not to use it, the context makes the primary use case obvious. The description could be improved by guiding away from using it when other tools like 'entity_profile' are more appropriate.

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, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing the return format ('ranked list with score, confidence, signal density per entity') and explaining that it probes each entity with ai_visibility_check and uses an optional API key. 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 concise with two well-structured sentences. The first sentence front-loads the core purpose ('Compare AI visibility across multiple entities side-by-side'), and the second provides details, usage context, and return value. 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 moderately complex tool with 4 parameters and no output schema, the description sufficiently covers what the tool does, how it works internally (probes with ai_visibility_check), and what it returns (ranked list with scores). This is complete given the annotations and schema richness.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds significant meaning beyond schema by noting that the first entity is treated as the 'subject' for narrative, explaining default models and the role of _apiKey. This clarifies usage beyond the parameter names and types.

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 explicitly states the verb 'Compare' and resource 'AI visibility across multiple entities side-by-side'. It distinguishes from sibling ai_visibility_check by describing itself as a composite tool that probes each entity and returns a ranked list.

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 a clear use case ('competitive AI-marketing audits') with an example question. It implies when to use this tool (multiple entities) vs. alternatives, but does not explicitly state when not to use it or name the alternative tool (ai_visibility_check) for single entities.

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, idempotentHint, and destructiveHint. Description adds valuable behavioral context: 'Partial failures degrade gracefully', bundlephobia first measurement can take 5-30s, and sources_failed lists timeout. This goes beyond annotations but could include more about rate limits or caching.

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 somewhat long but well-structured: starts with clear purpose, then enumerates data sources and return fields, usage guidance, ecosystem scope, and error behavior. Every sentence adds value, though it could be slightly more 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?

Despite no output schema, description fully explains return values: summary block with specific fields, per-advisory detail, links, and alternative versions. Also covers partial failure behavior. This makes the tool's complete behavior clear.

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 accurate descriptions for both 'package' and 'version'. Description repeats that scoped packages are accepted and version defaults to latest, adding minimal new meaning. 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?

Description clearly states the tool performs a composite npm package safety/popularity/size check integrating deps.dev and bundlephobia. It specifies the exact resource (npm package) and action (scan/check). Distinguishes itself from siblings by noting 'NPM ecosystem only in v1', setting 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?

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides when-not: for PyPI/Maven/Cargo/Go, 'fall under deps.dev:version directly'. This gives clear context and direction to 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 and idempotentHint. The description adds value by specifying the default edition, search limit of 30 results, and the possibility to search different editions, which goes beyond annotation data.

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

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

The description is concise, two sentences long, front-loaded with the action (search), and provides essential details without redundancy.

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

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

Given the tool's complexity (3 parameters, 1 required, no output schema), the description covers what the tool does, what it returns (verses with surah/ayah), and limits (up to 30). This is sufficient for an AI agent to use 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?

With 100% schema coverage, the schema already describes each parameter. The description adds clarity by stating 'keyword' is a word or phrase, 'edition' defaults to en.asad, and 'surah' can restrict to a number or 'all', enhancing understanding 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 tool searches the Quran for a keyword across verses, and specifies it returns matching verses with surah and ayah number. It distinguishes from sibling tools like get_ayah and get_surah by focusing on search 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?

The description provides context on default translation and the ability to change editions. While it does not explicitly state when not to use this tool versus siblings, the distinct purpose (search vs. specific retrieval) 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=true. The description adds value by detailing the return format (verdict types, structured form, actual value with citation, percent delta) and mentions it replaces 4-6 sequential calls, providing efficiency insight. 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 concise (5 sentences) and front-loaded with trigger phrases and purpose. Every sentence adds value—scope, usage, return info, and efficiency. No filler or 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 (1 parameter, schema 100% coverage, rich annotations), the description covers all necessary aspects: purpose, usage, return details, and limitations. It is fully sufficient for an agent to decide and invoke 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 single parameter 'claim' is already described in the input schema. The description adds examples and trigger phrases but does not significantly extend parameter semantics beyond the schema. Baseline 3 is appropriate given 100% 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 specific trigger phrases (e.g., 'Is it true that…', 'fact check') and clearly states the tool's purpose: natural-language claim verification. It distinguishes itself from sibling tools by specializing in company-financial claims for public US companies, making it unambiguous when to use this 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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and defines the scope (company-financial claims for public US companies). While it doesn't explicitly list alternatives or exclusions, the scope is clear enough to guide correct usage.

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