Cpsc

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

Annotations already indicate read-only/idempotent behavior; the description adds valuable context about cost (BYO Anthropic key, paid directly) and default model choice, which goes beyond the structured annotations. No contradiction is present, and the external API interaction is openly disclosed.

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 three sentences, front-loaded with the core action, and every sentence contributes distinct information: action/scope, model options/cost, and output/use cases. No wasted words.

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

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

Although there is no output schema, the description explicitly lists the return shape ({score, confidence, signals, raw_response} + combined view). It covers inputs, defaults, cost, and use cases, giving the agent enough context to invoke the tool correctly without needing additional details.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances this by explaining the default model (Workers AI Llama-3.3-70b), clarifying that `_apiKey` is only needed for Anthropic, and implying the behavior of the `models` parameter. This adds practical 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?

The description uses a specific verb ('probe') and resource ('LLMs'), and clearly defines the output (visibility score 0-100). It distinguishes itself from sibling tools like ask_pipeworx or scan_competitor_ai_presence by focusing on AI knowledge scoring rather than general Q&A or competitor scanning.

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 cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) which indicate when to use it. However, it does not explicitly name alternative tools or mention when not to use it, so it stops short of a full 5.

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

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

Annotations already declare readOnly=true, openWorld=true, idempotent=true, destructive=false. The description adds valuable behavioral context: it routes to 5,529 tools, fills arguments, returns stable citation URIs, works on every tier, and is fast. This goes beyond the structured annotations without contradicting them, though it doesn't disclose failure modes or cost/limits.

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 longer than ideal but every sentence adds value: positioning, trigger phrases, examples, rollout logic, and alternatives. It is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and organized with clear 'when to use' and 'when to step up' segments. A bit verbose but not wasteful.

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 (general-purpose router to thousands of sources), the description covers inputs, usage, outputs (citation URIs), and alternative escalation paths. It lacks explicit failure scenarios or response format structure, but no output schema exists, so the description carries the burden. It is sufficiently complete for an agent to select and invoke properly.

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's 100% coverage already documents all six parameters as aliases for 'question'. The description enriches this by explicitly stating it accepts natural language and listing all aliases (query, q, prompt, text, input), which is not obvious from the schema alone. It also provides three varied examples.

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 specifies a precise verb ('routes to the right one of 5,529 tools') and resource ('authoritative structured data with citations'), clearly distinguishing it from siblings like ask_pipeworx_grounded and deep_research. It states the tool answers factual questions via a routing mechanism and names the domains it covers.

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

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

Explicitly instructs to prefer over web search, lists trigger phrases ('what is', 'look up', 'find'), provides concrete examples, states 'START HERE for most questions', and explains when to step up to ask_pipeworx_grounded or deep_research. Also clarifies how it handles breaking news, covering 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value beyond these by disclosing the current state (no active candidate, matches ask_pipeworx exactly) and that it is an experimental edge with routing improvements compared against the stable router. This contextualizes behavior well.

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

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

The description is a compact paragraph of four sentences, each conveying a distinct and necessary fact: identity, current state, usage, and non-fallback status. It is front-loaded with the beta identity and efficiently packs context without unnecessary fluff, though slightly longer than the ideal two-sentence version.

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 states the response shape matches ask_pipeworx, leveraging sibling knowledge to cover return values. It also covers identity, current behavior, usage instructions, and experimental status. Some familiarity with ask_pipeworx is assumed, but for a beta variant, this is suitably 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?

The schema fully documents all six parameters (question plus five aliases) with 100% coverage, so the description need not repeat them. The phrase 'same arguments' references ask_pipeworx but does not add new semantic detail beyond what the schema already provides, keeping the baseline at 3.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from siblings by emphasizing the experimental edge and candidate routing improvements, making its purpose unambiguous.

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

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

The description explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and that results are compared against the stable router, providing clear when-to-use guidance. It also clarifies it is a full working router, not a fallback. It does not explicitly list when not to use it, but the experimental nature implies a stability trade-off.

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

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

The description adds significant behavioral detail beyond annotations: it explains the refusal reason enum, evidence extraction, and the constraint 'using ONLY what the tool result contains.' It also discloses the extra LLM call cost, which is not visible in annotations. No contradiction with readOnlyHint/openWorldHint.

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 appropriately sized and front-loaded: it opens with the core purpose, then provides return/refusal behavior, and ends with when-to-use guidance. Every sentence adds value, and the structure is logical and scannable.

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

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

Despite having no output schema, the description fully explains return values ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and all refusal modes. It covers cost, use cases, and the routing mechanism, making it complete for a complex grounded-answer tool.

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

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

Schema description coverage is 100% (all 6 parameters are aliases for 'question'), so the schema already documents parameter semantics. The description adds that the tool accepts natural language and routes to tools, but does not need to explain parameter formats further; baseline 3 applies.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb ('extracts the answer') and resource (Pipeworx tool routing). It distinguishes itself from sibling ask_pipeworx by emphasizing evidence grounding and refusal behavior, so the agent can differentiate between similar 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?

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also notes the extra LLM call cost, helping the agent choose between grounded and ungrounded variants.

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 well beyond the readOnly/openWorld/idempotent annotations. It discloses parallel fan-out behavior, status codes (low_confidence_match, market_closed_or_inactive), suppression of analysis on low confidence, wide-spread illiquidity, cancellation-rule parsing, and GDELT fallback behavior. These are critical behavioral traits not available in the annotations or 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?

