Excuse

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

Annotations already declare the tool as read-only, non-destructive, idempotent, and open-world. The description adds valuable behavioral context by revealing that it makes external calls to LLMs and, when `_apiKey` is passed, calls Anthropic directly with the user paying. This is beyond what annotations capture and does not contradict them.

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

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

The description is three sentences long and front-loaded with the core function. Every sentence carries essential information—purpose, model defaults, return format, and use cases—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?

Despite having no output schema, the description explicitly states the return shape (per-model {score, confidence, signals, raw_response} + combined view). It also covers model selection, authentication, and practical use cases, making it complete for an agent to decide on 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 description coverage is 100%, with each parameter already well-documented (e.g., models lists supported options, `_apiKey` clarifies the BYO-key requirement). The description reinforces but does not add significant new semantic depth beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific action—'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly states the tool's purpose and scope, distinguishing it from sibling tools by focusing on multi-model visibility scoring. The added mention of per-model scoring and combined view makes the tool's unique value evident.

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 use-case context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the Anthropic model (pass `_apiKey`). However, it does not explicitly mention when not to use this tool or name alternative siblings, keeping it from 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds meaningful context: it routes to tools, fills arguments, returns structured answers with citation URIs, works on every tier, and is a single fast call. This goes beyond the annotations without contradicting them.

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

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

The description is long but well-structured, starting with the key directive 'PREFER OVER WEB SEARCH' and then providing context, examples, and alternatives. Each sentence adds value (scope, triggers, fallbacks), though it could be slightly tightened. Overall, it is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (routing meta-tool) and no output schema, the description comprehensively covers what the tool does, when to use it, when not to (alternatives), examples, and returns characteristics (structured answer with citations). It leaves very few gaps for an agent to guess.

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

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

Schema coverage is 100% with all parameters (actually one real parameter and five aliases) described. The description itself does not add parameter-level details beyond schema; however, the schema's description of 'question' with alias handling is sufficient. 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 the tool answers factual questions by routing to one of 5,529 tools across 1,455 verified sources and returns structured answers with citations. It uses specific verbs and resources ('routes the question', 'returns the structured answer') and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says to prefer this tool over web search, provides trigger phrases ('what is', 'look up', 'get the latest'), and gives alternative tools with conditions: use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. Also notes it covers news/breaking-news, filling the when-not gap.

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

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

Beyond the read-only, idempotent annotations, the description reveals the tool's experimental nature, the possibility of live routing changes when a candidate is under test, and the current inactive state (no candidate active). It preempts ambiguity by stating 'Falls back to nothing — this IS a full working router', providing significant 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?

Four sentences, each with a distinct purpose: identify as beta, explain identical nature, state current inactivity, and clarify it's a full router with usage guidance. Dense but concise, with no wasted words or redundancy.

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

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

Given the simple input schema and rich annotations, the description fully covers the tool's purpose, usage, current state, and relationship to siblings. It even notes the identical response shape to ask_pipeworx, allowing agents to refer to that sibling for return format 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?

The schema already covers all 6 parameters with descriptions, including multiple aliases for 'question' (coverage 100%). The tool description adds no additional parameter details beyond mentioning 'same arguments' as ask_pipeworx, 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 it is the 'Beta version of ask_pipeworx' — an 'identical universal router' with the 'same 5,529 tools'. It distinguishes itself from the stable sibling by noting it carries 'candidate routing improvements' and is the 'experimental edge'.

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 it exactly like ask_pipeworx when you want the newest routing', identifying the alternative (ask_pipeworx) and the specific condition for choosing this beta. It also clarifies current equivalence ('currently matches ask_pipeworx exactly') and that results are compared for merge decisions.

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 readOnlyHint, openWorldHint, and idempotentHint, but the description adds significant behavioral details: it returns a structured refusal when data is absent, lists specific refusal reasons, and discloses the extra LLM call cost. This exceeds what annotations convey and helps the agent predict outcomes accurately. 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 compact yet information-dense. It front-loads the core purpose in the first phrase, then systematically covers return shape, refusal behavior, usage scenarios, and cost comparison. Every sentence earns its place; 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 having no output schema, the description fully documents the success return shape and all refusal modes. It explains the underlying mechanism (routing across 5,529 tools), the grounding constraint, and cost trade-off, making the tool's behavior predictable. This is comprehensive 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 description coverage is 100%, with all six parameters being aliases for the same natural-language 'question'. The description adds high-level context about routing but does not add parameter-specific semantics beyond the schema. Baseline 3 is appropriate because the schema already carries the full parameter meaning.

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 this as a hallucination-resistant answer mode for high-stakes reads, distinct from the sibling ask_pipeworx. It specifies the exact behavior: route through the same tool picker, fetch data, then extract answers only from the tool result. This goes beyond a simple verb+resource and effectively differentiates from ask_pipeworx and ask_pipeworx_beta.

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 this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. It also provides a clear alternative guideline: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost. This is strong usage guidance with both inclusion and exclusion criteria.

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

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

