Quran

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: it probes multiple models, returns per-model {score, confidence, signals, raw_response} plus combined view, and notes that Anthropic calls require BYO key with direct payment. 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 two sentences, front-loaded with the main action, and efficiently covers purpose, scope, default behavior, and return structure without extraneous 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?

With 4 parameters, no output schema, the description adequately explains the return shape (per-model + combined view). It covers all essential aspects for an agent to understand what the tool does and what it returns.

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 parameters are well-documented. The description enhances by stating the default model (Workers AI Llama-3.3-70b free) and explaining that _apiKey is needed only for Anthropic. This adds value beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the verb 'probe' and 'score' and the resource (LLMs, brand/product/topic). It distinguishes itself from sibling tools like compare_entities and scan_competitor_ai_presence by focusing on visibility scoring across multiple models.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains the default model and when to provide _apiKey for Anthropic. It does not explicitly state when not to use, but the 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?

The description explains internal routing (5,564 tools, 1,462 sources), argument filling, and return of structured answers with citation URIs. It also notes it works on all tiers and is a single fast call. Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent with the description; 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 lengthy (several paragraphs) with many examples. While information-dense, it could be more concise and streamlined. The key messages are front-loaded, but the length reduces quick scanability.

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 sources), the description is remarkably complete. It covers purpose, usage, behavioral details, input expectations, and results. Without an output schema, it still explains the return format (structured answer with citation URIs).

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% (question parameter and aliases documented). The description adds value with many examples and context for what kinds of questions are appropriate, going beyond the schema's bare definition.

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 tool routes factual questions to authoritative sources, listing many domains (SEC filings, FDA, economic statistics, etc.). It clearly distinguishes itself from siblings by positioning as the default entry point and contrasting with ask_pipeworx_grounded and deep_research.

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: 'PREFER OVER WEB SEARCH', 'USE WHENEVER the user asks...', 'START HERE for most questions'. Also tells when to step up: use ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions. This is comprehensive and actionable.

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 discloses that the tool is identical to ask_pipeworx but may have experimental routing changes when active. It notes that no candidate is currently active and when the last one was retired. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, so the description adds useful context about the experimental nature and current state without contradicting annotations.

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

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

The description is concise (5 sentences) but packs essential information: identity, experimental purpose, current status, usage instruction, and fallback behavior. No redundant or filler content.

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 (universal router with many tools), annotations cover safety and behavior, and schema covers all parameters, the description provides sufficient context about the experimental nature and current state. It does not explain return shape, but annotations (openWorldHint) and the sibling 'ask_pipeworx' imply standard response. Minor gap: no mention of rate limits or auth, but not critical.

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

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

Schema coverage is 100%, and the description states the arguments are the same as ask_pipeworx. The description does not add new information about the parameters beyond confirming they match the stable version. Baseline of 3 is appropriate since the schema already documents all parameters and their aliases.

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

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

The description clearly states it is a 'beta version' of ask_pipeworx, an 'identical universal router' with the same tool set, arguments, and response shape. It specifies the current status (no active candidate, matches stable version) and the experimental purpose (testing routing improvements). This effectively distinguishes it from the sibling tool 'ask_pipeworx'.

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 tells the agent to 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains the value proposition (results compared against stable router for merges) and clarifies that it is a fully functional router, not a fallback. This provides clear guidance on when to choose this tool over its 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds valuable behavioral context beyond annotations: it is hallucination-resistant, uses only tool result data, returns explicit refusals with specific reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and specifies the return format. No contradiction with annotations.

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

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

The description is a single paragraph that efficiently packs the key information: purpose, mechanism, return format, use cases, tradeoff, and cost. Every sentence serves a purpose with no fluff. The structure front-loads the core idea and progressively adds detail.

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

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

Given there is no output schema, the description fully explains the return format (success: {answer, evidence, confidence, source, fetched_at, refusal_reason:null}; failure: explicit refusal with reason). It covers relationship with sibling tool 'ask_pipeworx', use cases, and limitations (extra LLM call). Combined with annotations, the agent has complete contextual information to select and invoke this tool correctly.

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

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

Schema description coverage is 100% (all 6 parameters are aliases for 'question' with description 'Your question in natural language.'). The description does not add new parameter information beyond what the schema already provides. The baseline for high coverage is 3, and the description does not elevate it further as it focuses on tool behavior rather than parameter details.

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

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