The description is heavily detailed, with many sentences covering classifiers, fan-out examples, response shapes, safety rules, and cancellation rules. It is well-structured with all-caps section labels and front-loaded with a purpose sentence, but it is very long. Not every sentence is strictly necessary (e.g., the null-explanation for cancellation_rule), making it verbose rather than 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?

There is no output schema, so the description must explain return values, and it does thoroughly: result.market, result.analysis, result.evidence, market_match_confidence, parent_event, news fields, and statuses. It also covers failure modes, safety short-circuits, and resolution-rule risks. This is a complete behavioral contract for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema: it repeats that market accepts slug/URL/question text, but does not explain depth or include_raw beyond what the schema already says. It provides examples, but these are also in the schema. Thus it neither compensates for gaps nor adds new semantic value beyond the baseline.

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

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

The description opens with a specific verb+resource combination: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains the tool's purpose, including fan-out, evidence packet, and market-vs-model comparison. This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on narrower 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?

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides clear context and also includes safety guidance about inspecting match confidence. However, it does not mention when not to use it or name alternatives explicitly, so it falls short of a 5.

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 meaningful behavioral context beyond annotations: per-type data sources (SEC EDGAR/XBRL vs FAERS/FDA), handling of off-calendar fiscal years, sorted results by primary metric, and citation URIs. No contradiction with 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?

Front-loaded with trigger examples and well organized by type, but slightly redundant: 'ALWAYS PREFER over sequential single-pack lookups' is restated as 'Replaces 8–15 sequential lookups.' Otherwise every sentence earns its place.

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

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

Given no output schema, the description adequately covers inputs, data sources, sorting, return format (paired data + URIs), and entity-type behavior. It is 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?

Schema provides enum and array descriptions, but the description adds critical semantics: what metrics each 'type' pulls, example values (AAPL/MSFT, ozempic/mounjaro), and max count of 5. This substantially enriches the 2 parameters.

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

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

States specific verb and resource: side-by-side comparison of 2–5 companies or drugs in one call. Trigger phrases ('X vs Y', 'which is bigger', 'rank these companies') make intent unambiguous and distinguish it from single-entity sibling tools.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists exact user queries that should trigger this tool. It establishes when to use it and discourages the alternative sequential approach.

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 is exceptionally transparent about behavior: it details parallel tool routing, the findings packet structure (verbatim evidence, confidence, source, fetched_at, citations, gaps[]), the contradictions[] for standard/thorough depths, second-hop iteration behavior, semantic excerpting, timing expectations, and the paid plan requirement for 'thorough.' This goes far beyond the annotations, which only provide readOnly/openWorld/idempotent hints.

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 well-structured, front-loading account requirements and core purpose, then usage guidance, depth semantics, and output details. Every sentence adds value, but it could be slightly tighter; the inclusion of specific examples and URLs increases length without sacrificing clarity.

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

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

Given the tool's complexity (no output schema, multiple depth modes, complex return packet), the description is remarkably complete. It explains the return format, timing (15-90s), how citations are fetchable, contradictions scanning, and gap recovery, ensuring an agent has enough context to invoke and interpret 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?

Schema coverage is 100%, but the description adds substantial meaning for both parameters. It explains the 'depth' parameter in detail (quick=3 facets, standard=5 with hop, thorough=8 paid with follow-up) and clarifies the 'question' parameter accepts broad/multi-part natural language. The description and schema together fully capture parameter 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 it performs 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and differentiates from open-web search. It also distinguishes itself from sibling tools like ask_pipeworx, noting it is best for 'broad/multi-part questions over structured data.'

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 is provided: 'Best for broad/multi-part questions over structured data,' with direct exclusions: 'For a single lookup use ask_pipeworx' and for 'BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also states that if not signed in, users should use ask_pipeworx instead, covering account prerequisites.

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

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

Annotations already declare readOnly and idempotent hints, but the description adds valuable behavioral details: it returns top-N tools with names, descriptions, and full input schemas with curated examples, and notes that results are ready to call directly without a second lookup. This goes beyond annotations to set expectations for the output and convenience.

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

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

The description is front-loaded with the core purpose and includes a useful but somewhat long list of example domains. The extra domain list may aid discovery but adds length. Overall it is structured well: purpose, usage, return behavior, and strategic guidance in four sentences.

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

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

Despite having no output schema, the description explains the return format (names, descriptions, full input schemas, usable directly). Given the tool's simple input (query plus optional limit and aliases) and clear behavioral notes, the description is fully complete for the agent's decision-making and 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 coverage is 100%, with all aliases and the limit parameter documented in detail. The description itself does not add parameter-level meaning beyond the schema, but it does mention 'top-N' which aligns with the limit parameter. Since the schema carries the semantic weight, a baseline 3 is appropriate.

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

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