The description goes far beyond the annotations (read-only, open-world, idempotent) by detailing the resolver contract with match confidence levels, the behavior for low-confidence and closed markets, wide-spread tradeability flags, fallback handling for news 429s, and the cancellation rule parser with its EV implications. This is rich, actionable behavioral disclosure beyond 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 long, but it is organized into clear, labeled blocks (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the core purpose. There is minimal fluff; every block contributes essential operational detail. It could be more succinct (e.g., the final rules-risk paragraph is dense), but the structure makes it scannable and the length is justified by the tool's complexity.

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 fully explaining response shapes: result.market fields, result.analysis with model probability and edge, result.evidence keyed by source, parent_event extractor, news fallback fields, and all blocking statuses (low_confidence_match, market_closed_or_inactive, tradeability). It also covers cancellation-rule risk, which is critical for safe bet sizing. This is exceptionally complete for a complex research 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 covers 100% of parameters with descriptions and examples, so the baseline is 3. The description adds some context (e.g., mention of quick vs thorough fan-out, include_raw payload sizes), but most parameter semantics are already well-specified in the schema. No extra meaning is needed; the description complements the schema without significantly extending it.

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 precise verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further clarifies the three query intents ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which clearly positions the tool and differentiates it from sibling tools focused on edges, arbitrage, or generic data lookup.

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 when-to-use context: 'Use for "should I bet on X"...' and includes multiple operational guidelines (e.g., inspect market_match_confidence, check cancellation_rule before sizing). It doesn't explicitly name alternative tools to use instead, but the sibling context and query framing provide sufficient guidance for selection without exclusion criteria.

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

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

The description adds substantial behavioral context beyond the annotations: it reveals data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specifies that off-calendar fiscal years are handled correctly, explains sorting by primary metric, and notes it returns paired data plus citation URIs. This enriches the read-only annotation with detail on what the tool actually does.

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

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

The description is longer than the calibration examples but every sentence contributes value: trigger phrases, usage preference, data sources, special fiscal-year handling, sorting, and return format. It is well-structured and front-loaded with usage cues, though it could be slightly trimmed without losing essential information.

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

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

For a tool with two parameters and no output schema, the description gives adequate context: it explains the number of entities supported, the data sources, sorting behavior, and that it returns paired data with citation URIs. It does not mention error handling or invalid inputs, but the core usage is clear enough for an agent to 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?

While the schema provides full coverage of the two parameters (type and values), the description adds meaningful semantics: it explains that 'type=company' pulls financials from 10-K and 'type=drug' pulls adverse-event/trial counts, and it gives example values like tickers/CIKs or drug names. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one call, using specific verbs like 'compare', 'rank', and 'head to head'. It also distinguishes from sibling tools by explicitly saying it should be preferred over sequential single-pack lookups, 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 provides explicit when-to-use guidance with trigger phrases and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies the two entity types (company vs drug) and what each pulls, which helps the agent decide which to use. No explicit exclusions for single-entity lookups, but the preference is clear.

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

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

Despite annotations indicating readOnly/openWorld/idempotent, the description goes far beyond them: it explains the tool's latency (15-60s, up to ~90s), the gap[] mechanism (never invented answers), contradictions[] (only for standard/thorough), the hop field and citation_uri behavior, semantic excerpting, and the account requirement. This is rich, candid behavioral transparency that no annotation could 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 information-dense, front-loaded with the most critical operational caveat (account requirement) and sibling alternative. Every sentence adds distinct value, but at ~280 words it could be slightly tightened without loss; the structure moves from prerequisites to behavior to examples to edge cases to performance, which is logical.

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 complex tool with no output schema, the description is remarkably complete: it covers prerequisites, fallback alternatives, return structure (findings packet with gaps, contradictions), latency expectations, citation resolvability, and semantic excerpting behavior. It answers the main questions an agent would need to decide and invoke correctly.

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

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

The schema has 100% coverage with detailed descriptions for both parameters, so the baseline is 3; however, the description adds crucial semantics beyond the schema: it explains the practical implications of each depth tier ('quick' is single hop, 'standard' adds gap recovery, 'thorough' is paid and chases leads), and clarifies that the question parameter can be broad/multi-part. This meaningfully enhances 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 does grounded multi-source research across Pipeworx's 1455 structured data sources via parallel decomposition, distinguishing it from sibling tools like ask_pipeworx. It explicitly contrasts with open-web search and names the key resource (structured data sources) and behavior (decomposes, routes, returns findings packet).

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: best for broad/multi-part structured-data questions, and explicitly says to use ask_pipeworx for single lookups and breaking/current-news topics. It also discusses depth tiers with behavioral differences (gap recovery, contradictions), giving clear context on when to choose which depth.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'each result is ready to call directly, no second schema lookup needed.' This explains the return behavior and usability, exceeding the minimum required.

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, immediately front-loaded with the core purpose. The first sentence lists supported domains, and the second explains the return format and usage guidance. Every word earns its place, 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?

For a discovery tool with 6 parameters (mostly aliases) and no output schema, the description is very complete: it states what it does, when to use it, what it returns, and how to use those results. The schema covers parameter details. The only minor gap is that it doesn't explicitly mention the aliases, but the schema does. Overall, the description sufficiently equips an agent to 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 description coverage is 100%, so the baseline is 3. The description adds a high-level semantic ('describing the data or task') but does not elaborate on individual parameters beyond what the schema already provides. The description mentions 'top-N' but the limit parameter's default and max are already in the schema. No additional parameter meaning is needed.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It uses a specific verb+resource ('find tools') and provides a comprehensive list of covered domains (SEC filings, financials, FDA drugs, etc.), which differentiates it from sibling tools that perform specific tasks rather than discovery.

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

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

Explicit guidance is given on when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly indicates the tool is for initial discovery rather than for executing a specific task, distinguishing it 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?

Annotations already declare readOnlyHint and idempotentHint. The description adds substantial behavioral detail: multi-source fan-out, specific return fields (e.g., 'fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC)'), the USPTO API sunset and soft-fail behavior, and the GDELT→GNews fallback. This goes well beyond the safety 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 dense but every clause serves a purpose: examples, primary use, differentiated instructions, return structure, and input constraints. It is front-loaded with example queries and avoids filler. Length is justified by the tool's complexity.

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 aggregates multiple sources and has no output schema, so the description carries a heavy burden to explain return values. It lists each returned group with field-level detail, including sort order and URI format, plus caveats like the patent soft-fail. This is thorough for the complexity.

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

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

Schema description coverage is 100%: both 'type' and 'value' have explanatory descriptions. The description echoes the same constraints (ticker vs CIK, no names) with concrete examples like 'AAPL' and '0000320193', adding slight clarity but no new semantics 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 opens with concrete user queries ('Tell me about X' / 'research Acme') and states the tool produces a 'full cross-source profile of a US public company in ONE parallel call.' It explicitly differentiates itself from chaining single-source lookups and from resolve_entity, making the purpose unmistakable.

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 an explicit usage guideline: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states the input requirements (ticker or CIK, not names) and directs users to resolve_entity when only a name is available, covering when not to use this 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, covering the safety profile. The description adds the behavior of returning ready-to-use text, but does not disclose other behavioral traits such as whether the excuse is generated deterministically or how it might change based on the 'times_used_before' parameter. The description does not contradict any 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, well-structured sentence that front-loads the primary action (generate an excuse) and then enumerates the key inputs and output. Every word contributes meaning, with no redundancy or filler.

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

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

Given the tool's moderate complexity (4 params, 3 enums, output text), the description covers the core purpose, inputs, and output. The schema provides examples and a description for 'times_used_before,' and annotations cover the safety profile. However, the description doesn't mention potential limitations or circumstances where the output might be inappropriate, leaving a slight gap in completeness.

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

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

The schema covers only 25% of parameters with descriptions, but the description compensates by listing the allowed enum values for situation, audience, and excuse_quality. It does not explain the effect of 'times_used_before,' though the schema does. This adds meaningful context beyond the schema, making the parameters more understandable.

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

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

The description clearly states the tool generates excuses, identifies the key inputs (situation, audience, quality tier), and notes the output is ready-to-use excuse text. It uses specific verbs and enumerates the resource types, making the purpose unambiguous and distinct from sibling tools.

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

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

The description provides clear context on when to use the tool: when an excuse is needed for a given situation, tailored to audience and quality. It does not explicitly mention alternatives or exclusions, but no direct competing tools exist among siblings, so the usage is evident. It lacks explicit 'when not to use' guidance, preventing 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 declare destructiveHint=true and idempotentHint=true, so the description adds useful context about what gets deleted and the scenarios for deletion. It does not contradict annotations.

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

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

The description is two concise sentences, front-loaded with the primary action and followed by usage guidance. Every sentence is informative and no unnecessary words are present.

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 single-parameter tool with full schema coverage and annotations for destructive/idempotent behavior, the description is complete. No output schema is needed for this delete 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 schema covers 100% of the parameter with a clear description ('Memory key to delete'), and the tool description reinforces this without adding new semantics. 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 the action with a specific verb and resource: 'Delete a previously stored memory by key.' It distinguishes from sibling tools like remember and recall by focusing on 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?

Explicit guidance is given on when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, providing clear context on alternatives.

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

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

The description adds behavioral context beyond the annotations: it fetches the page, extracts specific elements, and emits a single text blob. This includes network behavior and output format, which is helpful. Annotations already cover safety (readOnly, non-destructive), so the added process detail earns a 4.

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

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

The description is concise, front-loaded with the main purpose, and every sentence adds value. The 'Useful for' list is structured and not redundant. No wasted words.

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

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

Despite no output schema, the description explicitly states the output is a single text blob ready for site-root/llms.txt, and covers the process, use cases, and behavioral details. This is complete for the tool's complexity and parameter count.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description itself doesn't add any extra meaning about parameters, but the baseline 3 applies because the schema handles the heavy lifting.

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 with a specific verb ('Generate') and resource ('llms.txt file'), and explains the process (fetches page, extracts title/description/key links, emits standard markdown). This clearly distinguishes it from sibling tools like scan_competitor_ai_presence or ai_visibility_check.

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

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

The 'Useful for' section provides explicit contexts: getting a client's site indexed, drafting for own project, auditing competitor AI presence. However, it does not explicitly mention when not to use it or name alternative tools, 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?

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by specifying the default 'active' filter and listing returned fields, but it doesn't go beyond annotations regarding side effects or data scope. No contradiction exists.

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: first states purpose and return fields, second gives usage guidance. Every sentence earns its place, and the key verb and resource are front-loaded. No fluff or redundancy.

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

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

Given the low complexity, single optional parameter, and rich annotations, the description is complete. It lists return fields (compensating for no output schema), provides usage context, and clarifies the default filter. No essential information is missing for an agent to 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?

The single parameter include_inactive is fully described in the schema (100% coverage), so the description doesn't need to add more. The description's mention of 'active subscriptions' implicitly aligns with the default false, but it doesn't explain the parameter itself 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 verb 'List' and the resource 'the caller's active subscriptions,' with explicit scope. It also lists the return fields, making the purpose unambiguous. This distinguishes it from sibling tools like subscribe and unsubscribe.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It gives clear context but does not explicitly reference alternatives or exclusion criteria, such as using subscribe/unsubscribe instead.

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 only convey generic hints (readOnly=false, etc.), but the description adds critical behavioral details: filing without an account returns a claim_token for later status checks, rate limiting to 5 per identifier per day, free usage not counting against quota, and that the team reads digests daily. This goes well beyond what the annotations provide.

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

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

The description is long (8 sentences) but every sentence carries necessary context: purpose, usage cases, exclusions, token flow, rate limits, and quotas. It is front-loaded with the core purpose and then builds supporting details. The length is justified given the potential for misuse, so it earns a 4 rather than a 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?

For a tool with 4 parameters and no output schema, the description covers nearly every angle: what counts as feedback, how to scope the report, how the claim_token works, what happens to the feedback, and operational limits. It is comprehensive enough for an agent to know exactly how and when to invoke this tool, even with no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how to use claim_token ('pass it back later as pipeworx_feedback(...)') and by instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting prompts. This enriches the message and context parameters without fully re-explaining every field.

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.' It immediately distinguishes the tool from siblings by framing it as feedback for Pipeworx tools specifically, which no other sibling does.

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: for bugs, feature/data_gap requests, or praise. It also gives an explicit exclusion: do not report issues for tools from other MCP servers, and tells the user where to file those instead. This is textbook alternatives-and-exclusions 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?

Even though annotations already mark the tool as read-only and non-destructive, the description adds valuable context: the data is self-aggregating from an analytics engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. This goes beyond the annotations and explains the freshness and privacy characteristics.

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 statement, then structured logically: what it returns, when to use it, and how it works. Every sentence serves a purpose and adds distinct information, with no filler or redundancy.

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

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

Given the tool has only one optional parameter and no output schema, the description is complete: it covers the return contents (top tools, top packs, call volume), the data source, caching behavior, privacy, and practical use cases. No critical information is missing 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?

The schema already fully describes the only parameter 'window' with its enum values and the trade-off between shorter and longer windows. The description merely restates this without adding new semantic meaning, so it stays at the baseline of 3 for 100% schema coverage.

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

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

The description clearly states a specific action and resource: it reports what other AI agents are calling on Pipeworx, returning top tools, top packs, and call volume over a time window. It also distinguishes itself from discovery tools by framing its purpose as revealing current usage trends, not merely listing available tools.

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

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

The description provides explicit 'Useful for' scenarios, which gives clear guidance on when to use the tool. However, it does not mention when not to use it or name alternative sibling tools explicitly, so it earns a 4 rather than 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?

The annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: the fill-check logic (realizable_edge_pp ≤ 0 means 'do not trade'), the Jaccard similarity threshold for cross-event pairing, and the partition placeholder filtering. These details reveal the tool's decision-making and limitations 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 well-structured with bolded section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence carries technical meaning; however, it could be trimmed slightly without losing value. It earns a high score for organization but not a perfect 5 due to its length.

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

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

The tool has no output schema, so the description takes on full responsibility for explaining return values. It does so by specifying the response structure ('opportunities[]', 'partition_check{...}'), covering all three call modes, and addressing edge cases like low-likelihood no-arg vs event usage. The description is comprehensive for a tool of this complexity.

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

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

While the schema already describes both parameters (event and topic), the description enriches them with concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explains the behavioral difference between modes, and clarifies what input format is accepted (full URLs also work). This goes beyond the schema's basic definitions.

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

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

The description states a concrete purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies distinct modes (trending_scan, event, topic) and clearly differentiates from siblings like polymarket_fill_risk, making the tool's scope 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?

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also points to an alternative: 'For custom sizing use polymarket_fill_risk.' The fill check section explains when not to trade, covering usage boundaries thoroughly.

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 thoroughly discloses behavioral traits beyond annotations: caching behavior ('Cached 1h at the KV level'), response structure (_diagnostics with funnel counters), and caveats about edge reliability (e.g., 'your edge may already be in the price'). It also explains why partitions may be empty and provides technical details about Kelly capping and slippage. This far exceeds the annotation set (readOnly, openWorld, idempotent, non-destructive) without contradicting it.

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 and front-loaded with the core purpose. It uses headings (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and breaks down sub-sections logically. Given the tool's complexity (9 params, multiple segments, diagnostics), the length is justified. However, it is dense and could be trimmed slightly without losing critical information, preventing a 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?

With no output schema, the description fully explains the response top-level structure (by_segment, fed_candidates, _diagnostics) and the meaning of each segment. It also covers caching, parameter effects, and edge cases (empty segments, filter skips). This gives an agent all the context needed to interpret results and make decisions, making it highly complete for its complexity.

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

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

Since schema coverage is 100%, the baseline is 3. The description adds significant meaning by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining their interdependencies (e.g., min_partition_leg_kelly applies per-leg Kelly for partitions, not the parent level). It also adds practical context like slippage assumptions and how to tune filters, going beyond the schema's per-field descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also frames the intended use case ('what should I bet on today') and distinguishes from siblings by detailing model families and a unique 'TRADEABLE-EDGE KNOBS' section. The verb 'scan' + resource 'Polymarket markets' + outcome 'return opportunities' is specific and unambiguous.

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

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

The description provides clear context for when to use the tool, including a direct use case and the note that 'agents discover opportunities without paging hundreds of markets.' It also includes exclusions, such as the Fed candidates warning ('1m-T vs EFFR signal is unreliable at meeting-month horizons without paid OIS/SOFR-futures data'). However, it does not explicitly name sibling alternatives like polymarket_arbitrage, 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?

Discloses important behavioral traits beyond annotations: 60-day snapshot TTL, history starts from when snapshotting was enabled, snapshots written only on cache-miss causing gaps, decay computed from daily closes (not intraday), and signed edge values. Rich in operational context and fully consistent with the read-only, 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?

Despite length, the description is highly structured with labeled sections (Args, RESPONSE, LIMITS) and front-loaded purpose. Every sentence adds specific technical or conceptual value, with no fluff or repetition. The density is justified by the tool's complexity and absence of an output schema.

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 fully compensates by detailing the response structure: tracked[] with time-series, first_seen, trend categories, decay_pp_per_day, expired[] with lifespan_days, and snapshot_dates[] with gap semantics. It also explains limits and the meaning of signed values, making the tool self-contained 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?

The schema already covers both parameters with defaults, clamps, and enum values (100% coverage). The description restates them (days lookback default 14 max 30; window default '1wk') but adds only minor contextual framing (snapshot family), not new semantic depth. Baseline of 3 is appropriate because schema does the heavy lifting.

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 a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling polymarket_edges by focusing on persistence/decay rather than current edges.

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

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

The description provides clear context for when to use this tool: when edge age or decay matters, giving the example that a fresh wide edge and a 3-week-old wide edge are different trades. It does not explicitly name alternative tools or state when not to use it, but the purpose statement implies it complements rather than replaces current-edge 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?

The description adds substantial behavioral context beyond annotations: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), exposes per-leg fill details, and warns about 'forced_directional_risk' in basket mode. Annotations already declare readOnlyHint=true and destructiveHint=false, but the description enriches understanding of what the tool actually computes without contradicting annotations.

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

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

The description is long but dense and well-structured. It front-loads the core purpose, then distinguishes modes with clear formatting, lists outputs, and concludes with actionable usage guidance. Every sentence adds value—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?

Without an output schema, the description thoroughly enumerates return values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, capture_ratio, per-leg detail, thin_legs, etc.). It also explains the risk rationale, making it sufficient for an agent to decide whether this tool fits the task.

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?