The description clearly defines the tool as a 'hallucination-resistant answer mode for high-stakes reads' and specifies its core mechanism: it picks the right tool, fetches data, and extracts answers using only tool result content. It explicitly distinguishes itself from the sibling 'ask_pipeworx' by mentioning the extra LLM call and the strict extraction logic.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also tells when to avoid it: 'prefer ask_pipeworx for casual lookups,' and explains the cost tradeoff of one extra LLM call.

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 goes far beyond annotations (readOnlyHint=true, etc.) by detailing resolution contract, parent event extractor, news fallback behavior, safety checks for low-confidence matches and closed markets, wide spread handling, and resolution-rule risk. No contradiction with annotations.

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

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

The description is lengthy but well-structured with clear section headings (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence adds necessary detail for such a complex tool, but it could be slightly more concise while maintaining completeness.

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 lacking an output schema, the description thoroughly explains response shapes, edge cases (low confidence, closed markets, wide spreads), and result fields. It covers all aspects of tool behavior and output, making it highly 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?

Schema coverage is 100% with descriptions for all three parameters. The description adds context on how the 'market' parameter accepts slug, URL, or question text, and explains the 'depth' default. This adds value beyond the schema, though not extensively.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and distinguishes from sibling tools like polymarket_arbitrage, polymarket_edges, etc., by being the comprehensive research 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?

Explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also provides fan-out examples for different bet types, making it clear when to use this tool versus alternatives.

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

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

Beyond the readOnlyHint annotation, the description details data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinicaltrials.gov for drugs), how fiscal years are handled, sorting by primary metric, and the inclusion of citation URIs. It also quantifies the efficiency gain (replaces 8-15 sequential lookups).

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 common trigger phrases, then the core action, then type-specific details, and finally the value proposition. While slightly long, every sentence adds essential information; no redundancy.

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

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

Given the tool's moderate complexity (two entity types, multiple metrics per type) and the lack of an output schema, the description covers data sources, sorting behavior, and output format (paired data + URIs). It is comprehensive enough for effective use, though it could optionally mention rate limits or error scenarios.

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 description adds significant context beyond the schema: it specifies that 'values' should be tickers/CIKs for companies and drug names for drugs, and explains what data fields are retrieved for each type. This helps the agent understand the expected input format and output semantics.

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 does side-by-side comparison of 2-5 companies or drugs in a single call, with explicit example queries and a strong distinction from sequential single-entity lookups (entity_profile). It leaves no ambiguity about the tool's function.

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 prefers this tool over sequential single-pack lookups when comparing entities, and provides concrete example triggers. However, it does not explicitly state when not to use it or mention alternative tools beyond the implied contrast.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds rich behavioral detail: parallelism (5,564 tools in parallel), hop field and citation_uri behavior, contradictions[] for standard/thorough, gap[] reporting for unanswered facets, semantic excerpting of large records, and timeouts. It explains the non-open-web nature and the structured catalog limitation, which is critical for agent expectations.

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 long but information-dense, with no fluff. It front-loads the critical sign-in requirement and fallback, then covers behavioral details. While longer than ideal, every sentence earns its place given the tool's complexity. A minor improvement would be shorter sentences in the middle.

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 high complexity (2 params, rich enum, no output schema but complex return described), the description is complete. It covers the return format (findings packet with evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop), error/edge-case behavior (empty gaps for uncataloged topics), and the semantic excerpting for large records. The absence of an output schema is compensated by this textual description.

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 depth enum semantics (how many facets, which hops, contradictions) beyond the schema's concise description, and clarifies that the question parameter should be natural language and multi-part. However, the schema already describes these adequately, so the incremental value is moderate.

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: grounded multi-source research across Pipeworx's structured data sources. It explicitly distinguishes deep_research from siblings like ask_pipeworx by contrasting parallel multi-tool decomposition vs. single LLM call, and against open-web search. The verb 'research' plus specific resource description ('1462 STRUCTURED data sources') and scope ('broad/multi-part questions') is unambiguous.

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

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

The description provides extensive usage guidance: account requirements (free vs. paid), fallback when unsigned-in (use ask_pipeworx), when to prefer ask_pipeworx (single lookup, BREAKING news, colloquial current events), depth level details with use cases (standard for gap recovery, thorough for chasing leads), and anticipated latency (15-90s). This covers both when to use and when to avoid the tool with named alternatives.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond by detailing the return format (top-N relevant tools with names, descriptions, and schemas) and the immediate usability of results, which is not covered by 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 purpose and usage, followed by domain examples and return details. It is efficient but slightly long; every sentence adds value.

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

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

Given 6 parameters, 100% schema coverage, and no output schema, the description thoroughly explains what is returned (names, descriptions, schemas with examples) and the purpose of the tool. No gaps remain.

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

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

