Biorxiv

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds cost implications (Anthropic requires BYO key) and default model behavior, providing useful context beyond annotations without contradiction.

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

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

Three sentences with no wasted words. The first sentence states the core action and output, the second adds functional details (default model, API key), and the third provides use cases. Well-structured and front-loaded.

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 adequately explains return format (per-model score, confidence, signals, raw_response, combined view) and scoring range (0-100). It covers the main aspects but could include error handling or rate limits for 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default model for 'models' parameter, the cost implication for '_apiKey', and the disambiguation purpose of 'context', going beyond the schema descriptions.

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

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

The description uses specific verb ('Probe') and resource ('LLMs for what they know about a business / brand / product / topic') and clearly states the output (visibility score 0-100). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on general AI visibility rather than just competitors.

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 cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default model and optional API key usage. However, it does not explicitly contrast with similar sibling tools like scan_competitor_ai_presence, and lacks when-not-to-use guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: routes to 4,862 tools, returns structured answer with citation URIs, works on all tiers, one fast call. Does not mention any error handling or rate limits, but the transparency is good overall.

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 a clear hierarchy: preference note, capabilities, usage guidance, examples, and escalation paths. It is front-loaded with the most important message. Minor redundancy (e.g., 'one fast call' and 'works on every tier' could be merged).

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 broad scope, the description covers purpose, usage context, examples, and alternatives comprehensively. It explains what the tool returns (structured answer with citation URIs) even though no output schema is provided. No gaps identified.

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

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

Schema coverage is 100% with clear description for the question field and its aliases. Description adds value through examples of effective questions but does not provide additional semantic guidance beyond what the schema offers. Baseline 3 is appropriate.

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

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

Description clearly states it answers factual questions using authoritative structured data from thousands of sources. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning as the default fast entry point.

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 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. Provides clear alternatives for specific needs: grounded for verbatim evidence, deep_research for broad queries. Gives concrete examples of when to use.

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

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

Description adds details beyond annotations: extraction process, return structure (including refusal reasons), and cost trade-off. 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?

Front-loaded with key purpose, then provides essential details. Slightly verbose but every sentence adds value; structured well.

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

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

Covers input, behavior, output format (success and refusal), usage guidance, and cost. No output schema but described in text. Adequate for 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 covers 100% of parameters with descriptions; description only reiterates that q, text, input, query, prompt are aliases for question, adding minimal value beyond schema.

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

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

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, differentiating from sibling ask_pipeworx by emphasizing extraction using only tool results and explicit refusal reasons.

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 recommends use when answers will be quoted/cited/acted on and the agent must not invent facts, and advises preferring ask_pipeworx for casual lookups due to extra cost.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. Description adds extensive behavioral details: fan-out, resolver contract, safety short-circuits, closed market handling, spread warnings, resolution-rule risk, etc. No contradiction.

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

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

Long but well-structured with headers. Covers all details but could be slightly more concise. Earns its length given 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?

No output schema, but description thoroughly explains response shapes, resolver contract, parent_event extractor, news fields, and safety mechanisms. Very complete for a complex tool.

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

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

Schema coverage is 100% but description adds value: market parameter examples, depth enumeration with defaults, include_raw explanation. Enhances understanding beyond schema.

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

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

Clearly states it researches a Polymarket bet by pulling Pipeworx data. Specifies input types and process. Distinguishes from siblings like polymarket_edges and polymarket_arbitrage.

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

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

Explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. Context implies appropriate use cases. Alternatives exist in sibling list.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description explains exactly what data is pulled per entity type (e.g., latest 10-K financials for companies, FAERS/ FDA/trial counts for drugs), how off-calendar fiscal years are handled, sorting by primary metric, and the return format including citation URIs. No contradiction with annotations.

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

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

Well-organized with trigger phrases upfront, then behavioral details, then parameter specifics. Every sentence adds value, but slightly longer than strictly necessary. Could trim minor redundancies like the enumeration in the first sentence versus later examples.

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

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

Despite no output schema and moderate complexity (two entity types, different data sources), the description covers output format (paired data + citation URIs), sorting behavior, and even notes it replaces 8-15 sequential lookups. An agent has all needed context for correct invocation.

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

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