Although schema coverage is 100% with descriptions for all four parameters, the tool description goes beyond by explaining mode semantics: how 'market' vs 'event' selects single vs basket mode, how 'side' defaults vary by mode, and how 'size_usd' is interpreted differently (spend/target proceeds vs settlement notional/shares per leg). This adds meaning not present in the schema alone.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools by naming polymarket_arbitrage and polymarket_edges as the tools it precedes, positioning itself as a risk-check complement.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (thin-book overround is not capturable) and the risk of partial fills, making when-to-use and when-not-to-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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds substantial behavioral context: it explains compatibility_warning in two specific scenarios, temporal_alignment semantics, and skipped_cross_type/subtype counters. It also warns that non-equivalent bet shapes trigger a warning instead of a false delta, providing deep transparency about edge-case behavior.

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

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

The description is long but every sentence carries information. It uses structural labels (TWO MODES, RESPONSE, SAFETY FIELDS) to organize dense content, and it front-loads the core purpose. For a tool with this complexity, the length is appropriate and 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?

The description covers the response format (leg-by-leg prices, spread[], top_spreads_pp), safety fields, temporal alignment, and skip counters, with no output schema to rely on. It also sets expectations about tradeability and compatibility warnings, making it complete for an agent to understand behavior and 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 coverage is 100% with per-parameter descriptions, so the baseline is 3. The description adds value by explaining how the parameters interact: topic is a shortcut, explicit kalshi_event_ticker and polymarket_event_slug override the mapped sides, and the examples clarify format. This goes beyond the schema's isolated parameter descriptions, earning a 4.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from siblings like polymarket_arbitrage by naming the two venues and the concept of cross-venue spread, and it details two modes (topic and explicit) plus response elements, leaving no ambiguity about what the tool does.

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 guidance on using the two modes (topic shortcuts vs. explicit ticker/slug) and provides a strong when-not-to-trust caveat ('most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable'). However, it does not name alternative sibling tools (e.g., polymarket_arbitrage) for other use cases, so it stops short of full when/alternatives guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: scoping to 'anonymous IP, BYO key hash, or account ID' and the listing behavior when omitting the key. No contradictions exist.

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, followed by usage context and scoping. Every sentence earns its place with no redundant or vague wording.

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

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