Schema description coverage is 100% and the description does not add significant new meaning beyond listing aliases. It provides example queries but does not clarify syntax or behavior beyond what the schema already states.

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 ('Find tools by describing the data or task') and lists numerous concrete domains (SEC filings, FDA drugs, etc.), clearly distinguishing it from sibling tools that search for specific entities or perform analyses.

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear direction on when to use vs. alternatives. Also notes that results are ready to call directly, eliminating the need for separate schema lookups.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses that patents soft-fail until reactivated (USPTO PatentsView API sunset May 2025) and that the call is parallel, adding useful behavioral context. However, it does not detail latency or error scenarios.

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?

Front-loaded with example queries, then clear statement of purpose, detailed return fields, and usage guidance. Somewhat verbose but every sentence adds value; could be slightly tighter but overall efficient.

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

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

Despite no output schema, the description lists all return fields (cik, company_name, filings with URIs, fundamentals, patents, news, LEI) and explains the sources. Missing error behavior for invalid inputs, but adequate for agent use.

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?

Input schema covers 100% of parameters with descriptions. The description adds clarity by specifying that names are not supported and advising to use resolve_entity first, which adds value beyond 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 uses a specific verb-resource pairing ('full cross-source profile of a US public company') and provides example queries ('Tell me about X', 'research Acme'), clearly distinguishing it from sibling tools like resolve_entity and compare_entities by emphasizing holistic view over chaining individual 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 states when to use this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to use it ('names not supported — use resolve_entity first if you only have a name'), providing clear 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?

The description states 'Delete' which aligns with destructiveHint=true. Annotations already provide the destructive and idempotent hints, so the description adds value by explaining the purpose (clearing stale/sensitive data) but doesn't detail other behavioral traits like irreversibility. Still, it's consistent and informative.

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

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

Two sentences that are front-loaded with the action, then usage guidance. No wasted words. Every sentence contributes to 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?

With one parameter, full schema coverage, relevant annotations, and clear usage context, the description is complete. It explains what the tool does, when to use it, and how it relates to sibling tools.

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 fully documents the single 'key' parameter. The description mentions 'by key' but doesn't add new semantic meaning beyond what the schema provides. 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 action ('Delete'), the resource ('previously stored memory by key'), and provides context for when to use it. It explicitly distinguishes from siblings by mentioning paired tools '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?

The description provides explicit guidance on when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with 'remember' and 'recall', which helps agents select the correct 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 idempotent, read-only, and non-destructive behavior. Description adds context about fetching pages, extracting title/description/key links, and emitting standard markdown format, which supplements annotations without 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?

Four concise sentences front-loaded with action and output, each sentence adds value (purpose, process, output format, use cases). No waste.

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 tool with 2 parameters and no output schema, the description fully covers what the tool does, how it works, and when to use it, with annotations covering safety and idempotency.

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. Description does not add parameter-specific details 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?