The description starts with 'Find tools by describing the data or task', which is a clear verb+resource statement. It also differentiates from siblings by emphasizing discovery across many domains and explicitly says 'Call this FIRST' when surveying the option set, distinguishing it from specific search tools like search_recalls.

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 usage context: 'Use when you need to browse, search, look up, or discover what tools exist for' followed by a concrete list of domains. It also contrasts with getting 'just one answer', and instructs to call this first when many tools are available, offering clear when-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?

Annotations already indicate a safe, idempotent read operation. The description adds rich behavioral detail: fans out across multiple sources, returns specific fields, includes soft-fail behavior for patents, and fallback order for news. 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 dense paragraph but every clause adds needed information (examples, sources, output fields, constraints). It would benefit from bullet points or breaks, but it remains highly informative without 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?

Given the tool's multi-source complexity and no output schema, the description fully enumerates return data (cik, filings, fundamentals, patents, news, LEI), explains the patents sunset, identifies the fallback chain, and covers input constraints. It is complete for an agent to use correctly.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description reinforces this with concrete examples (AAPL, 0000320193) and emphasizes the zero-padding requirement, adding marginal 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's purpose: 'full cross-source profile of a US public company in ONE parallel call' and lists concrete example queries. It distinguishes from siblings by explicitly preferring it over chaining single-pack lookups.

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

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

Provides explicit when-to-use guidance ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups') and when-not-to-use ('names not supported — use resolve_entity first'), along with a noted fallback for the patents API.

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 destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds minor context like 'previously stored' and 'clear sensitive data' but does not disclose behavior for non-existent keys or error handling. It does not contradict annotations; it just adds limited extra detail beyond the structured hints.

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 three sentences, each earning its place: purpose, usage context, and relationship to sibling tools. It is front-loaded with the action and free of fluff, making it highly scannable for an agent.

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 single-parameter delete tool with no output schema, the description completely covers what, when, and with what other tools to use. The annotations provide safety information, and the description leaves no major gaps. The absence of return-value details is acceptable given no output schema and the destructive nature.

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% since 'key' is described as 'Memory key to delete'. The description's 'previously stored memory by key' confirms the meaning but does not add substantial new semantics beyond the schema. This meets the baseline for high coverage.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory') plus the method ('by key'), clearly distinguishing it from siblings like 'remember' and 'recall'. It directly states the tool's core action without ambiguity.

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

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

The description explicitly states when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also provides a pairing with 'remember and recall', giving contextual relationship without naming alternatives but making the intended use 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 behavioral context: it fetches the page, extracts title/description/key links, and emits 'the standard llms.txt markdown format.' It also clarifies the output as a 'single text blob,' going beyond the annotation baseline.

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 three sentences, front-loaded with the main purpose, followed by the process and use cases. Every sentence contributes value with no redundancy or filler.

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

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

For a tool with only 2 params and no output schema, the description explains what it does, how it does it, what the output looks like, and why it is useful. It is self-contained and leaves no critical gaps for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%: both 'url' and 'max_links' have clear descriptions in the schema. The description adds no extra meaning about parameters, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Generate') with a clear resource ('llms.txt file') and scope ('for any URL'). It distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than checking or scanning.

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 ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use it. However, it does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it returns specific fields (id, type, params, etc.) and defaults to active subscriptions, giving useful behavioral context beyond the annotations. No contradictions.

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

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

Two sentences, front-loaded with the core action, followed by return fields and use case. 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?

For a simple list tool with one optional parameter, the description covers purpose, return fields, and usage context. It lacks pagination/limits info but is adequate given the tool's simplicity.

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

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

Schema description coverage is 100% for include_inactive. The description's mention of 'active subscriptions' implicitly relates to the parameter but doesn't add new semantic detail beyond the schema, so baseline 3 applies.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and differentiates from sibling subscribe/unsubscribe by noting it's for reviewing before adding or cancelling.

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 provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This indicates when to use it but doesn't explicitly name alternative tools or when-not scenarios, so it's clear context without 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 stateful behavior (claim_token for later review), rate limiting (5 per identifier per day), cost (free, not counted against quota), and processing cadence (daily digests), all beyond the annotations' false hints. No contradiction with annotations, as readOnlyHint:false is consistent with the write action of filing feedback.

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?

Though long, the description is front-loaded with the purpose and every sentence provides distinct value—trigger conditions, exclusions, content guidance, claim-token workflow, rate limit, and cost. The structure is logical and readable.

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 the tool returns (claim_token, subsequent status) and how to use it. Combined with detailed parameter schema, clear exclusions, and operational notes (rate limit, free), it's 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 coverage is 100%, meeting the baseline, and the description adds meaningful guidance: advise describing issues in terms of Pipeworx tools/packs rather than end-user prompts, and clarifies claim_token's purpose as a follow-up read mechanism. These enrich the parameter understanding 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 opens with a specific verb and resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly distinguishes itself from siblings by limiting scope to tools served by this Pipeworx connection. It enumerates use cases (bug, feature/data_gap, praise), making its purpose unambiguous.

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

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