For a simple read-only retrieval tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and sibling relationships. The absence of return format details is acceptable given the tool's simplicity and the examples provided.

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

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

Schema coverage is 100% since the key parameter has a description. The description adds meaning by explaining the key is 'previously saved via remember' and provides examples of its content, going beyond the schema's minimal 'Memory key to retrieve.'

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 action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs (retrieve/list) and identifies the resource (saved memory keys). It explicitly distinguishes itself from siblings by referencing remember and forget.

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

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

The description provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It names the alternatives: 'Pair with remember to save, forget to delete.' This leaves no ambiguity about when to choose this tool over its siblings.

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

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

The description explicitly states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' indicating a persistent state mutation. However, the annotations declare readOnlyHint:true, which directly contradicts this. The annotation flags this tool as read-only while the description reveals a write side-effect, so the score must be 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?

Five sentences, all front-loaded with the core purpose and each earning its place — the example filter, the side-effect warning, and the alternative URL are all useful. 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?

With no output schema, the description compensates by listing the fields on each returned event (source, citation_uri, raw payload). It also covers filtering, read flags, and an alternative access method. This makes the tool fully understandable for an agent.

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

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

All 5 parameters are already fully described in the schema (100% coverage). The description adds a concrete type example ('sec_8k') and clarifies mark_read's effect on subsequent calls, providing meaningful 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 opens with 'Pull fired events from your subscription feed' — a specific verb and resource. It clearly differentiates from sibling tools like list_subscriptions by focusing on alert events rather than subscription definitions, and it describes the return payload.

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 tells users that 'Polls work fine' and points to an alternative endpoint 'GET registry.pipeworx.io/alerts.json for scripts and dashboards,' giving appropriate usage context. It doesn't explicitly compare with sibling tools, but it offers practical guidance on when to use this tool versus direct access.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses key behaviors: parallel fan-out to multiple sources, GDELT-to-GNews fallback on rate limits/5xx, USPTO soft-failure due to API sunset, and structured return format with `changes[]` and `total_changes`. This goes well beyond what annotations already provide.

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

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