Clearly states the tool generates a llms.txt file for any URL, with specific verb ('Generate') and resource ('llms.txt file'), and distinguishes from sibling tools by targeting a unique output format and use case.

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 use cases ('getting a client's site indexed', 'drafting for own project', 'auditing competitor') but does not mention when not to use or 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable context about return format (verse text in chosen edition) and mentions the Arabic option, which is beyond the schema.

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 purpose, includes a functional example. No filler or redundant text.

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

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

For a simple read operation with 2 parameters and no output schema, the description is adequate. It mentions return of verse text, but lacks details on error handling (e.g., invalid reference). However, the openWorldHint suggests resilience.

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%, but the description adds meaning by explaining the two reference types ('surah:ayah' vs. global number) and giving concrete examples. The edition parameter is clarified with default and Arabic option.

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 retrieves a single ayah by reference, specifying two reference formats (surah:ayah or global number) and the ability to choose an edition. This distinguishes it from siblings like get_surah (whole surah) and search_quran (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 explains how to use the tool (reference format, editions) and provides examples in the input schema. While it doesn't explicitly state when not to use it, the sibling tool list provides context for alternatives, and the openWorldHint annotation suggests it won't error on novel inputs.

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, and idempotentHint=true. The description adds that it returns every ayah in the chosen edition, providing additional context beyond the annotations without 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?

Three sentences front-load the purpose, then describe return value and edition guidance. Every sentence serves a purpose with 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?

Despite no output schema, the description fully explains what is returned (every ayah) and covers key aspects like surah range, edition options, and usage context, making it complete for a simple retrieval 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?

With 100% schema description coverage, baseline is 3. The description adds value by explaining edition examples and the default, plus clarifying that the output contains every ayah, which goes 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 gets the full text of a surah by number (1-114) and distinguishes itself from sibling tools like get_ayah (single verse) and list_surahs (list only) by emphasizing it returns every ayah.

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 guidance on which editions to use (English translations or Arabic), implicitly indicating when to use this tool over alternatives. It does not explicitly exclude other cases but offers clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds value by listing the specific fields returned (id, type, params, etc.) and noting the optional include_inactive parameter, which goes beyond the annotations.

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

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

The description is two sentences with no wasted words. The first sentence covers purpose and output, the second provides usage guidance. Ideal density.

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 one optional parameter and strong annotations, the description is mostly complete. It lists return fields and gives usage context. Lack of pagination or rate limit info is a minor omission, but not critical for this use case.

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 a description for the single parameter (include_inactive). The tool description does not add further parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, providing a specific verb and resource. It distinguishes itself from sibling tools like subscribe and unsubscribe by mentioning its use for reviewing monitoring and finding IDs to cancel.

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 tells when to use this tool: to review subscriptions before adding more or to find an ID to cancel. It implies when not to use (for subscribing/unsubscribing), but could be more explicit about alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds the context of what fields are returned, which is useful but not critical for behavioral understanding.

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 that conveys all essential information without any fluff. It is well-structured and easy to parse.

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 parameters and annotations covering safety, the description fully explains the tool's output, making it complete for an agent to understand its function.

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?

There are no parameters, so the description does not need to add parameter info. Baseline 4 is appropriate.

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

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

The description clearly states the tool lists all 114 surahs and specifies the exact fields returned (Arabic name, English name, translation, ayah count, revelation type). This distinguishes it from siblings like 'get_surah' which retrieves a single surah.

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

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

The description implies the tool is for listing all surahs, and sibling names like 'get_surah' and 'search_quran' suggest alternatives. However, it does not explicitly state when to use or not use this tool versus others.

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 are all false and provide minimal safety signals, so the description carries the burden. It discloses rate limiting (5 per day), that it is free and doesn't count against quota, the claim_token workflow, and that the team reads digests daily. This goes well beyond what annotations convey, with 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?

Although lengthy, every sentence earns its place: purpose, triggers, exclusions, formatting, claim_token flow, rate limit, and cost. The structure is front-loaded with the core action and logically proceeds to edge cases, so there is no waste.

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

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

With no output schema, the description explains what filing returns (a claim_token) and how to later use it to read status/resolution. It covers rate limits, account behavior, and the correct scope of feedback, making it complete for a tool with 4 parameters and nested objects.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already thoroughly documents each parameter, including the claim_token usage. The description reinforces the claim_token example but doesn't add new parameter-level meaning; it only adds contextual advice about message content.

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 starts with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates exact feedback types (bug, feature, data_gap, praise) and explicitly scopes the tool to tools served by this Pipeworx connection, distinguishing it from sibling tools like ask_pipeworx or discover_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 gives explicit 'Use when' triggers for each feedback type and an explicit exclusion ('if the tool came from a different MCP server... file it with that server instead'). It also provides formatting guidance ('don't paste the end-user's prompt') and explains the claim_token flow, making when-to-use and when-not-to-use unmistakably 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 safe read, idempotent, non-destructive. Description adds valuable context: derived from CF analytics, no PII, caching details. 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 concise paragraphs, front-loaded with purpose, then use cases, then technical details. 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?

Despite no output schema, description explains return structure (tools, packs, count) and caching. Sufficient for a simple single-parameter 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 covers the parameter 'window' fully with enum and description. Description reinforces purpose but adds minimal new meaning. 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?

Clearly states it returns trending tool/pack usage and total call volume. Differentiates from sibling tools like discover_tools by focusing on aggregated popularity rather than individual tool 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?

Provides three explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case). Could further clarify when not to use (e.g., when needing specific tool search), but still 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?

Discloses internal behaviors like semantic anchor (Jaccard ≥0.30), partition filter (placeholder slugs), and fill check (realizable vs theoretical edge). Annotations declare readOnlyHint=true, and the description aligns with that, adding rich context beyond annotations.

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

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

The description is long but every sentence adds value for a complex tool. It is front-loaded with purpose and modes, then details secondary checks. Could be slightly more structured with bullet points, but still highly 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?

Despite no output schema, the description fully explains the response structure: opportunities array with fields and partition_check details. It also covers edge cases (placeholders, fill checks) making it complete 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?

Schema has two optional parameters with basic descriptions. The description adds extensive meaning: explains how each parameter works, expected inputs (slugs, URLs, seed questions), and the effect on the scan (e.g., partition check vs cross-event).

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three call modes (no args, event, topic) and explains what each does, differentiating it from siblings like polymarket_edges.

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 guides when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Also gives 'do not trade' advice when fill check shows negative edge, preventing misuse.

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. The description adds extensive behavioral context: caching, segment grouping, edge calculation details, diagnostics, and Fed bet exclusion. 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 long (approx 300 words) but front-loaded with main purpose. Every sentence serves a purpose, but it's dense and could be more concise. Well-structured but not 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?

No output schema, but the description details the response structure (by_segment, fed_candidates, _diagnostics) and covers how to interpret results. Given complexity (9 params, multiple model families), the description is comprehensive.

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

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

Schema has 100% coverage with descriptions for all 9 parameters. The description adds meaningful extra context for several parameters (e.g., slippage_pp explains Polymarket fees, min_partition_leg_kelly explains special behavior). Baseline 3 + extra value.

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, distinguishing it from sibling tools like polymarket_arbitrage by focusing on edge detection across multiple model families.

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 'Built for "what should I bet on today"' and describes knobs for filtering, but does not explicitly state when not to use or compare to alternatives like polymarket_arbitrage. It provides clear context but no 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 description discloses behavioral details beyond annotations: it explains the output structure (tracked[], expired[], snapshot_dates[]), the decay computation method, sign conventions, and limitations like snapshot gaps and TTL. Annotations (readOnlyHint, openWorldHint, idempotentHint) are fully consistent with the description.

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

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

The description is a single paragraph of dense, information-rich sentences. It efficiently conveys purpose, output structure, and limitations. While clear, it could benefit from bullet points or section breaks for easier 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 no output schema, the description fully explains the return fields (tracked, expired, snapshot_dates) with their subfields and meanings. It also covers computational details and limitations. The tool is well-documented for a simple two-parameter function.

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 (days, window) with descriptions. The tool description adds context: default values, allowed ranges, and examples for window family values. This adds meaningful guidance beyond the schema, especially for window which lists possible values not in 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question 'how long has this edge existed and is it shrinking?' This purpose is distinct from sibling tools like polymarket_edges, which likely provides current edges.

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

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

The description implies when to use the tool by contrasting a fresh wide edge with a 3-week-old wide edge, indicating this tool is for assessing edge maturity. It also mentions limits such as the 60-day TTL and snapshot start date. However, it does not explicitly state when not to use or list alternative tools for other contexts.

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, idempotentHint, openWorldHint, destructiveHint. Description adds behavioral context: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains consequences of partial fills. Adds value beyond annotations.

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

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

Description is long with multiple paragraphs and detailed technical output lists. Front-loaded with key purpose but could be tightened. Complexity justifies density, but some redundancy exists (e.g., repeating mode 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?

No output schema, so description must explain returns. Lists all returned fields for both modes comprehensively. Includes edge cases (thin_legs, forced_directional_risk). Complete for a complex tool with two modes.

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

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

Schema description coverage is 100%, baseline 3. Description adds clarifying context: for 'side', explains default behavior in basket mode (auto from partition sum); for 'market' and 'event', clarifies mode assignment; for 'size_usd', adds clamp range and interpretation. Adds meaning 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 states a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes and names outputs. It also differentiates from siblings like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-check.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Provides reasoning: theoretical overround on thin books is not capturable and partial basket fills convert arb into directional position, which is the dominant loss mode.

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 provides extensive behavioral details beyond annotations, including two modes, compatibility warnings, temporal alignment, skipped cross types, and the rarity of real spreads. It adds significant context not covered by readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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 (240 words) but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every sentence adds value, though slight trimming could improve conciseness.

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 of the tool (3 params, 2 modes, no output schema), the description covers response structure (leg-by-leg prices, spread array, top_spreads_pp, safety fields) and edge cases thoroughly, making it complete for an agent to understand 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?

The input schema covers all three parameters with descriptions (100% coverage), so baseline is 3. The description adds value by listing the topic shortcuts explicitly and explaining how explicit tickers override topic-mapped sides, improving 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?

The description clearly states the tool calculates cross-venue spreads between Kalshi and Polymarket for the same resolving question. It uses specific verbs like 'provide' and details two modes, distinguishing it from siblings like polymarket_arbitrage by specifying the cross-venue nature.

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 outlines two usage modes (topic shortcuts and explicit tickers) and warns that pre-mapped topics often yield compatibility warnings, guiding agents on when spreads are meaningful. It lacks explicit 'when not to use' guidance, but the context is clear.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable context about scoping to an identifier and relationships with sibling tools, which goes 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.

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

The description is concise with four sentences, front-loaded with the core action. Every sentence adds useful information (usage, scoping, pairing) without unnecessary detail.

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

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

Given the tool has only one optional parameter, no output schema, and comprehensive annotations, the description fully covers behavior, scope, and relationships with siblings. No gaps in understanding remain.

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 optional parameter, and the schema description already explains that omitting the key lists all keys. The description mirrors this but does not add new information beyond what the schema provides, meeting the baseline expectation.

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 retrieves a value saved via 'remember' or lists all keys. It uses specific verbs ('retrieve', 'list') and identifies the resource (saved values/keys), distinguishing it from sibling tools like 'remember' 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?

The description explains when to use the tool (to look up stored context) and provides context about scoping and pairing with 'remember' and 'forget'. However, it does not explicitly mention situations where it should not be used, though the guidance is clear overall.

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, idempotentHint, destructiveHint false. The description adds behavioral context: mark_read mutates read status, returned events include specific fields, and polling is safe. 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 a single dense paragraph with no fluff. Front-loaded with main purpose, each sentence adds value (return fields, filtering, side effects, alternative access).

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 tool complexity (read-only, 5 optional params, no output schema), description covers purpose, return fields, filtering, side effect of mark_read, and even includes an alternative access mechanism. Very 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?

Schema coverage is 100%, baseline 3. Description adds semantic value: example type 'sec_8k', clarifies since expects ISO timestamp, explains mark_read effect. Does not mention limit or unread_only, but schema descriptions suffice.

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 'Pull fired events from your subscription feed' with specific verb and resource. It enumerates returned fields (source, citation_uri, raw payload) and distinguishes from siblings by providing an alternative HTTP endpoint for scripts/dashboards.

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?

Guidance is given on filtering (type, since), setting mark_read, and polling suitability. However, it does not explicitly state when NOT to use this tool versus sibling tools like list_subscriptions or subscribe.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds valuable context: it fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO (with soft-fail note). This goes beyond what annotations provide.

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

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

The description is well-structured: it starts with concrete example queries, then states the core function, then details sources and parameter format, and ends with an alternative tool. Every sentence contributes meaning 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?

The description covers all key aspects: source fan-out, fallback behavior, parameter acceptance, return structure (changes[], total_changes, citation URIs), and a pointer to an alternative tool. No output schema exists, but the description compensates adequately.

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%—all parameters have descriptions. The description further clarifies the `since` parameter format with examples (ISO date and relative shorthand). This adds value beyond the schema, especially for usage guidance.

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

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

The description clearly states the tool's purpose as a change feed for a company in a recent time window, with examples ('What's new with X', 'latest on Y'). It also distinguishes itself from entity_profile, which focuses on static profiles.

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 indicates when to use this tool (for recent changes) and provides an alternative ('Use entity_profile instead when you want the static profile'). It also explains the underlying fan-out behavior and fallback logic.

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

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

Adds behavioral context beyond annotations: storage scoped by identifier, persistence difference for authenticated vs anonymous users. Annotations already indicate idempotent and non-destructive. 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?

Four concise sentences, front-loaded with main purpose. No wasted words. 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?

Complete for a simple key-value store tool. Covers when to use, how it works, pairing with other tools. No output schema needed. All relevant context provided.

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 already describes both parameters (100% coverage). Description adds example key patterns and value types, adding meaning 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?

Description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the resource (key-value memory) and the verb (save). It distinguishes from siblings 'recall' and 'forget' by mentioning them.

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 when to use: 'when you discover something worth carrying forward'. Provides examples. Mentions alternatives: 'Pair with recall to retrieve later, forget to delete'. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive hints. The description adds substantial behavioral context: source-labelled identifiers, explicit `unresolved` handling, graceful degradation of LEI/FIGI if upstream services fail, and internal cascading lookups. No contradiction with annotations.

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

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

The description is long, but every sentence carries valuable information. It is front-loaded with examples and supported types, then explains edge cases. Though dense, it avoids fluff while remaining 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's complexity (multiple entity types, multiple ID systems, fallback behavior) and lack of an output schema, the description is thorough. It covers return values, source attribution, unresolved identifiers, and degradation behavior. No critical missing pieces.

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 100% of parameters, but the description enriches semantics: it clarifies accepted input formats for `value` (ticker, CIK, ISIN, name), explains ISIN-to-LEI resolution behavior, and gives concrete examples for both types. This goes well beyond the schema's brief 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 resolves a user-spoken name to canonical/official identifiers, with specific verbs ('resolve') and resources ('entity identifiers'). It provides diverse examples (ticker, CIK, LEI, RxCUI) and explicitly distinguishes its purpose from other tools by positioning it as the prerequisite for ID-requiring 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?

It gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains supported types and input formats. However, it does not name alternative tools or state when not to use this tool, leaving some room for interpretation.

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, idempotentHint, openWorldHint, and non-destructive. The description adds context: calls ai_visibility_check internally, ranks by score, returns confidence and signal density. 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?

Three sentences, front-loaded with the core action (compare side-by-side), no redundant words. Every sentence serves a purpose: purpose, method, use case, output.

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 purpose, usage, parameter hints, and output format (ranked list with score, confidence, signal density). Lacks edge case guidance (e.g., what if entities are not recognized) but overall sufficient for a comparison tool with no 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%, and the description adds meaning beyond the schema: explains entities array first entry is the subject, models default to workers-ai if omitted, _apiKey only needed for anthropic, context disambiguates names. Slight deduction for not fully elaborating on all parameter constraints.

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 compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check and ranking results. It distinguishes from sibling tools like ai_visibility_check by focusing on competitive comparison.

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 it's useful for competitive AI-marketing audits and gives an example query. Implicitly contrasts with single-entity checking (ai_visibility_check) by noting it probes multiple 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?

Beyond annotations (readOnly, idempotent), the description discloses performance behaviors (bundlephobia's first measurement taking 5-30s), partial failure degradation (sources_failed listed on timeout), and the specific fields returned, offering complete behavioral context.

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

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

The description is a single paragraph that is front-loaded with the core purpose and covers all necessary details. While thorough, it is slightly dense but not excessively long; 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?

Given no output schema, the description fully details the return value (summary block, per-advisory detail, links, alternative versions) and explains partial failures and ecosystem limits. This makes the tool fully understandable 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%, so baseline is 3. The description adds value by clarifying ecosystem restriction ('NPM ecosystem only in v1') and explaining how parameters are used in the composite calls, which is meaningful beyond 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's purpose as a composite check for evaluating npm packages by fanning out across deps.dev and bundlephobia. It specifies what it returns and distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on npm packages.

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 an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes that other ecosystems (PyPI, Maven, etc.) are not covered, providing clear when-to-use and when-not-to-use 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?

The description adds behavioral context beyond annotations: it reveals the default English translation (en.asad), the ability to search other editions (including Arabic), and a result limit of 30 verses. This supplements 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 two sentences, front-loading the core purpose and return format. The second sentence concisely adds the default translation and the option to search other editions. No unnecessary words.

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

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

Given no output schema, the description adequately describes the result structure (verses with surah and ayah numbers) and the result limit. It covers the three parameters and their defaults. It is complete for a search tool, though it omits error scenarios or empty results.

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 all three parameters, but the description adds value by explaining the default for the 'edition' parameter and mentioning that passing 'quran-uthmani' searches Arabic. It also clarifies that results include surah and ayah numbers, which is not in 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 verb 'Search', the resource 'the Quran', and the scope 'across ayahs (verses)'. It also specifies the return format with surah and ayah numbers. This distinguishes it from sibling tools like get_ayah and get_surah, which retrieve specific items.

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 keyword searching across the Quran, but it does not explicitly state when to use this tool versus alternatives. It mentions default edition and result limits, but lacks guidance on when not to use it or how it compares to 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?

Beyond annotations (readOnly, idempotent, openWorld), the description reveals the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character cap (200K chars with truncation flag), and output properties (offsets, similarity scores). No contradiction with annotations.

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

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

The description is a single paragraph that is dense with information but not verbose. Every sentence adds value: function, use case, pairing, technical details, and limitations. No wasted words.

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

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

Given no output schema, the description adequately covers return values (passages, offsets, similarity scores), technical behavior (chunking, embeddings), and limitations. It also references a sibling tool for grounding. 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?

Input schema has 100% coverage with descriptions for text, query, and limit. The description adds value by clarifying the text size limit, providing query examples, and specifying limit range and default.

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 semantic search inside a fetched record, returning passages with offsets and scores. It distinguishes itself from siblings by specifying the context ('inside a fetched record') and provides concrete examples (SEC 10-K body, article).

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 advises using this tool when a record is too large for the prompt, and it pairs with ask_pipeworx_grounded. While it doesn't explicitly list alternatives or when not to use, the guidance is clear and actionable.

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

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

Beyond annotations, the description details authentication needs, type-specific behavior, delivery channels with constraints (e.g., SMS 10/day cap, webhook auto-disable), and return value. No contradiction with annotations.

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

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

The description is information-dense but slightly long. It is front-loaded with the main purpose. Every sentence adds value, though a more structured format could improve 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?

Given the tool's complexity and lack of output schema, the description covers all usage aspects: required parameters, type-specific params, delivery options, constraints, and return value. No gaps remain.

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 description adds rich examples and behavioral context for each parameter, significantly exceeding the schema's descriptions. For instance, it explains the 'items' field for sec_8k and HMAC signing for webhook.

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 creates a proactive monitoring subscription, with specific verb 'Create' and resource 'subscription'. It distinguishes from sibling tools like unsubscribe by focusing on creation.

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, including authentication requirements and supported types, but does not explicitly contrast with alternatives. However, the purpose is clear enough for correct usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description builds on this by detailing that the tool returns 'category-bucketed example questions' with 'exact tool + argument shape' drawn from a live catalog. 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 every sentence adds value: it includes example queries, explains the output format, and gives usage guidance. The list of categories is long but informative. It is well-structured with a clear flow from purpose to usage to output.

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 simplicity of the tool (one optional parameter, no output schema), the description is highly complete. It covers what the tool does, when to use it, how to use it, and what the output contains. No additional context is 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%, but the description adds significant meaning beyond the schema: it explains the purpose of the optional topic parameter, lists example values (finance, pharma, etc.), and clarifies behavior when the parameter is omitted ('full spread'). The description fully compensates for the schema's minimal description.

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

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

The description clearly states the tool's purpose as the onboarding entry point that returns category-bucketed example questions. It distinguishes from sibling tools by explicitly noting it should be used first to learn how to call meta-tools like ask_pipeworx and entity_profile.

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 explicit usage instructions: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains the two modes (no arguments for full spread, or topic to focus). While it doesn't explicitly state when not to use, the guidance is clear and includes alternative suggestions.

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 that the row is deactivated (not deleted) and historical events remain via recent_alerts, going beyond annotations (readOnlyHint=false, destructiveHint=false) to explain the actual behavior. 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?

Three sentences, each serving a distinct purpose: action, ownership constraint, and deactivation detail. No unnecessary words.

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

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

Given the tool's simplicity (one required param, no output schema), the description fully covers behavior, ownership, side effects, and impact on historical data. No gaps.

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

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

Only one parameter (id) with schema coverage 100%. Description adds no extra info beyond the schema's description ('Subscription id (uuid) returned by subscribe'). Baseline 3 is appropriate as schema already covers the parameter adequately.

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 starts with 'Cancel a subscription by id,' which clearly specifies the verb ('cancel') and resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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?

States 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear context for when to use the tool (own subscriptions) and implying it should not be used for others' subscriptions. Does not explicitly name alternatives but offers sufficient 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?

The description adds substantial behavioral context beyond the annotations: it explains that could_not_verify means the check did not happen and carries verification_error, and distinctions between could_not_verify and unsupported. It also describes the two-pipeline routing and the tolerance_pct behavior with hallucination detection examples. This is thorough and does not contradict the readOnly/idempotent 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 longer than average but every sentence carries informational weight. It front-loads with trigger phrases and a clear purpose, then efficiently covers the routing, return values, and edge cases. It is well-structured and not redundant, though it could be tightened without losing important 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?

Given the tool's moderate complexity and lack of an output schema, the description fully covers the return values (verdict types, citation, reasoning), error semantics (could_not_verify vs unsupported), and parameter usage nuances. It also explains the internal routing and the performance benefit, making it complete enough for an agent to select 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 schema covers 100% of parameters, so the baseline is 3. The description adds meaning beyond the schema by explaining tolerance_pct's override purpose ("set 1–2 for hallucination detection") and its default behavior ("implied by wording, capped at 5"). It also provides realistic claim examples, adding value for the claim 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 explicitly states a specific verb and resource: "natural-language claim verification against authoritative sources." It provides trigger phrases and clearly distinguishes itself from siblings by describing the structured SEC EDGAR path for financial claims and the grounded pipeline for other claims, plus the note that it replaces 4–6 sequential calls.

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 says "Use whenever the agent needs to check whether something a user said is factually correct," which gives clear context for when to use it. It also explains the two routing paths based on claim type, but it does not explicitly name alternative tools or state when not to use it, so it misses the 'when-not' and 'alternatives' element.

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