It gives explicit triggers (wrong/stale data, missing tool, unexpected success) and an explicit exclusion (other MCP servers' tools), even telling the agent to file with that other server instead. It also clarifies how to identify Pipeworx tools and what content to include, going well beyond basic when-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?

Beyond the readOnly/idempotent annotations, the description adds valuable behavioral context: caching windows (5min-1h), data provenance (CF analytics-engine), and privacy (no PII, just pack/tool/count). This is richer than typical and aligns 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 well-structured with a strong opening sentence, a brief list of use cases, and useful extra context about caching and privacy. It is a bit longer than strictly necessary but every sentence contributes value.

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

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

For a one-parameter read-only tool with no output schema, the description is remarkably complete: it states the return content, gives use cases, explains data source and caching, and clarifies privacy. An agent has enough to decide when and how to use it.

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

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

The input schema already fully describes the 'window' parameter including default, enum values, and their meaning (shorter = hot right now, longer = steady-state). The description merely repeats the enum values without adding new parameter details, so the baseline of 3 applies.

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

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

The description clearly states what the tool does: it returns top tools, top packs, and total call volume from other agents' current activity on Pipeworx. This distinguishes it from sibling tools like discover_tools, which likely focuses on different discovery criteria.

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 lists three concrete use cases (e.g., discovering hot data sources, confirming a canonical tool, checking alignment with agent needs). It provides clear context for when to use, though it does not explicitly name alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description enriches this with internal logic: Jaccard similarity threshold (≥0.30), placeholder filtering (skipped_low_similarity, placeholders_filtered), and the fill-check behavior against live CLOB depth. It also reveals the '>3pp emit a BUY/SELL EVERY LEG signal' rule, which is significant behavioral context not derivable from 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 well-structured: a one-sentence purpose, followed by clearly labeled mode sections (event, topic), semantic anchor, partition filter, response format, and fill check. It front-loads the primary verb and resource, and each paragraph adds distinct value. However, some illustrative examples (e.g., 'Powell-Fed-Pause being paired with Powell-DOJ-probe') are arguably expendable, making it slightly less concise than ideal.

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 compensates by explaining the response structure ('opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)') and the partition_check details. It covers both modes, filters, fill-check logic, and fallback to polymarket_fill_risk. Given the tool's complexity, the description leaves no significant gaps for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% with descriptions for both 'event' and 'topic', but the description adds critical semantics beyond the schema: it explains mode-specific behavior, provides concrete example slugs and seed questions, and clarifies that 'event' walks child markets while 'topic' flattens across events. This enables correct parameter selection beyond what the schema properties alone convey.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly states the tool's function and is distinct from sibling tools like polymarket_edges (tracks edges) and polymarket_fill_risk (sizing), with an explicit cross-reference to fill_risk for sizing. The purpose is unambiguous and well-scoped.

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: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative tool ('For custom sizing use polymarket_fill_risk') and clarifies when the fill check is necessary ('when the partition signal fires... do not trade it'). This fully addresses usage context and 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?

Beyond the read-only, idempotent, and non-destructive annotations, the description reveals key behavioral details: edge is calculated net of slippage, there is a 24h-move warning, results are cached for 1 hour keyed on knobs, and diagnostics reveal why segments might be empty. This is substantial additional transparency well beyond what annotations alone convey.

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

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

The description is a dense, long-form block of text without sections or bullet points, which could be challenging to parse. However, every sentence contains substantive information about model families, output structure, or edge calculations. It is not minimal, but the length is justified by the tool's complexity, earning a 4 rather than a lower score.

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

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

With no output schema, the description carries full responsibility for explaining return values. It thoroughly covers the top-level response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market stats), and diagnostic funnels. It also explains the rationale behind Fed bet exclusion and the filter knobs, making it highly complete for an agent to understand and correctly invoke the 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?

The schema already provides rich descriptions for all 9 parameters, achieving 100% coverage, so the baseline is 3. The description adds extra context for the tradeable-edge knobs (min_liquidity, max_spread_pp) and specifically explains the subtle behavior of min_partition_leg_kelly (since parent-level kelly_fraction_half is always 0 for partitions). This elevates the value above 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 opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states the tool's function and differentiates it from generic market tools. It also articulates the intended use case, 'what should I bet on today,' which further clarifies its purpose.

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

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

The description provides clear context for when to use the tool (discovering betting opportunities without paging hundreds of markets) and even includes an explicit exclusion (Fed bets are surfaced but excluded from ranking with a rationale). However, it does not name alternative sibling tools or explicitly state 'use this instead of X', so it falls short of a 5.

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?