While schema has 100% coverage, the description adds significant value: concrete examples for values (e.g., [AAPL,MSFT] for companies, [ozempic,mounjaro] for drugs), and clarifies what each type returns (company: specific financial metrics; drug: adverse events, approvals, trials). This goes far beyond schema descriptions.

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

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

Clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. Gives multiple example trigger phrases (Compare X and Y, X vs Y, rank these companies) and explicitly distinguishes it from sequential lookups.

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

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

Provides explicit 'ALWAYS PREFER over sequential single-pack lookups' guidance. Shows when to use (comparing entities) and what not to do (sequential lookups). The example queries help an agent recognize appropriate contexts.

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

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

Description adds significant behavioral context beyond annotations, including account requirement, depth levels' internal behavior (quick/standard/thorough with facet counts, hop logic, contradiction pass), expected response times, and output structure (gaps, contradictions, citations). 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 long but every sentence adds necessary information. It front-loads the critical account requirement. Could be slightly more structured with bullet points, but still well-organized and efficient 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 (parallel research, multiple depth levels, output with gaps/citations), the description is remarkably complete. It explains all key aspects: prerequisites, behavioral differences across depth, output expectation, time limits, and sibling alternatives. No output schema exists, so the description adequately fills that gap.

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

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

Schema coverage is 100% with good descriptions. Description adds value by explaining what each depth level does in terms of facets, hops, and time expectations, and clarifies that the question parameter accepts broad/multi-part natural language. 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 it performs grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets. It distinguishes from sibling tools like ask_pipeworx by specifying it's for broad/multi-part questions, while ask_pipeworx is for single lookups or breaking news.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not to use (single lookup: use ask_pipeworx; breaking/current news: prefer ask_pipeworx). Also mentions account requirements and free vs paid tiers.

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

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

Annotations already declare the tool as read-only, idempotent, and open-world. The description adds that queries can be by DOI or date range, which is consistent. No additional behavioral details (e.g., pagination behavior, rate limits) are provided beyond the schema.

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

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

The description is a single, efficient sentence that front-loads the purpose. It contains no redundant words, though it could slightly expand to improve clarity without significant bloat.

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 presence of a full output schema and 100% schema coverage for parameters, the description only needs to state the core functionality. It does so adequately, making the tool's purpose clear without missing critical context.

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

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

Schema coverage is 100%, with each parameter described clearly. The description mentions the two query modes (DOI or date), adding conceptual grouping but no syntax details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states that the tool returns preprint metadata by DOI or date/date range, which clearly indicates the resource and operation. However, it does not differentiate from sibling tools like 'published' or 'summary' that might also retrieve metadata.

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

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

No guidance is given on when to use this tool versus alternatives such as 'published' or 'summary'. The description only states what the tool does without specifying context or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that results include full input schemas with curated examples and are ready to call directly, providing extra behavioral context beyond annotations.

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

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

The description is concise yet comprehensive: it starts with purpose, lists domains, explains output behavior, and gives usage advice. Every sentence is informative without redundancy.

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

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

Given the tool's discovery role and the richness of annotations and schema, the description fully covers what an agent needs: when to call, what to expect (top-N tools with full schemas), and how parameters work. No gaps.

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

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

Schema coverage is 100%, and the description elaborates on the primary parameter 'query' with examples, aliases (q, task, search, description), and natural language usage, adding significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous data domains and gives concrete examples, distinguishing it from sibling tools that perform specific operations 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: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also specifies use cases like browsing, searching, and discovering tools for specific domains, leaving no ambiguity.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds valuable behavioral context: parallel execution, specific sources and their status (e.g., USPTO sunset May 2025 with soft-fail, GDELT→GNews fallback), and return structure. No contradictions.

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

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

The description is longer but well-structured: front-loaded with example queries, then structured explanation of sources and returns. Each sentence adds value, though slightly verbose. Conciseness is good given 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 (multiple data sources, fallbacks, specific constraints), the description covers all necessary context: what it returns, how to use it, limitations (no names, USPTO sunset), and parallel execution. No output schema exists, but return fields are adequately described.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description mirrors the schema's parameter info (e.g., names not supported) but doesn't add new semantics beyond what's already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating a full cross-source profile of a US public company. It provides example queries like 'Tell me about X' and lists specific data sources (SEC, XBRL, USPTO, etc.) and return fields, distinguishing it from siblings like resolve_entity.

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

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