The description is information-dense and front-loaded with example queries, making it highly useful. However, it is a single unbroken block of text; while every sentence earns its place, breaking it into short labeled segments would improve scannability. Still, it is far from verbose or redundant.

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 specifies what the user gets: structured changes grouped by source, total count, and citation URIs. It also addresses failure modes (GDELT fallback, PatentsView sunset) and parameter edge cases, making it complete for a read-only tool with such rich behavior.

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 every parameter has a description. The tool description enriches meaning by giving concrete examples for `since` (ISO date vs relative shorthand, recommended '30d' or '1m'), explaining `value` formats (ticker or CIK), and clarifying `type` restrictions. This adds substantial 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 identifies the tool as a change feed for a company over a time window, listing concrete sources (SEC EDGAR, GDELT/GNews, USPTO) and providing natural-language example queries. It also explicitly contrasts with entity_profile, making the purpose unmistakable and distinguishing it from the sibling tool.

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

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

The description gives explicit usage context with example queries and specifies when to use this tool versus entity_profile ('Use entity_profile instead when you want the static profile...'). It also clarifies fallback behavior and intended `since` values, providing strong guidance for appropriate invocation.

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

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

The description adds behavioral context beyond annotations: memory is 'scoped by your identifier', authenticated users get persistent memory while anonymous sessions retain for 24 hours. These details explain persistence semantics, which annotations do not convey. No contradictions with annotations.

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

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