Even with readOnlyHint=true, the description goes far beyond annotations by disclosing critical behavioral details: history depth is bounded by 60-day TTL, snapshots are written on cache-miss (gaps mean no scan), decay is computed from daily closes of edge_pp_net (not intraday), and the sign convention (negative = SELL YES). This is exactly the kind of context that prevents misuse.

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 exceptionally well-structured with clear sections (Args, RESPONSE, LIMITS). Every sentence earns its place—there is no filler or redundancy. The use of ALL CAPS for response keys and section headers improves scannability.

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 compensates by detailing the response structure (tracked[], expired[], snapshot_dates[]), what each field means, and the limitations (TTL, cache-miss gaps, daily closes). It also explains the median lifespan as a 'competition clock,' making the tool's output actionable without requiring further documentation.

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 already names and describes both parameters with 100% coverage, so the baseline is 3. The description adds value by explaining that days controls lookback with a clamp of 2-30 and is bounded by the 60-day TTL, and that window selects a snapshot family (24hr/1wk/1mo). This extra behavioral context on how parameters affect results nudges the score above baseline.

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 'Edge persistence and decay telemetry' with a specific question it answers: 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence and decay, and even explains why a 3-week-old edge is materially different from a fresh one.

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 strong contextual guidance on when to use the tool: when you need edge persistence, decay trends, and lifecycles. It includes a motivating example (fresh vs. old edge) and explains what the snapshots represent. However, it does not explicitly name alternative tools or state when NOT to use this tool, which prevents a perfect score.

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

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

Annotations already declare readOnly/idempotent, but the description goes far beyond by detailing execution behavior: it 'walks the ladder', returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains mode-specific interpretations (size_usd as settlement notional in basket), and warns about forced_directional_risk and thin_legs. This provides rich behavioral context without contradicting 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 long but densely informative, with clear structural markers (SINGLE-MARKET, BASKET, USE THIS) that aid scanning. It is front-loaded with the core purpose. While longer than ideal, every sentence earns its place given the tool's complexity and two modes.

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

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

With no output schema, the description carries full responsibility for explaining return values. It lists all key outputs for both modes, covers edge cases (thin_legs, forced_directional_risk, max_clean_notional_usd), and includes usage context relative to sibling tools. For a complex tool with two modes, this is 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%, so the baseline is 3. The description adds extra semantics, notably that `size_usd` is interpreted as settlement notional (shares per leg) in basket mode, and explains the `side` defaults/auto-detection for basket mode. This goes beyond the schema without fully compensating for every nuance, but the schema already handles parameter basics.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb ('check') and resource ('CLOB order-book depth'). It clearly distinguishes single-market and basket modes, separating it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill-risk validation rather than signal generation.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' providing concrete when-to-use context and naming alternatives. It also explains the rationale (theoretical overround is not capturable, partial fills create directional risk), making the usage guidance unambiguous.

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 readOnly/destructive/idempotent annotations, the description details compatibility_warning firing conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and response fields like matched spread and top_spreads_pp. It warns that aligned:false means spreads are 'mathematically meaningless,' which is exactly the behavioral context annotations can't convey.

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

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

The description is long but structured with TWO MODES, RESPONSE, and SAFETY FIELDS labels, and every sentence adds functional detail (warning cases, temporal alignment, skipped counters). It front-loads the core purpose before diving into edge cases.

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 compensates by enumerating returned data: leg-by-leg prices, matched spread[], top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also explains two distinct warning scenarios, making the tool self-sufficient for an agent.

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

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

Schema coverage is 100% with per-parameter descriptions, so the baseline is 3. The description adds operational meaning by framing the three params as two modes ('topic' auto-fetch vs explicit kalshi_event_ticker + polymarket_event_slug for custom pairings) and explaining override behavior, which goes beyond the schema text.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' naming the exact resource and operation. It distinguishes from sibling tools like polymarket_arbitrage by focusing on the two-venue comparison and explaining the two input modes.

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: when to use the topic mode vs explicit tickers, and cautions that 'most pre-mapped topics return compatibility_warning today — pre-mapped ≠ tradeable.' It lacks explicit alternatives like 'use X for single-venue opportunities,' but gives enough contextual guidance to select the tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful context about scoping to the user's identifier and the memory lifecycle, which goes beyond annotations. 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?

Three sentences, each earning its place: behavior, use case, and scoping/lifecycle. It is front-loaded with the action, making it easy for an agent to quickly understand the purpose.

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 one optional parameter, no output schema, and strong annotations, the description covers the essential behavior, use cases, and scoping. It could optionally describe the return format (single value vs list) but the schema and examples make this largely inferable.

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 already describes the key parameter and the omission behavior with 100% coverage, so the baseline is 3. The description reinforces this with examples of stored values, but adds no new parameter-specific syntax beyond what the schema provides.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes itself from sibling tools like remember, forget, and search_recalls by specifying the read-only lookup behavior and the optional key omission for listing.

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 states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also references companion tools remember and forget, but does not explicitly name alternatives like search_recalls or state when not to use, so it stops short of full exclusion guidance.

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

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

The description contradicts the annotations by stating that mark_read:true flags events read (a mutation), while readOnlyHint is true. This is a direct inconsistency. The description adds useful context like return payload and polling, but the contradiction forces a score of 1.

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 compact and front-loaded with the main purpose. Each sentence adds distinct value: return payload, filtering, mark_read side effect, and alternative access. No unnecessary words.

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

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