Explicitly states to prefer this tool over chaining single-pack lookups for holistic views. Also notes that names require resolve_entity first, and that tickers or CIKs are accepted. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds that it deletes by key, but doesn't disclose additional behaviors like error handling for missing keys or permanence beyond destructive. No contradiction with annotations.

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

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

Two sentences, front-loaded with the action, no wasted words. Efficient and clear.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers purpose, usage context, and tool relationships. The annotations are thorough, making the description complete.

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

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

Schema coverage is 100% with a clear parameter description 'Memory key to delete'. The description does not add new semantics; 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 clearly states the action 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings '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?

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also recommends pairing with 'remember' and 'recall', guiding the agent on 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?

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds context about fetching the page, extracting title/description/key links, and emitting standard markdown, which is consistent and adds value beyond annotations.

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

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

The description is concise, using two sentences plus a bullet list of use cases. It is front-loaded with the main purpose and contains no unnecessary information.

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

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

Given the low complexity of the tool (2 params, no output schema), the description covers input, process, and output adequately. It explains the return format and use cases. Missing error handling or rate limits, but annotations partly address safety.

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

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

Schema covers both parameters (url and max_links) with descriptions, achieving 100% coverage. The description hints at extraction behavior but does not add new semantic information beyond what the schema provides.

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

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

The description clearly states that the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes itself from siblings by focusing on this specific output format and use case.

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

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