The description is succinct—three sentences—and front-loaded with the primary action. Each sentence provides useful information: purpose, when to use, and key behavioral details, with 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 simple two-parameter tool with no output schema and good annotations, the description fully covers the purpose, usage, persistence, and relationship to sibling tools. It is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description gives examples of key/value content (ticker, address, preference) but these mirror the schema's examples without adding new parameter-level details. It does not enhance understanding beyond the schema.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with a specific verb and resource (key-value store). It distinguishes itself from siblings by explicitly mentioning companion tools recall and forget, 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?

It provides concrete when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It names recall and forget as alternatives/replacements, giving clear context on how this tool fits into a workflow.

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 (readOnly, idempotent, etc.), the description discloses important behaviors: graceful degradation if GLEIF/OpenFIGI fails, cascading through multiple endpoints, explicit reporting of unresolved identifiers under 'unresolved', and cross-source labeling. These add significant context not captured by annotations.

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

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

The description is long but dense with useful information—query examples, supported types, behavior notes, and fallback details. Every sentence earns its place, and the structure is front-loaded with usage guidance and examples, making it easy to scan.

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 must explain return values, and it does thoroughly: identifiers per source, unresolved field, and mention of citations for drug lookups. It covers edge cases like unavailable sources. This is complete for an agent to invoke the tool correctly 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?