For a tool with 5 optional parameters and no output schema, the description covers the return shape, filtering options, state-changing side effect, and alternative URL access. The schema handles the remaining parameter details, making it complete for 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 covers 100% of parameters, but the description adds concrete examples ('sec_8k' for type, ISO timestamp for since) and explains the behavioral effect of mark_read on subsequent calls. This goes beyond the schema without being exhaustive.

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 action ('Pull fired events from your subscription feed') and specifies the resource (persisted feed). It also distinguishes from siblings like recent_changes and recent_recalls by focusing on subscription alerts, with details about payload contents.

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 usage context: 'Polls work fine' suggests suitability for polling, and mentions an alternative feed URL for scripts/dashboards. However, it does not explicitly compare to sibling tools or give when-not-to-use scenarios beyond that URL alternative.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial context beyond this: multi-source fan-out, fallback logic, USPTO soft-fail due to PatentsView API sunset, accepted since formats, and the return structure (changes[], total_changes, pipeworx:// URIs). 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 information-dense. It front-loads the most important use case with examples, then packs source details, fallback behavior, and return format into a tightly structured paragraph. Every clause adds value, but the density may require careful reading—hence not a perfect 5.

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?

There is no output schema, so the description correctly explains the return shape (changes[] grouped by source, total_changes count, citation URIs). It also covers input formats, source-specific failure modes, and alternative tool usage. For a tool that fans out to three APIs with fallbacks, this is thorough and 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% and each parameter already has a description. The description adds practical examples and constraints: 'since' accepts ISO date or relative shorthand ('7d', '30d', '3m', '1y') with a tip to use '30d' or '1m' for monitoring, and 'value' can be a ticker or zero-padded CIK. This exceeds the schema's bare descriptions without fully replacing them.

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

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

The description opens with natural-language query examples ('What's new with X'), then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call', listing the specific sources (SEC EDGAR, GDELT→GNews, USPTO). It clearly distinguishes itself from sibling tool entity_profile, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance with example queries and a direct exclusion: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback behavior (GDELT preferred, GNews on rate-limit/5xx) and soft-fail conditions, helping the agent decide when results may be incomplete.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context beyond annotations by specifying the CPSC source, 'newest first' ordering, and cross-category scope, which helps the agent understand expected results.

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 core purpose ('Most recent US consumer-product recalls') and immediately followed by usage alternatives. Every sentence earns its place with 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?

The tool is simple with 2 optional params, no output schema, and rich annotations. The description fully covers what the tool does, when to use it, and how to distinguish it from the sibling search_recalls, making it complete for an agent's decision-making.

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 provides 100% coverage of both parameters (days and limit) with clear descriptions, so the description does not need to add parameter details. The examples in the schema reinforce usage, but the description itself adds marginal value beyond the schema, hence baseline 3.

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 most recent US consumer-product recalls (CPSC), newest first, across all product categories. It explicitly distinguishes itself from search_recalls for specific product lookups, using a specific verb+resource structure.

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 usage guidance: 'Use for "latest product recalls", "recent safety recalls this month"' and directly names the alternative tool for specific products (search_recalls). This clearly communicates 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 annotations (readOnlyHint=false, idempotentHint=true), the description adds key behavioral details: key-value storage scoped by identifier, persistence duration (24 hours for anonymous sessions, persistent for authenticated users), and that deletion is handled by a separate tool. It doesn't mention overwrite behavior, but idempotentHint already suggests safe repetition, so 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?

Three sentences, first sentence immediately states the core purpose. Every sentence adds value: purpose, usage context, storage semantics, and complementary tools. No redundancy or filler.

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

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

For a simple two-parameter tool with no output schema, the description fully covers purpose, usage, scoping, persistence, and integration with recall/forget. The agent has all necessary information to select and invoke the tool correctly.

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

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

Schema covers both parameters (key, value) with descriptions, but the description adds contextual meaning: keys are scoped by identifier, and value can be 'any text'. This helps the agent understand namespacing and flexibility beyond the raw schema, though schema coverage is already 100%.

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 opens with 'Save data the agent will need to reuse later', clearly identifying the verb (save) and resource (data/memory). It distinguishes from siblings by explaining the use case and explicitly naming recall and forget as complementary tools for retrieval and deletion.

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: 'Use when you discover something worth carrying forward' with concrete examples. Also mentions persistence differences (authenticated vs anonymous) and names alternatives ('Pair with recall to retrieve later, forget to delete'), giving clear context on when this tool is appropriate.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds significant context: each call cascades through several endpoints, LEI/FIGI enrichment degrades gracefully, and unresolved identifiers are explicitly listed under an 'unresolved' field rather than omitted. This goes beyond annotation basics.

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 well-structured: it opens with user-facing examples, then states the core purpose, then organizes per-type details. Slight redundancy in the graceful degradation explanation ('degrades gracefully' repeated later as 'if GLEIF or OpenFIGI is unavailable') could be tightened without losing clarity.

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

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

With no output schema, the description effectively covers return values and edge cases: source-labeled identifiers, explicit 'unresolved' field, fallback behavior when external services are down, and the cascading multi-API nature. This is a complete picture for an agent to confidently use the 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 descriptions cover both parameters thoroughly (100% coverage). The tool description enriches this by detailing what each type returns (company: CIK, ticker, LEI, FIGI with source labels; drug: RxCUI, ingredient, brand, citation), and clarifying accepted input formats for 'value'. This adds meaning well beyond the schema.

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

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

The description clearly states the tool resolves a user-spoken name into canonical identifiers, with specific verb ('resolve') and resource ('NAME to the canonical/official identifiers'). It provides multiple example phrasings and distinguishes itself from siblings like entity_profile by focusing on ID lookup rather than profiling.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID', giving a clear, actionable when-to-use directive. It does not name alternative tools for when not to use, but the guidance is strong and context-specific.

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

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

Annotations already declare readOnly/idempotent, and the description adds useful behavioral detail: it probes with ai_visibility_check, ranks by score, identifies most/least recognized, and returns a list with score, 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?

The description is three sentences, front-loaded with the primary action, and every sentence adds value: what it does, how it works, and what it returns. No fluff.

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

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

For a tool with no output schema, the description compensates by stating the return format (ranked list with score, confidence, signal density) and explaining the internal process. It does not cover error cases or edge scenarios, but complexity is moderate and schema covers entity limits.

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

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

Schema description coverage is 100%, so baseline is 3. The description's 'your brand + N competitors' adds minor color but does not enhance parameter meaning beyond what the schema already provides.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' with a specific verb and resource. It distinguishes itself from sibling tool ai_visibility_check by noting it probes each entity with that check and ranks results.

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 clear context for use with 'Useful for competitive AI-marketing audits' and an example question. However, it does not explicitly mention when not to use it or name alternatives beyond implying comparison vs. single check.

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 well beyond annotations by disclosing partial failure behavior ('Partial failures degrade gracefully'), latency expectations ('bundlephobia's first measurement on a new version can take 5-30s'), and the 'sources_failed' field. These are not conveyed by the readOnly/openWorld/idempotent hints. 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?

Although the description is long, every sentence is information-dense and earns its place: purpose, usage, return details, ecosystem caveat, and failure behavior. It is front-loaded with the main purpose and structured logically, with no filler.

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

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

With no output schema, the description enumerates the return fields (summary block, per-advisory detail, links, alternatives), explains the performance caveat, and covers partial failure. It is complete for a tool of this complexity, needing no additional context.

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 both parameters are already well-described in the schema (package name, optional version with default). The description adds no significant additional param semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a composite check for adding an npm package, aggregating data from deps.dev and bundlephobia. It distinguishes itself from sibling tools by specifying its unique scope (npm package evaluation), and the verb 'scan' matches the resource 'dependency'.

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 is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion/alternative for non-NPM ecosystems, directing to deps.dev:version directly, making when-to-use and alternatives 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 declare readOnly/openWorld/idempotent/non-destructive, so safety is covered. Description adds behavioral context by listing exactly what each returned recall includes (title, date, products, hazard, remedy, injuries, manufacturer/retailer, URL) and notes optional date range. No contradictions.

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

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

Description is informative and front-loaded with action and preference. Every major sentence adds value, though the 'Optional date range' phrase is slightly redundant given the schema, and the example list partially overlaps schema examples.

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 search tool with no output schema, the description fully compensates by enumerating return fields, product categories, and scope boundaries. It also provides alternative tools for adjacent domains, making it contextually 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 description coverage is 100% with clear per-parameter descriptions and examples. Description adds little over schema—only a generic 'Optional date range' note, while schema already explains start_date/end_date. Baseline 3 is appropriate.

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

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

Description uses specific verb 'Search' plus resource 'US consumer-product safety recalls (CPSC)' and clarifies scope. It distinguishes from sibling tools by explicitly naming get_recalls (NHTSA) and openfda as alternatives for other recall types.

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

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

Gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH for...'), provides concrete example queries, and clarifies exclusions with a NOTE about vehicles (get_recalls) and food/drugs (openfda). This is strong differentiation from 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 read-only annotations, the description discloses the embedding model (BGE-base-en), chunking (500-char overlapping windows), the 200K char cap with truncation flagging, and the return format (offsets + similarity scores), providing rich 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 packs essential usage and technical details into three sentences, with the core function front-loaded. No filler; each sentence adds unique value.

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

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

With no output schema, the description compensates by specifying the return structure (passages with offsets and scores). It covers input limits, truncation behavior, and integration with a related tool, making it self-sufficient.

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 already documents all three parameters (100% coverage), but the description adds illustrative query examples and clarifies the 'text' parameter as previously-fetched document content. It also implicitly explains 'limit' via 'top-N passages.'

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

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

The description opens with 'Semantic search INSIDE a fetched record,' precisely stating the tool's function. It distinguishes itself from sibling tools like ask_pipeworx by emphasizing it operates on already-pulled text, and explicitly contrasts with ask_pipeworx_grounded.

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 an explicit trigger: 'Use when the record is too big to cram into the prompt,' and explains the benefit of saving context. It also points to a companion tool, ask_pipeworx_grounded, for a grounded workflow, demonstrating awareness of 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 annotations, the description discloses critical behaviors: OAuth requirement, return of subscription id, SMS verification and daily cap, webhook HMAC signing and auto-disable after failures, and the always-on feed endpoint. These are essential operational details not captured by the readOnly/idempotent/destructive hints.

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, then prerequisites, types, and delivery details in a logical order. Despite its length, every sentence carries necessary information for a complex multi-type subscription tool with no redundancy or fluff.

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

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

Given no output schema, the description adequately explains the return value (subscription id and one-time webhook secret). It covers all supported types, parameters, delivery channels, prerequisites, and failure modes, making it self-sufficient for an agent to successfully invoke the 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?

The schema itself has 100% parameter coverage with rich descriptions, so the baseline is 3. The description adds extra semantic nuance, such as the example that items:['5.02'] means officer change for sec_8k, and clarifies that SMS must match the verified phone. While mostly restating the schema, this added example and consolidated context elevate it slightly.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It differentiates from sibling tools like list_subscriptions and unsubscribe by emphasizing creation and monitoring.

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 clear context for when to use the tool: for proactive monitoring of specific live-data event types. It also notes a key prerequisite (requires Pipeworx OAuth account, anonymous/BYO cannot persist), and explains delivery options with how to consume the feed. However, it does not explicitly name alternative tools or exclusions, relying instead on the clear purpose and sibling names.

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, idempotent, non-destructive behavior. The description adds value by describing the return format: 'Returns category-bucketed example questions... each with the exact tool + argument shape,' and notes the output is 'drawn from the live catalog of thousands of tools,' implying dynamic content. This contextualizes what the agent can expect without contradicting 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?

While the description is longer than average, every sentence earns its place: it lists user intentions, return contents, category names, parameter behavior, and a clear 'Use this FIRST' directive. It is well-structured with the opening queries, a dash explanation, and a closing usage statement. No fluff.

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

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

For a tool with only one optional parameter and no output schema, the description is complete: it explains what the tool does, what it returns, how to call it, and when to use it. It also references related meta-tools, providing full onboarding context. There is no missing information needed for an agent 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 coverage is 100%: the only parameter `topic` is fully described with allowed values and the omit behavior ('Omit for a cross-category spread'). The description repeats this and adds examples ('finance', 'pharma', 'betting'), but does not introduce new meaning beyond what the schema already 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 tool is the onboarding entry point that returns category-bucketed example questions each with the exact tool and argument shape to answer it. It distinguishes itself from siblings like ask_pipeworx and discover_tools by focusing on 'what is worth asking' and learning how to call meta-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?

Explicit direction is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the two calling modes: no arguments for the full spread, or pass a topic to focus. It does not mention explicit alternatives or when not to use it, so not a 5.

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

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

Annotations already mark this as non-destructive and idempotent. The description adds critical details: ownership enforcement, deactivation instead of deletion, and preservation of historical events via recent_alerts. This goes beyond annotation data.

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

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

Two sentences with no redundancy; the core action is front-loaded and additional context is woven in efficiently.

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

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

For a single-parameter tool with rich annotations, the description covers all necessary behavioral aspects: action, ownership, side effects, and data retention. No output schema is needed for this cancel operation.

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

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

The input schema fully documents the id parameter (uuid returned by subscribe). The description adds no new parameter-level semantics, so baseline 3 is appropriate given 100% coverage.

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

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

The description explicitly states the action ('Cancel a subscription by id') and differentiates from siblings like subscribe and list_subscriptions by focusing on cancellation. The title reinforces the alert context.

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 clearly communicates the tool's role for canceling subscriptions and notes ownership restrictions. While it doesn't explicitly name alternative tools, the context is sufficient for typical use cases; a minor gap is no explicit 'when not to use' statement.

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 well beyond the readOnly/idempotent annotations by disclosing return semantics (verdict values, grounded/structured value with citation, reasoning) and critical caller caveats: 'could_not_verify means the check did not happen... it is NOT evidence for or against the claim' and 'unsupported means we looked and cover no source for it.' This is rich behavioral context that annotations do not cover.

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 earns its place: example triggers, usage directive, routing logic, return artifacts, and important error-state caveats. It is front-loaded with user-phrased examples and structured clearly from usage to semantics. No filler or redundancy.

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

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

Despite no output schema, the description fully explains the return format (verdicts, actual value, citation, reasoning) and the meaning of special verdict states (could_not_verify, unsupported). It also covers the financial-vs-other routing and the math behind tolerance. Given the tool's complexity and the absence of an output schema, this is complete and unambiguous.

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 input schema already provides detailed semantics for both parameters, including the tolerance_pct range, override behavior, and default. The main description adds little beyond the schema—it mentions exact percent-delta math but doesn't introduce new parameter-level guidance. With such high schema coverage, a 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's purpose: natural-language claim verification against authoritative sources. It provides specific example user phrasings ('Is it true that...' / 'fact check') and distinguishes itself from sibling research/ask tools by focusing on verdict-based fact-checking for factual claims. It also differentiates its handling of company-financial claims via SEC EDGAR versus other claims via the grounded pipeline.

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 usage context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic and notes it replaces 4–6 sequential calls, implying when this is the better single-call choice. However, it does not explicitly name alternative tools or state when NOT to use it, so it lacks the full when-not/alternatives structure.

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