The description provides explicit use cases (getting a client's site indexed, drafting llms.txt, auditing competitor indexing) but does not mention when not to use the tool or list alternatives. The sibling tools suggest related capabilities but are not contrasted.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's addition of return fields adds some value but doesn't disclose other behavioral traits like pagination. It is consistent with annotations.

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

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

Two concise sentences front-load the core purpose and usage guidance, with zero unnecessary words.

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

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

For a simple list tool with one parameter and no output schema, the description is largely complete. It lacks mention of pagination or result limits, but given the simplicity, it meets the minimum for effective 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 coverage is 100%, and the parameter description in the schema already explains the single parameter. The description does not add new meaning beyond the schema.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifies the returned fields, and distinguishes it from sibling tools like subscribe and unsubscribe by focusing on listing.

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

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

The description advises using this tool before adding more subscriptions or to find an ID for cancellation, providing clear context for appropriate use. It implicitly suggests when not to use it (for actions other than reviewing).

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 rate limits (5 per identifier per day) and that it's free, which supplements the annotations. No contradictions; adds important behavioral context beyond the structured data.

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

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

Four sentences, front-loaded with the main action, no fluff. Every sentence adds value—usage, anti-pattern, impact, and limits.

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

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

Given the tool's simplicity (3 params, 2 required, nested object), the description covers when, what, and how to use it. No output schema needed for a feedback tool. Complete.

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

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

Schema coverage is 100%, but the description adds value by advising users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts. This clarifies the expected format beyond schema enum 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: reporting bugs, missing features, or praise. It distinguishes from sibling tools, none of which are for feedback. The specific verb 'tell' and resource 'Pipeworx team' make it obvious.

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

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

The description provides explicit guidance on when to use (bug, feature/data_gap, praise) and what not to include (end-user prompts). It lacks explicit alternatives but is clear enough for the context.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral details: self-aggregating from CF analytics engine, no PII, cached 5min-1h depending on window. No contradiction with annotations.

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

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

The description is a single paragraph but well-structured: first sentence states output, then bullet-point-like numbering for use cases, then technical details. It is fairly concise, conveying necessary information without verbosity.

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

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

No output schema, but the description mentions what is returned (top tools, top packs, total call volume). It explains caching and data source. For a simple tool with one optional param, it is adequately complete, though output format could be more explicit.

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

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

Schema coverage is 100% with a fully described enum parameter 'window'. The description adds context beyond the schema: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances 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 it returns 'top tools, top packs, and total call volume' over a recent window, using the verb 'calling on Pipeworx' to indicate usage trends. It distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on trending and aggregation.

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

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

The description explicitly lists three numbered use cases: discovering hot data sources, confirming canonical choice, and seeing use case alignment. It implicitly suggests not to use it for specific queries (use ask_pipeworx instead). Clear context but lacks explicit when-not-to-use.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false. The description adds detailed behavioral context: partition-check logic, Jaccard similarity filter, placeholder filter, and fill check using depth data. 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 well-structured and front-loaded with the core purpose, but it is lengthy (multiple paragraphs). While each sentence adds value, some redundancy exists (e.g., repeated mention of fill check). Still, it is clear and organized.

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 comprehensively covers the response structure (opportunities array with fields), fill check details, and edge-case handling. It fully equips an agent to understand the tool's behavior and outputs.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: it explains the effect of each parameter with examples (e.g., event slugs like 'fed-decision-may-2026') and describes the modes in detail. This enables the agent to use the parameters correctly.

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

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

The description explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It provides a specific verb and resource, and distinguishes from sibling tools like polymarket_edges by mentioning related tools and the fill 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 description clearly explains when to use each argument: no args for trending scan, 'event' for per-event, 'topic' for cross-event. It gives recommendations and contrasts modes, e.g., 'Cross-event mode catches ... that single-event misses.' This provides excellent guidance for the agent.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds substantial behavioral context beyond these: caching at 1h KV level, detailed model families and their underlying logic, the exclusion of Fed bets due to data unreliability, and the structure of response diagnostics that reveal why segments may be empty. There is no contradiction with annotations.

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

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

The description is long but highly informative, with a front-loaded purpose statement. Every section adds necessary detail for a complex tool with three model families and multiple parameters. However, some internal methodological details (e.g., specific alpha values per sport) could be abbreviated or moved to documentation without losing essential guidance.

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

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

Given the absence of an output schema, the description thoroughly details the response structure (top-level segments, diagnostics, Fed bets handling) and explains edge cases (e.g., why partition arbs return kelly_fraction_half=0 at parent level). It covers all 9 parameters, tradeable-edge knobs, and even the caching policy, making it effectively self-contained for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how parameters like min_liquidity and max_spread_pp function as 'tradeable-edge knobs' and how slippage_pp interacts with edge calculation. It also clarifies the interplay between min_kelly and min_partition_leg_kelly for different opportunity types, providing semantics beyond the schema descriptions.

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

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

The description clearly identifies the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb-resource pair ('scan and return opportunities') and distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on edge opportunities driven by Pipeworx disagreement across multiple model families.

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

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

The description explicitly states the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides guidance on when to adjust knobs (e.g., min_liquidity, max_spread_pp) to filter tradeable edges. However, it does not explicitly exclude or compare to sibling tools like 'polymarket_arbitrage' or 'bet_research', leaving some ambiguity about when to use alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, so safety is clear. The description adds valuable context: history depth bounded by 60-day TTL, snapshots from when enabled, and decay computed from daily closes (not intraday). This enhances transparency 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 comprehensive but slightly verbose. It is well-structured with labeled sections (ARGS, RESPONSE, LIMITS) and front-loaded with purpose. Every sentence adds value, though some trimming could improve conciseness.

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

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

The tool has no output schema, so the description fully compensates by detailing the response structure: tracked[] with fields like edge_pp_net time-series, first_seen, trend, decay_pp_per_day; expired[] with lifespan_days; snapshot_dates[]. It also covers important context (gaps, TTL limits). This is complete for a complex data tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context: default values (days=14, window='1wk'), clamp for days, and explains window as 'snapshot family' and days as lookback. This goes beyond the schema, justifying 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 clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' It uses specific verbs (persistence, decay) and distinguishes from siblings like polymarket_edges by focusing on time-series and decay, not just 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 on when to use the tool (e.g., assessing edge quality over time, noting that a 3-week-old wide edge is different from a fresh one). However, it does not explicitly mention when not to use it or list direct alternatives, so it's slightly below a perfect score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral details like walking the order-book ladder, output fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and risk warnings about thin legs and directional risk. No contradiction with annotations.

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

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

The description is detailed but well-structured with bold headings for modes and bullet points for output. Every sentence adds value, though it is somewhat lengthy. Could be slightly more concise without losing clarity.

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

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

Given the complexity (two modes, many output fields, no output schema), the description is complete. It covers purpose, parameter behavior, output fields, edge cases (thin_legs, forced_directional_risk), and usage warnings, leaving no critical gaps.

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

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

Schema coverage is 100% so parameters are documented. The description adds meaning beyond schema by explaining how parameters behave differently in single-market vs basket mode (e.g., default side determination in basket based on partition sum, interpretation of size_usd).

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with specific modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk and slippage.

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

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

Explicitly says when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why partial fills convert arb into directional risk, providing clear guidance on usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond by detailing compatibility_warning scenarios, temporal alignment checks, skipped leg reasons, and the meaning of response fields. This adds substantial behavioral context not captured in 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 thorough but slightly verbose, using multiple paragraphs. However, every sentence adds essential information, and the structure (introduction, modes, response, safety fields) makes it easy to parse. A minor reduction for length, but still effective.

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

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

Despite no output schema, the description explains the response structure (leg-by-leg prices, matched spreads, safety fields) in enough detail for the agent to understand what to expect. It also covers edge cases like temporal misalignment and shape mismatches.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds examples, explains the two modes, and provides the list of valid topic values. This provides richer context than the schema alone, helping the agent construct correct parameter values.

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 that the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It explains the two modes (topic shortcuts and explicit tickers) and distinguishes the tool from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explicitly outlines when to use each mode (topic vs. explicit) and warns that most pre-mapped topics return compatibility warnings, implying that users should verify before trading. It also suggests that real arbitrage is rarer than the shortcut list implies, setting clear expectations.

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 no behavioral detail beyond what the annotations already declare (readOnlyHint=true, idempotentHint=true, etc.). It does not discuss pagination, rate limits, or any other side effects.

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 short (one sentence) and front-loaded, but it sacrifices information for brevity. It could be improved by adding a few more words without becoming verbose.

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 the presence of an output schema, the description lacks essential context about how to use the parameters (e.g., date format, server options). It leaves the agent guessing about how 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?

With 0% schema description coverage, the description must explain the three parameters (cursor, server, date_or_range). It fails to do so, providing no hints about their meaning, format, or required values.

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

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

The description clearly states what the tool returns: preprints that have been published in a peer-reviewed journal. The name 'published' reinforces this. However, it lacks a verb like 'retrieve' or 'list', making it a noun phrase rather than an explicit action.

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

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

No guidance is provided on when to use this tool versus its siblings (e.g., 'publisher', 'details', 'summary'). There is no mention of context, prerequisites, or 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, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond the semantic purpose, missing opportunities to note pagination, rate limits, or other traits.

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

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

Single sentence, no redundant words, and includes an example. Could be slightly expanded without harming conciseness, but currently efficient.

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

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

Despite an output schema existing, the description is too minimal to fully equip an agent. With 4 parameters (3 required) and only 25% schema coverage, the description should detail parameter semantics and usage context more thoroughly.

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

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

Schema description coverage is low (25%); only 'prefix' has a description in the schema. The tool description does not explain 'server' or 'date_or_range', despite the example implicitly showing them. It fails to compensate for the schema gaps.

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

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

The description clearly states the tool retrieves preprints published by a given DOI prefix, with a helpful example. It distinguishes the main purpose but does not explicitly differentiate from the sibling 'published' 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?

No guidance on when to use vs. alternatives like 'published'. No exclusion criteria or context provided, leaving the agent to infer usage without explicit direction.

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 and idempotent behavior. The description adds important behavioral context: scoping to the user's identifier and the ability to list all keys by omitting the argument, which is not covered by annotations.

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

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

The description is concise with three sentences, each earning its place. The first sentence delivers the primary action, the second provides purpose and examples, and the third explains scoping and relationships. No wasted words.

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

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

Given the low complexity (1 optional parameter, no output schema) and presence of two usage modes, the description is complete. It covers both retrieval modes, scoping, examples, and links to sibling tools. No significant gaps.

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

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

Schema description coverage is 100%, providing a baseline of 3. The description adds meaning beyond the schema by explaining the effect of omitting the 'key' parameter and giving concrete examples of typical memory keys (ticker, address, notes).

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

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

The description clearly states the tool retrieves a saved value or lists all keys when the key is omitted. It uses specific verbs and distinguishes between two modes, and implicitly differentiates from siblings '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 gives clear context for use: to retrieve previously stored context without re-deriving it. It mentions pairing with 'remember' and 'forget' but does not explicitly state 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?

Although the description transparently discloses the mark_read side effect ('Set mark_read:true to flag returned events read so the next call only shows newer ones'), this contradicts the annotations (readOnlyHint: true, idempotentHint: true). According to scoring rules, contradiction yields a score of 1.

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

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

The description is four sentences, each adding meaningful information. It starts with the core purpose, explains return fields, filtering, mark_read behavior, and an alternative access method. No superfluous content; front-loaded and efficient.

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

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

With 5 parameters and no output schema, the description adequately covers what is returned (source, citation_uri, payload) and key behaviors (mark_read). Schema descriptions cover parameters like limit and unread_only. Minor gap: no mention of the unread_only filter's purpose beyond schema, but overall complete for a read tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the effect of mark_read ('next call only shows newer ones') and giving an example for type ('sec_8k'). This practical context goes beyond the schema 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 clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies what is returned (source, citation_uri, raw event payload) and mentions filtering options. This clearly distinguishes it from sibling tools like list_subscriptions, which manage subscriptions rather than retrieving events.

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

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

The description implies when to use this tool (to get recent alerts) but does not explicitly contrast with alternatives. It mentions that polling works fine and provides an alternative URL for scripts/dashboards, but no guidance on when to avoid this tool or comparisons to siblings. Usage guidelines are minimal.

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

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

Annotations already indicate safe, idempotent, read-only behavior. The description adds significant behavioral context: the tool fans out to multiple sources in one parallel call, handles fallback from GDELT to GNews when rate-limited, and notes that the PatentsView API sunset is handled gracefully. This goes well beyond what annotations provide.

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

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

The description is concise but packed with valuable information. It front-loads with query examples, then explains the data sources, parameter usage, and fallback logic. Every sentence adds clarity without redundancy. 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?

Despite the tool's complexity (multiple data sources, fallback, relative dates), the description thoroughly covers input, behavior, and output. It mentions the return structure (changes grouped by source, total_changes, citation URIs) even without an output schema. It also cross-references the sibling tool appropriately.

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 parameter descriptions. The description adds extra meaning: explaining `since` accepts ISO dates or relative shorthand with examples, and `value` can be ticker or CIK. It also explains fallback behavior for GDELT. While schema already covers basics, the description enhances 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's purpose: providing a change feed for a company by aggregating data from SEC EDGAR, GDELT/GNews, and USPTO. It explicitly distinguishes itself from the sibling tool 'entity_profile', which serves a different use case (static profile). The verb 'change feed' and examples like 'What's new with X' make the purpose immediately obvious.

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 examples ('What's new with X', 'latest on Y', etc.) and when-not-to-use guidance ('Use entity_profile instead when you want the static profile'). It also explains the `since` parameter usage and fallback behavior, giving clear context for agent decision-making.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds context about key-value scoping by identifier, persistence differences for authenticated vs anonymous sessions (24 hours), and storage semantics. No contradictions; the description enriches the safety profile beyond annotations.

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

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

The description is well-structured with the core purpose first, followed by usage context and pairing notes. All sentences contribute useful information without redundancy. Slightly verbose but efficient for the information conveyed.

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

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

Given the tool's simplicity (2 required params, no output schema), the description covers all necessary aspects: purpose, usage triggers, storage details, and integration with sibling tools. It fully prepares an agent to use the tool correctly.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description reinforces naming conventions (e.g., 'subject_property') and the nature of the value, but adds no fundamentally new information beyond the schema.

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

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

The description starts with a clear action verb 'Save data' and specifies the resource 'the agent will need to reuse later'. It explicitly distinguishes from sibling tools by mentioning 'recall' and 'forget', making the tool's role 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 guidance on when to use the tool: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also references alternative tools ('Pair with recall to retrieve later, forget to delete').

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, indicating a safe read operation. The description adds significant value by explaining the internal cascading lookup process ('Each call cascades through several lookup endpoints internally') and detailing the return structure for each type (e.g., ticker, CIK, company name, citation URI). It does not mention rate limits or authentication, but the annotations cover the safety profile, making the description complementary.

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-organized, starting with user-facing examples, then stating the core purpose, followed by detailed type breakdowns. Every sentence serves a purpose—no filler. It could be slightly more concise by tightening the type details, but overall it is efficient and front-loaded with the most important information.

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

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

Given the absence of an output schema, the description compensates by describing the return fields for each entity type (including citation URIs). It mentions the cascading behavior and auto-disambiguation. It does not cover error scenarios (e.g., ambiguous names) or edge cases, but for a resolution tool with good annotations, it provides a complete enough picture for an AI 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?

Schema coverage is 100%, so the schema already documents both parameters. The description enriches this by providing concrete examples of acceptable values (e.g., 'AAPL', '0000320193', 'ozempic') and explaining how each type returns results, which indirectly clarifies the data expectations. It adds meaningful context beyond the schema without repeating 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 clearly states the tool's function: resolve user-spoken names to canonical identifiers required by other tools. Concrete examples (e.g., 'What's the ticker for…') and a strong verb ('resolve') establish the purpose unambiguously. It distinguishes itself from siblings by declaring 'Use FIRST whenever you have a name but need an ID', which contrasts with sibling tools that likely require IDs as input.

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

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

The description explicitly advises when to use the tool ('Use FIRST whenever you have a name but need an ID') and lists supported types. It does not explicitly state when NOT to use it or mention alternatives, but the context of sibling tools (like 'compare_entities', 'entity_profile') that require IDs implies the tool is not needed when an ID is already known. The guidance is strong but could be more explicit about exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds behavioral context: probes each entity with ai_visibility_check, ranks, surfaces results. No contradictions.

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

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

Three sentences, front-loaded with purpose, no redundant information. Every sentence adds value.

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

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

No output schema, but description explains return format (ranked list with score, confidence, signal density). Covers parameters and tool behavior completely.

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

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

Schema coverage is 100% so baseline 3. Description adds value by specifying array size 2-8, first entry as subject, and usage hints for models and _apiKey.

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 states specific verb 'Compare AI visibility', resource 'multiple entities', and provides concrete outcome: ranks by score, surfaces most/least recognized. Clearly distinguishes from sibling ai_visibility_check which is a single probe.

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 use case 'competitive AI-marketing audits' and example question. Implicitly suggests not to use for single entity (use ai_visibility_check instead). Could be more explicit about when not to use.

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

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

Annotations already declare safety (readOnly, idempotent, not destructive). The description adds critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed will list timeouts. This goes beyond what annotations provide.

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

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

Well-organized: front-loads composite purpose, then details fan-out, return fields, and limitations. Slightly long but every sentence earns its place; could trim minor redundancy.

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

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

Despite no output schema, the description fully explains the return structure (summary block, advisories, links, alternatives), ecosystem constraints, and graceful degradation. No gaps for a composite read-only tool.

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

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

Schema covers both parameters at 100% (baseline 3). The description adds value by noting scoped packages are accepted and version defaults to latest, plus explains how parameters drive the composite call.

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

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

The description clearly states it is a composite check for 'should I add this npm package' that combines data from deps.dev and bundlephobia. It distinguishes itself from sibling tools like deps.dev:version for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also specifies ecosystem limitations (NPM only in v1) and mentions alternatives for PyPI/Maven/Cargo/Go.

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 the embedding model (BGE-base-en), similarity metric (cosine), chunking method (500-char overlapping windows), and the character cap of 200K with truncation flagging. This goes beyond the annotations (which are all true/non-destructive) to add valuable behavioral details.

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 immediate value proposition. It is around 100 words, but each sentence adds significant detail. Minor redundancy exists (e.g., 'max ~200K chars' repeated), but overall it is efficient and well-structured.

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

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

Despite having no output schema, the description explains what the tool returns (top-N passages with character offsets and similarity scores). It covers use case, behavior, limitations (cap, truncation), and even mentions a companion tool. For a 3-parameter tool, this is comprehensive.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by providing example queries and clarifying the purpose of each parameter beyond the schema descriptions, such as the 'text' max length and 'limit' default.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using phrases like 'INSIDE a fetched record' and 'search_within'. It distinguishes itself from sibling tools by specifying it works on already-fetched text and pairs with ask_pipeworx_grounded, indicating a unique role.

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 when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded for grounding. It gives clear context but does not explicitly state when not to use it or list alternatives, only the complementary 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?

The description adds significant behavioral context beyond annotations: return value (subscription id), OAuth requirement, type-specific examples, delivery channel constraints (SMS cap, webhook signing, auto-disable), and that webhook secret is returned once. 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 comprehensive but well-structured: purpose, prerequisites, types with examples, delivery channels. Every sentence adds value, though slightly lengthy for a simple tool.

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

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

Given the complexity (3 params, nested objects, no output schema), the description fully explains prerequisites, return value, type-specific params, delivery options with constraints, and the always-on feed channel.

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

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

Schema coverage is 100%, and the description adds extensive meaning with examples for each subscription type and detailed delivery channel explanations 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource combination and distinguishes 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 tells when to use the tool (to create a subscription) and mentions prerequisites ('Requires a Pipeworx OAuth account'). It doesn't explicitly compare to alternatives like recent_alerts, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds context about returning dynamic, catalog-based results with category-bucketed examples, which supplements the annotations without contradiction.

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

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

The description is slightly long but front-loaded with user intents and efficiently conveys purpose, content, and parameter guidance. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Given the tool's simplicity (one optional param, no output schema) and the rich annotations, the description fully covers purpose, usage, parameters, and return format. It provides all necessary information for correct invocation.

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

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

The description adds significant meaning beyond the schema: it enumerates possible topic values (finance, pharma, etc.), explains the default behavior (full spread) versus focused behavior, and ties the parameter to the tool's overall purpose. This fully compensates for the schema's minimal description.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns example questions with tool+argument shapes. It lists multiple user intents and distinguishes itself from siblings by recommending usage when the agent doesn't know what Pipeworx can do.

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

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

The description explicitly advises using this tool FIRST when unfamiliar with Pipeworx, and mentions passing a topic to focus. While it doesn't explicitly state when not to use it, the context of sibling tools implies alternatives. The guidance is clear and useful.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds value by specifying the scope (bioRxiv) and interval behavior, which goes beyond annotations.

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

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

Two sentences, no fluff, front-loaded with purpose. Every word earns its place.

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

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

For a simple tool with one optional parameter, output schema present, and annotations covering safety, the description is complete: it tells what, how, and scope limitations.

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 parameter is described. The description adds the default value ('m') and clarifies the meaning of values, enhancing understanding beyond the schema.

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

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

The description clearly states it provides submission/publication counts for bioRxiv, with a specific verb 'counts' and resource 'bioRxiv'. It distinguishes from medRxiv, showing awareness of 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?

It explains interval options ('m' default, 'y') and explicitly notes bioRxiv only, preventing misuse on medRxiv. However, it doesn't explicitly mention when to use this tool over siblings like 'details' or 'published', though the context makes it 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?

The description adds non-obvious behavior: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This complements annotations (destructiveHint=false) and provides valuable context beyond structured fields.

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

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

Two sentences that efficiently convey purpose, ownership, and behavioral effect. No wasted words; key information is front-loaded.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage rules, and behavioral nuances (activation vs deletion). It also links to related tool 'recent_alerts'.

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 the 'id' parameter well-documented. The description adds minimal extra meaning, reinforcing that the id comes from 'subscribe'. Baseline 3 is appropriate.

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

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

The description clearly states the action ('cancel') and resource ('subscription by id'), and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by indicating cancellation.

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

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

The description explains ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use. While it doesn't explicitly state alternatives, the context is clear.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds context on the return format (verdict, structured form, actual value with citation, percent delta) and data sources, which goes beyond annotations.

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

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

The description is a single paragraph that efficiently packs key information without redundancy. It uses examples and a clear statement of scope, earning 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?

Given the tool has one parameter and no output schema, the description provides a complete picture: what it does, what it returns, and its limitation to company-financial claims. It is mostly complete, though lacks details on error handling.

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

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

Schema coverage is 100% with a description for the single parameter. The tool description adds value by providing natural-language examples and clarifying the expected form, which aids the agent in constructing the claim parameter.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific examples and scope. It distinguishes from siblings by mentioning it replaces multiple sequential calls, setting it apart from general research tools.

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

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

Explicitly states when to use ('whenever the agent needs to check factual correctness') and specifies the domain (company-financial claims via SEC EDGAR + XBRL). Does not explicitly state when not to use, but the scope is clear.

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