The schema already provides descriptions, but the tool description adds concrete examples and accepted formats for the 'value' parameter (ticker 'AAPL', CIK with leading zeros, brand/generic names). It also clarifies the semantics of each enum value ('company' vs 'drug'), going well beyond the schema's 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 states the tool resolves user-spoken names to canonical identifiers, with specific verbs like 'resolve' and resources like CIK, LEI, etc. It distinguishes itself from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID', which sets it apart from other tools like entity_profile.

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

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

The description provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and elaborates on supported input types (company/drug) with examples. It also explains that the tool replaces 2-3 manual lookups, making its role clear relative to alternatives.

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

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

Description discloses that the tool probes each entity, ranks by score, and surfaces most/least recognized, adding orchestration detail beyond the readOnlyHint and idempotentHint annotations. Return format (ranked list with score, confidence, signal density) is also stated.

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

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

Three sentences, front-loaded with main purpose, including a practical example and expected return fields. No redundant wording or repetition of schema/annotations.

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 100% schema coverage, annotations covering safety, and a description that explains purpose, use case, orchestration, and output shape, this is complete for a read-only comparison tool. No missing critical information like authentication or rate limits, but those are less relevant given the annotations.

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 description doesn't need to explain parameters. It mentions 'your brand + N competitors' matching the entities parameter, but adds no extra meaning beyond what the schema already states (e.g., first entry as subject). 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 'Compare' with resource 'AI visibility across multiple entities', clearly defining a side-by-side competitive comparison. It distinguishes from sibling tools like ai_visibility_check (single-entity) and compare_entities (generic) by specifying it probes with ai_visibility_check and ranks by score.

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?

Description explicitly mentions usefulness for 'competitive AI-marketing audits' with a concrete example, and names ai_visibility_check as the underlying mechanism, implying this is the multi-entity version. It doesn't explicitly say when not to use it, but context is clear enough.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds meaningful behavioral context: it fans out to multiple APIs, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s, with sources_failed listing timeouts. This gives the agent a clear picture of reliability and latency.

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 and front-loaded, starting with a clear one-sentence summary followed by usage, output, scope, and failure behavior. It is slightly long, but each sentence carries information that supports agent decision-making, so it 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?

Without an output schema, the description compensates by enumerating the summary fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory details, links, and alternative versions. It also covers edge cases (NPM-only v1, timeout behavior), making it complete for agent use.

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

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

Schema description coverage is 100%, so the description doesn't need to repeat parameter details. The description adds no additional semantics beyond what the schema already provides (name, version, scoped packages, defaulting), which meets the baseline for high schema coverage.

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

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

The description explicitly states it is a composite check for whether to add an npm package, listing specific data sources (deps.dev and bundlephobia) and the type of output. This clearly distinguishes it from sibling tools like scan_competitor_ai_presence, which targets a different subject.

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 'Use whenever' guidance with example queries ('is X safe / popular / small' or 'what does adding lodash cost me'). It also states exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', pointing to an alternative approach for other ecosystems.

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 hints, eliminating safety concerns. The description adds rich behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K character cap with truncation flagging, and output format (passages with offsets and scores). No contradictions with annotations.

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

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

The description is concise and front-loaded: it starts with the core function, then gives use case, pairing, and technical details. Every sentence contributes to understanding—no fluff or repetition. Despite being ~130 words, it packs substantial guidance without rambling.

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 modest complexity (3 params, no output schema but described), the description covers input, output shape, operational limits, and relationship to a sibling tool. It fully compensates for the lack of an output schema by stating exactly what results look like (passages, offsets, scores).

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, so baseline is 3. The description adds value by giving concrete examples for the 'text' parameter (SEC 10-K body, article) and clarifying the 'limit' behavior via 'top-N passages with character offsets and similarity scores'. It also notes the 200K character cap, which is not in the schema, enriching parameter understanding.

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

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

The description clearly states the tool does semantic search INSIDE a fetched record, with specific verb and resource. It distinguishes itself from siblings like ask_pipeworx_grounded by emphasizing that it searches within text the agent already pulled, rather than over a whole document or knowledge base.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative pattern: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and how-it-relates-to-alternatives 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 discloses significant behavioral traits beyond the annotations: authentication requirements, non-persistence for anonymous/BYO, phone verification and SMS caps, and the always-on feed. It complements the annotations (readOnlyHint=false, idempotentHint=true) without contradicting them.

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

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

The description is front-loaded with the core action and then provides well-organized details on requirements, types, and delivery. It is dense but every sentence serves a purpose, 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?

Given the tool's complexity (nested objects, multiple types, no output schema), the description covers all necessary aspects: purpose, prerequisites, type-specific parameters, delivery options, and the return value. It is sufficient for an agent to invoke correctly.

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

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

The schema already provides 100% parameter descriptions with examples, and the tool description reinforces this with extra semantics (e.g., item code '5.02' = officer change) and delivery channel details. While this adds some value, much of the parameter information is redundant with the schema, so a 4 is appropriate.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return value ('Returns the new subscription id'). This is a specific verb+resource combination that clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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 usage context: it requires a Pipeworx OAuth account, explains supported subscription types and delivery channels, and notes the always-on feed alternative. However, it does not explicitly reference sibling tools for alternative use cases (e.g., list_subscriptions), so it stops short of a perfect guidance 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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context about what it returns (category-bucketed example questions with exact tool and argument shape) and how it behaves (call with no arguments for full spread, or pass topic to focus). This goes beyond the structured fields and helps the agent anticipate output.

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

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

The description is more than two sentences but each sentence carries weight: example queries, return format, call patterns, and usage priority. It is structured with a clear flow, though slightly verbose; it could be tightened without losing meaning.

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

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

The description fully explains the tool's input (optional topic), output (category-bucketed examples with tool+argument shape), and positioning (first step for onboarding). With no output schema, this description compensates well by detailing what the agent will receive and how to use the tool, making it complete for its simple single-parameter signature.

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 covers the single optional 'topic' parameter with a complete list of allowed values. The description adds only redundant examples ('finance', 'pharma', 'betting') and does not introduce new semantic details, so it falls at the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: the onboarding entry point for agents that want to know what to ask Pipeworx. It specifies the resource (Pipeworx capabilities) and the action (suggesting category-bucketed example questions), and distinguishes it from siblings by positioning it as the 'first' step.

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 FIRST when you do not yet know what Pipeworx can do for you', giving a clear when-to-use guideline. It also points to alternatives (ask_pipeworx, entity_profile, compare_entities) for learning how to call meta-tools, and provides example user intents that trigger the tool, making the usage context very 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?

Beyond annotations, the description discloses the soft-delete behavior ('deactivated, not deleted'), the persistence of historical events via recent_alerts, and ownership enforcement. This adds significant context not available from annotations alone.

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

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

The description is two sentences, front-loaded with the primary action, and every phrase adds value. It communicates the action, a constraint, and the side-effect clearly without redundancy.

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

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

For a simple single-parameter tool with high schema coverage and helpful annotations, the description covers the essential behavioral aspects (ownership, soft delete, historical availability). No output schema is needed for this operation, and the description is sufficient for an agent to use it correctly.

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

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

The schema already describes the id parameter fully, including that it is a uuid returned by subscribe. The description does not add additional parameter details, so it meets the baseline for high schema coverage but adds minimal extra semantic value.

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

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

The description starts with 'Cancel a subscription by id,' clearly stating the action and resource. It distinguishes itself from sibling tools like subscribe and list_subscriptions by addressing the cancellation operation, and the ownership constraint adds specificity.

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 conveys when to use the tool: to cancel a subscription by id. It also notes ownership enforcement, which is a prerequisite. It does not explicitly contrast with alternatives, but the sibling context makes it clear this is the cancellation counterpart to subscribe.

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

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

Annotations declare read-only, open-world, idempotent, and non-destructive hints. The description adds crucial behavioral nuances beyond this: the distinction between could_not_verify (check failed, not evidence) and unsupported (no source found), the structured vs grounded pipeline behavior, and the warning that could_not_verify must not be shown as evidence. This is rich, actionable context.

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

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

The description is long but structured and purposeful. It starts with trigger phrases, then explains usage, pipeline routing, return values, and error semantics in a logical order. Every section adds necessary detail for a complex tool, though it is slightly verbose in places (e.g., the 'IMPORTANT for callers' note could be tightened).

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers what is needed: the two execution paths, exact return verdict types, the actual value and citation format, and the meaning of error-related outcomes. It effectively equips an agent to decide when to invoke it and what to expect.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds value for tolerance_pct by explaining override semantics, hallucination detection use, and default behavior (implied by wording, capped at 5). This moves it above baseline, though claim's semantic is adequately covered by examples in the schema.

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

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

The description clearly identifies the tool's purpose: verifying natural-language factual claims against authoritative sources. It uses strong, specific language ('fact check', 'verify the claim') and distinguishes itself from siblings by stating it replaces 4–6 sequential calls and by detailing two distinct verification paths (SEC EDGAR for financial claims, grounded pipeline for others).

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 explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and differentiates between company-financial and other factual claims. However, it does not explicitly name alternative tools or provide 'when not to use' guidance, so it misses the full bar for 5.

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