Hnb Hr

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds details on default model (Workers AI Llama), optional Anthropic with BYO key, and the return structure (per-model scores with confidence, signals, raw_response). 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 four sentences, front-loaded with the primary function. Every sentence adds essential information: function, optional models, return format, use cases. No fluff.

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

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

For a tool with 4 parameters and no output schema, the description thoroughly explains the return structure (per-model object + combined view), default behavior, optional API key, and usage context. It covers all aspects an agent needs to decide and invoke correctly.

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

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

Schema description coverage is 100%, but the description adds context: e.g., entity examples ('Pipeworx', 'OpenInvoice'), and clarifies _apiKey usage. This adds value beyond the schema's 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: probe LLMs for knowledge about an entity and score visibility (0-100). It specifies verb (probe), resource (LLMs knowledge), and output (score). No sibling tools duplicate this function.

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

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

The description provides clear use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to use the API key for Anthropic. However, it does not explicitly contrast with sibling tools like scan_competitor_ai_presence.

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

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

The description discloses significant behavioral details beyond the annotations: it routes questions to 5,724 tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and works on every tier. This adds substantial transparency about how the tool behaves internally and what the response includes, complementing the readOnlyHint and openWorldHint 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 relatively long but highly informative and efficiently structured. It front-loads the key directive ('PREFER OVER WEB SEARCH'), then lists domains, examples, and guidance on alternatives. Every sentence contributes value; there is no fluff. The length is justified by the tool's complexity and breadth, so a 4 is appropriate rather than a 5.

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

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

Given the tool's complexity (routing to thousands of sources) and the presence of many sibling tools, the description is remarkably complete. It explains what the tool does, how it works, when to use it, when to use alternatives, and what to expect in the response (structured answer with citations). There is no output schema, but the description fills that gap by stating the return format. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, including aliases. The description adds no additional parameter semantics beyond what the schema provides, which meets the baseline of 3 for high coverage. No extra guidance on parameter formatting or constraints is given, but none is needed.

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

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

The description clearly states the tool's purpose: it answers factual questions about real-world data (SEC filings, FDA drugs, economic stats, etc.) by routing to many sources. It explicitly names the verb 'ask' and the resource 'Pipeworx' and differentiates itself from siblings like ask_pipeworx_grounded and deep_research by stating when to step up to those. This is a specific and unambiguous purpose.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and supplies concrete instructions for when to use alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad multi-part questions). It also lists trigger phrases and examples, making the selection criteria crystal clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable context about the beta nature, live candidate routing, the current state (no active candidate), and clarifies that it is a full working router, not a fallback. This goes beyond the annotations without contradicting them.

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

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

The description is moderately sized but front-loads the core purpose and current state, then moves to usage and clarification. Each sentence earns its place, though a slightly tighter wording could remove redundancy (e.g., 'identical' and 'matches exactly' both appear). It remains clear 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?

The description covers the router's scope, experimental nature, current status, and usage guidance. It mentions the same response shape as ask_pipeworx, which is sufficient given the sibling exists. Missing details like response structure are not critical since the tool is a simple question-to-router with a well-known sibling, and no output schema is provided.

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

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

Schema coverage is 100% for all six parameters, so the schema fully documents them. The description only restates that the tool uses 'same arguments' as ask_pipeworx, adding no new semantic information beyond what the schema provides. Baseline 3 is appropriate because the schema carries the full burden.

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

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

The description clearly identifies the tool as a universal router with 5,724 tools, same arguments and response shape as ask_pipeworx, and explicitly distinguishes itself as the beta version. It conveys the exact function and differentiates from the stable sibling, making it easy for an agent to understand what it does.

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

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

Provides explicit usage context: 'Use it exactly like ask_pipeworx when you want the newest routing' and clearly states that results are compared against the stable router. It implies when to use the stable alternative (when not seeking experimental improvements) and names the primary sibling, leaving no ambiguity about selection.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the critical behavioral contract: answers are extracted only from tool results, and the tool returns an explicit refusal with a concrete refusal_reason when the data doesn't directly answer. It also specifies the success and failure response shapes, including fields like evidence, confidence, source, and fetched_at. This is substantial behavioral context that annotations alone do not 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 dense but every sentence earns its place: mode definition, routing behavior, extraction guarantee, return shape, refusal reasons, usage context, and cost tradeoff. It is front-loaded with the most important trait ('Hallucination-resistant') and ends with a practical comparison to the cheaper sibling. No filler or repetition.

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

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

With no output schema, the description fully covers both success and refusal response envelopes, enumerating all refusal_reason values. It also addresses the operational context (high-stakes, must-not-invent), the routing mechanism, and the cost tradeoff. An agent has everything needed to call this tool correctly and interpret its results.

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

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

Schema description coverage is 100%: all six parameters are aliases for 'question' and each has a description. The tool description adds nothing about parameters beyond referring to 'the question,' so it doesn't improve on the schema. Baseline 3 is appropriate because the schema already fully documents the single semantic 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 names a specific verb ('answer'), a resource ('Pipeworx'), and a defining mode ('grounded, hallucination-resistant'). It distinguishes this tool from its sibling ask_pipeworx by focusing on extraction from tool results rather than merely routing and fetching. The high-stakes context is front-loaded, so an agent can immediately tell what this tool does and why it exists.

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

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

The description explicitly states when to use the tool: 'whenever an answer will be quoted, cited, or acted on' and lists examples like financial verdicts, legal claims, medical lookups, and public statements. It also gives a clear exclusion: prefer ask_pipeworx for casual lookups because this mode 'costs one extra LLM call.' This is model guidance for choosing between siblings.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Beyond that, the description richly details resolution logic, classifier fan-out, response shapes, resolver contract with confidence levels, parent event extraction, news fallback handling, safety short-circuits, closed market handling, wide spread warnings, and cancellation rule parsing. This provides extensive behavioral insight beyond annotations.

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

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

The description is long and detailed, which is justified by the tool's complexity. It is front-loaded with purpose and structured logically, but contains verbose explanations that could be condensed. Every sentence adds value, but overall length reduces 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 no output schema, the description comprehensively explains return values: result.market fields, analysis with edge and warning, evidence keyed by source, resolver contract with confidence and alternatives, parent_event extractor, news fields with fallback info, safety mechanisms, and cancellation rule parsing. Covers all necessary context 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% (3 parameters fully described). The description adds examples and context for the 'market' parameter (slug, URL, text) and mentions 'depth' and 'include_raw' defaults, but does not significantly augment 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 explicitly states the tool researches a Polymarket bet by pulling relevant Pipeworx data. It specifies the verb 'research' and resource 'bet' with concrete input types (slug, URL, question text). The detailed classifier list and fan-out examples distinguish it from sibling tools like polymarket_edges.

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

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

The description provides clear use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It explains when to use the tool but does not explicitly state when not to use or compare with related siblings, though the examples and classification system imply differentiation.

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. Description adds substantial behavioral context: data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorted results by primary metric, and inclusion of citation URIs. No contradictions.

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

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

Description is somewhat long but each sentence earns its place. It is front-loaded with query examples, making purpose instantly clear. A slight trim could improve conciseness, but current structure is 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?

Given the tool has 2 parameters (100% schema coverage) and no output schema, the description covers input semantics, data sources, and behavioral details. It mentions return format (paired data + citation URIs) but lacks detailed structure of output. Sufficient 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%, but description adds meaning: for 'type' enum it explains the data pulled (financial vs adverse events), for 'values' it specifies tickers/CIKs for companies and names for drugs, and reinforces min/max constraints. Goes beyond schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific verb phrases like 'Compare X and Y' and 'head to head'. It distinguishes from siblings such as entity_profile by emphasizing parallel lookup.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong usage guidance. It also explains when each type (company vs drug) is appropriate, but does not explicitly state when not to use (e.g., for single entity lookups), though implied.

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

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

Beyond the readOnly/openWorld/idempotent/destructive annotations, it discloses rich behavior: decomposition into facets, parallel routing to 5,724 tools, findings packet contents, verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citations, gaps[] for unanswered facets, contradictions[] for standard/thorough, and explicit 'never invented' wording. This goes well beyond what annotations already provide.

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

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

The description is long but front-loads critical requirements (account needed, fallback tool, what it is not) and is organized topically: use cases, depth semantics, citation behavior, latency. Nearly every sentence earns its place for a complex tool; it loses only a point for restating some schema content.

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

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

There is no output schema, so the description carries the burden of explaining the return shape, and it does: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop field. It also covers account requirements, fallback path, expected latency, and depth semantics. Nothing an agent needs to call it correctly is missing.

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

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

The input schema already fully describes both parameters (100% schema_description_coverage), including the depth enum's per-value behavior and a natural-language note for question. The description largely restates this rather than adding new parameter-level semantics, so it stays at the baseline for high schema coverage.

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

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

The description uses a specific verb and resource: 'grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources' 'in ONE call.' It also explicitly distinguishes itself from open-web search and from the sibling ask_pipeworx, so an agent can tell them apart without opening the schema.

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

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

It states clearly when to use this tool: broad/multi-part questions over structured data ('compare X and Y's regulatory + financial exposure'). It gives explicit alternatives with conditions: use ask_pipeworx for single lookups, breaking/current-news topics, or when not signed in. It even names what the tool is not ('NOT open-web search').

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating a safe, read-only operation. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states results are 'ready to call directly, no second schema lookup needed.'

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 efficiently structured: a clear one-sentence purpose, followed by examples, return value specifics, and usage guidance. Every sentence adds value, and the most important 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?

Given the tool's complexity (6 parameters, 1 required, no output schema, no nested objects), the description is complete. It covers purpose, usage, behavior, and return format. No gaps are apparent.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces that 'query' is the main parameter and accepts aliases, but adds minimal new meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples of searchable domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from sibling tools by being the discovery tool for browsing the toolset.

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: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear usage context. While it doesn't explicitly list alternatives, the instruction to use it first implies when not to use it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds significant value by detailing the parallel fan-out across multiple sources, specific returned fields, the USPTO API sunset and soft-fall, and limits like 'up to 5 filings'. 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?

Description is somewhat long but every sentence serves a purpose. It is front-loaded with query examples and immediately states the core function. Could be slightly more structured but remains clear 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?

Given the complexity (multiple data sources, varied return fields, fallback behavior, no output schema), the description provides enough detail for an agent to understand what to expect, including limits (5 filings) and deprecation notes (USPTO). Leaves 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% with both parameters described. Description enhances with examples (e.g., 'AAPL', '0000320193'), clarifies type^enum is only 'company' currently, and explains that value does not accept names. Adds practical guidance beyond schema.

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

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

The description explicitly states 'full cross-source profile of a US public company' and provides concrete query examples (e.g., 'Tell me about X', 'brief me on Tesla'). It distinguishes from siblings by contrasting with chaining single-pack lookups and mentioning resolve_entity for name resolution.

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?

Clearly states when to prefer this tool ('ALWAYS PREFER... when the user asks for a holistic view') and when not to use it ('names not supported – use resolve_entity first'). Provides explicit alternatives and 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 destructiveHint=true and readOnlyHint=false, so the description does not add significant behavioral detail. It echoes the destructive nature but does not go beyond.

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?

Extremely concise: two sentences that cover purpose, usage, and pairing. No wasted words.

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

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

For a simple tool with one required parameter and no output schema, the description fully covers the action, triggers, and complementary tools.

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

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

Schema coverage is 100% and already describes the key parameter. The description does not add new semantic information about the 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 uses a specific verb 'delete' and clarifies the resource 'previously stored memory by key'. It also distinguishes from siblings by mentioning 'pair with remember and recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with other tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, ensuring the agent knows it's a safe, idempotent read operation. The description adds behavioral context: fetches the page, extracts title/description/key links, and emits standard markdown format, 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 two sentences plus a bullet list, front-loaded with the main purpose. Every sentence earns its place with no wasted words.

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

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

Despite no output schema, the description specifies output as a single text blob in standard markdown format. Combined with annotations for safety, the description fully covers what the tool does and produces.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds marginal value with an example URL format and mentions the output format, but parameter details are already in the schema.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt file), and purpose for AI crawlers. It distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation rather than visibility scanning.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor. It provides clear context for when to use the tool, though it does not explicitly state when not to use it or mention 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 provide readOnly/idempotent hints. Description adds return format details (string with comma decimal separator), field name 'srednji_tecaj', and date format, which go 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?

Single dense paragraph with clear structure: purpose, input format, three modes, data format. No wasted words.

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

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

Given no output schema, description explains return structure and key field. Covers all usage modes. Lacks error handling but adequate for a simple rate query 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%, baseline 3. Description adds examples, clarifies relationship between date and start_date/end_date, and explains modes, providing 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?

Description clearly states tool fetches HNB exchange rate for ONE foreign currency vs EUR, with three modes (latest, single date, date range). Distinguishes from potential sibling 'hnb_exchange_rates' by emphasizing single currency.

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

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

Explicitly describes three usage modes and date format. Does not explicitly exclude alternatives or provide when-not-to-use, but context is clear 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. Description adds meaningful context: rates quoted against EUR, return fields (valuta, rates, apply date), and comma decimal separator. No contradictions.

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

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

Two sentences, front-loaded with purpose and key details. Every sentence earns its place: first introduces the tool, second details quotation and return format. No filler.

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

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

Given single optional parameter, no output schema, and full annotations, the description provides all necessary context: what the tool returns, how the data is expressed, and how to use the parameter. Complete for its complexity.

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

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

Schema coverage is 100% with clear schema description for the optional 'date' parameter. Description adds value by stating 'Omit for the latest applicable rates' and specifying the format 'YYYY-MM-DD' (already in schema but reinforced). Exceeds baseline 3.

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

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

The description clearly states 'official exchange rates for ALL foreign currencies on a given date', differentiating from the sibling 'hnb_currency_rate' (likely for a single currency). It specifies the resource (HNB exchange rates) and the scope (all currencies, date-driven).

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 explains when to use: provides a date for a specific day or omit for latest rates. Implicitly contrasts with sibling tool 'hnb_currency_rate' which presumably handles single currencies. No ambiguity about 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 indicate read-only, idempotent, non-destructive behavior. Description adds useful context by listing returned fields and the default active-only filter, enhancing transparency.

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

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

Two short sentences, zero wasted words. Information is front-loaded with the primary action and followed by usage hints.

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

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

Given the simple tool with one optional parameter and no output schema, the description sufficiently covers purpose, return fields, and usage context. 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 covers the single parameter with full description. The description adds no additional detail beyond implying the default behavior, so it meets the baseline for 100% schema coverage.

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

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

Clearly states the tool lists the caller's active subscriptions, distinguishing it from related tools like subscribe and unsubscribe. The description is specific and action-oriented.

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

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

Provides explicit guidance on when to use: to review monitored subscriptions before adding more or to find an id to cancel. This helps the agent decide appropriately.

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

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

Annotations are all false, so the description carries the full burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the token-based follow-up mechanism, and the digest/roadmap impact. There is no contradiction with annotations (readOnlyHint=false aligns with a submission action).

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 coherent paragraph that front-loads the purpose, then follows with usage, exclusions, token mechanism, and operational details. Every sentence adds value; length is justified by the tool's nuanced behavior.

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 feedback tool with no output schema, the description is remarkably complete: it covers when to use, what to report, how to report, the token-based status flow, rate limits, and cost. It compensates for the lack of output schema by explaining the claim_token return behavior.

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

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

The input schema already has 100% property coverage, so the description adds marginal value. It does enrich the 'message' parameter with content guidance (describe in terms of Pipeworx tools, don't paste user prompt) and explains the claim_token usage pattern, but most parameter semantics live in the schema.

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

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

The description opens with a clear verb+resource+scope: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists feedback categories (bug, feature, data_gap, praise) and clearly differentiates from sibling research/query tools by being the dedicated feedback channel.

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 states explicit trigger conditions ('Use when a tool returns wrong/stale data...'), an explicit exclusion ('if the tool came from a different MCP server... file it with that server instead'), and provides guidance on how to formulate feedback ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). It also notes the claim_token flow for later follow-up.

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 context beyond annotations: caching behavior (5min-1h), data source (CF analytics), privacy (no PII), and derived nature. Annotations already indicate readOnly, openWorld, idempotent, non-destructive.

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

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

Description is well-structured: a concise one-liner followed by bullet-point use cases and technical details. Every sentence adds value 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 simplicity (one optional parameter, no output schema), the description fully covers what the tool returns, its source, caching, and privacy. 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 covers window parameter with enum and description. The description adds semantic value by explaining the trade-off between hotness and steady-state demand for different window lengths.

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 that the tool returns trending tools, packs, and call volume from other agents. It distinguishes from siblings like 'discover_tools' by focusing on real-time popularity.

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

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

Three explicit use cases are listed, providing clear context for when to use the tool. However, it does not mention when not to use it or suggest alternatives.

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

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

Annotations already indicate safe, idempotent read. Description adds deep behavioral context: internal algorithms, response structure, fill check logic, semantic anchor, partition filter, and when not to trade. 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?

Front-loaded with main purpose, logically structured by mode. While lengthy, every sentence adds necessary detail for a complex tool. Slight wordiness but very 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?

No output schema provided, but description thoroughly explains response fields, including opportunities, partition_check, and fill check details. Covers all modes, edge cases (semantic anchor, partition filter), and actionable guidance.

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

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

Schema descriptions cover both parameters 100%. Description adds practical context: accepted formats (full URLs for event), explains differences between event and topic modes, and how they affect scanning scope.

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 finds arbitrage opportunities on Polymarket via specific algorithms (monotonicity violations, partition-sum checks). Distinguishes from siblings like polymarket_edges and polymarket_fill_risk by describing unique approach.

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

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

Provides explicit guidance: call with no args for trending scan, use 'event' for specific market, use 'topic' for cross-event scan. Recommends 'event' mode and explains when to avoid trading via fill check.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds immense value beyond annotations, detailing caching (1h KV-level), response structure with three segments, edge computation models, Kelly sizing, slippage assumptions, and diagnostics for empty segments.

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 relatively long but well-structured with clear sections for each model family, knobs, and diagnostics. Every sentence adds value, though it could be slightly more concise without losing critical details.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and edge computation details. It covers caching, knob behaviors, and reasons for empty segments, making it highly 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%, so the schema already documents all parameters. The description does not add significant new meaning beyond what the parameter descriptions in the schema provide (e.g., min_kelly, slippage_pp). 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on cross-data disagreement and providing a comprehensive edge analysis.

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

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

Description explicitly targets agents discovering opportunities without paging hundreds of markets, and outlines tradeable-edge knobs and diagnostics for empty segments. It lacks explicit exclusions or alternatives but is clear in its use case.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: returns three arrays (tracked, expired, snapshot_dates), explains time-series computation, decay calculation from daily closes, note about data gaps, and limits like 60-day TTL.

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

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

The description is long but every sentence adds value. It is front-loaded with core purpose. Could be slightly more concise, but structure is clear with sections for args, response, 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 no output schema, the description thoroughly explains the three output arrays and their fields (tracked with time-series, first_seen, trend; expired with lifespan_days; snapshot_dates). Also mentions limitations. Complete for the tool's complexity.

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

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

Schema coverage is 100% for both parameters. The description adds meaning beyond schema by stating default values (14 days, '1wk'), max days (30), and explaining that window corresponds to a snapshot family. This adds useful context.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question about edge duration and shrinkage. It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on time-series analysis.

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

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

The description explains when to use it (to assess edge persistence) and implicitly when not (since it's about historical trend, not current edge). It details parameters like days and window but does not explicitly compare to sibling tools, though 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, confirming a safe check. The description adds significant behavioral context: requires one of 'market' or 'event', explains verdict options ('clean|degraded|cannot_fill'), and warns about forced directional risk from thin legs. 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 structured with sections ('SINGLE-MARKET', 'BASKET') and bullet points, front-loading the purpose. It is verbose but every sentence provides necessary detail; slight redundancy could be trimmed.

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

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

With no output schema, the description fully explains return values for both modes (e.g., top_of_book, vwap_fill_price, verdict for single; theoretical_sum, capture_ratio, profit_usd, thin_legs for basket). It covers edge cases like partial fills and directional risk, making it complete for informed tool selection.

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

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

Schema description coverage is 100%, baseline is 3. The description adds meaning beyond schema: explains side behavior for basket (auto-detect from partition sum), interprets size_usd differently for basket (settlement notional), and clarifies defaults and clamps. This adds value but the schema already has good descriptions.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly ties its usage to specific sibling tools like polymarket_arbitrage and polymarket_edges, differentiating itself as a pre-trade validation step.

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

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

The description tells when to use the tool ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains the rationale (theoretical overround not capturable, partial fills create directional risk). It lacks explicit exclusion criteria or alternative tools for other scenarios.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses the matching logic, the unverified nature of pairings, fee modeling limitations, skipped-comparison counters, and multiple compatibility warning codes with their meanings. It also explicitly states that returned pairs may still be invalid and that real spreads are rarer than the shortcut list suggests.

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

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

The description is heavily label-structured and front-loaded with a clear first sentence, but it is long and somewhat repetitive. Points like temporal_alignment_unknown, the 'same disclosures apply to both' note, and the warning to read compatibility fields are reiterated in multiple places. It is organized and dense, but not concise.

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

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

With no output schema, the description carries the full burden of explaining the response shape, and it does so thoroughly: per-leg prices, top spreads, per-entry flags, temporal alignment fields, fee disclosure, skipped-comparison counters, and low-confidence pairs. It also covers safety and failure modes, making it complete for an agent to call this tool with reasonable expectations.

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 already have descriptions. The description adds meaningful context by explaining that topic auto-fetches mapped events, that explicit ticker/slug override the mapped sides, and that both modes use the same matching logic. This is a valuable layer beyond the schema's basic value lists.

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 opening line states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, which is a specific resource and scope. It distinguishes itself from any single-venue or abstract comparison tool by emphasizing the two-venue pairing, and it clarifies the core outcome (matched spread in percentage points).

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 the two invocation modes (topic shortcuts vs explicit ticker/slug) and when each is appropriate. It gives strong practical guidance with caveats such as 'pre-mapped ≠ tradeable' and tells users to read compatibility fields even when pairs exist, but it does not explicitly name alternative sibling tools or state when a different tool should be used instead.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping context and listing behavior, which is valuable beyond the annotations.

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

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

Two sentences, no fluff, front-loaded with action and resource. Efficient and to the point.

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 low complexity (1 optional param, no output schema), description is complete: explains behavior, scoping, and pairing with related tools.

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

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

Schema has 100% coverage with parameter description 'Memory key to retrieve (omit to list all keys)'. Description reinforces this and adds no new info but confirms usage.

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 retrieves a previously saved value or lists all keys. Verb 'retrieve' and 'list' are specific, and it distinguishes from sibling tools 'remember' and 'forget' by naming them.

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

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

Explicitly says to use for looking up context stored earlier, avoiding re-derivation. Mentions scoping and pairing with remember/forget. Does not explicitly state when not to use, but context is clear.

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

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

The annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the return fields (source, citation_uri, raw event payload) and the effect of the mark_read parameter on subsequent calls. No contradictions with annotations.

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

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

The description is concise at four sentences. Each sentence serves a purpose: stating the function, describing output, explaining filtering and mark_read, and noting polling and alternative access. No redundant or excessive text.

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

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

Given no output schema, the description adequately covers return structure, filtering options, and the mark_read side effect. It also mentions an alternative endpoint. While it does not discuss error handling or rate limits, the annotations cover safety aspects. The description is reasonably complete for this 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 coverage is 100%, so baseline is 3. The description adds context for the 'type' parameter with an example ('sec_8k'), explains 'since' as ISO timestamp, and clarifies 'mark_read' behavior. However, it does not elaborate on 'limit' or 'unread_only', so it only marginally improves over 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 'Pull fired events from your subscription feed', with a specific verb and resource. It details what the tool returns (most recent alerts with source, citation_uri, raw payload). While it distinguishes itself from the HTTP endpoint, it does not explicitly differentiate from sibling tools like 'list_subscriptions', which might also return alert-related data.

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

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

The description mentions that polling works fine and provides an alternative HTTP endpoint for scripts/dashboards, offering some usage context. However, it does not specify when to use this tool versus other tools (e.g., 'list_subscriptions') or what prerequisites exist. No explicit when-not or alternatives are given.

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

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

Adds significant behavioral context beyond annotations: fans out to multiple sources in parallel, fallback logic, USPTO soft-fail, return structure (changes[] grouped by source + total_changes + citation URIs). No contradictions with annotations.

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

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

Single dense paragraph front-loaded with query examples, followed by source details, parameter explanation, return structure, and sibling differentiation. Every sentence adds value, 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?

Highly complete given no output schema: covers all sources, fallback, return format, parameter formats, and when to use alternatives. No missing crucial information.

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 valuable meaning: examples for 'since' (ISO date and relative shorthand with recommendations), explanation of 'value' (ticker or CIK), and clarification that 'type' only supports 'company'. Exceeds baseline expectation.

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

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

The description clearly states the tool's purpose with specific verbs and resources: 'change feed for a company', fans out to SEC EDGAR, GDELT→GNews, USPTO. It provides query examples ('What's new with X', 'latest on Y') and distinguishes from sibling entity_profile.

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

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

Explicit usage guidance: 'Use entity_profile instead when you want the static profile... regardless of window.' Explains fallback behavior (GDELT→GNews) and parameter recommendations ('Use "30d" or "1m" for typical monitoring').

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 provide idempotentHint=true and destructiveHint=false; description adds key-value scoping by identifier, persistence details (authenticated vs. 24-hour anonymous), and pairing with other tools. No contradiction.

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

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

Two sentences plus a short phrase, front-loaded with purpose, no wasted words. Every sentence adds essential information.

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

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

Given no output schema, description sufficiently explains storage behavior, scoping, and tool pairing, making it complete for a simple key-value store.

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 by listing example keys (subject_property, target_ticker) and explaining value as any text, enhancing semantic understanding beyond schema.

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

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

The description clearly states the tool saves data for later reuse, with concrete examples (resolved ticker, target address, user preference) and distinguishes from siblings recall and forget by mentioning pairing.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and directs to recall and forget as alternatives for retrieval and deletion.

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

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguity handling via figi_candidates, and explicit unresolved fields. This gives the agent a realistic model of tool behavior and failure modes.

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

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

The description is long but information-dense, with every sentence contributing either use-case context, input guidance, or behavioral caveats. It front-loads the core purpose and practical trigger phrases before diving into type-specific details.

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

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

With no output schema, the description compensates by naming expected outputs (CIK, ticker, LEI, FIGI, RxCUI), explaining candidate behavior, and covering source provenance. An agent has enough context to call the tool correctly across company and drug cases.

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?

Even with 100% schema coverage, the description adds substantial meaning: example inputs for both types, the critical 'ENTITY NAME ONLY' rule, warnings about trailing security-class words, and ISIN-to-LEI resolution semantics. This goes well beyond the schema's simple property 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 states a specific action — resolve user-spoken names to canonical/official identifiers — and lists concrete query patterns and identifier examples. It also frames the tool's role relative to other tools ('identifiers other tools require as input'), making the purpose unmistakable.

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

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

The description gives strong, explicit usage guidance: 'Use FIRST whenever you have a name but need an ID', plus supported entity types and input formats. It does not explicitly name alternatives or state when not to use the tool, though the distinction is mostly clear from sibling names and the tool's stated role.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by explaining that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with specific fields (score, confidence, signal density). 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 two sentences, front-loaded with the main purpose, and every sentence provides essential information 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?

Despite no output schema, the description clearly states the return format (ranked list with score, confidence, signal density per entity). It also explains the internal mechanism (calling ai_visibility_check). This is sufficient for an agent to understand the tool's behavior and output.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds additional meaning by explaining that the first entity is treated as the 'subject' for narrative and the rest as competitors, which goes beyond the schema's 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 it compares AI visibility across multiple entities, distinguishing it from single-entity tool ai_visibility_check and general compare_entities. It specifies the action (probe, rank, surface) and the output (ranked list).

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

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

The description explicitly mentions use for competitive AI-marketing audits and provides an example question. While it doesn't explicitly list when not to use it, the context of sibling tools and the description itself imply that it is for multi-entity comparison, not single-entity checks.

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 (read-only, idempotent, not destructive), the description adds critical behavioral details: fan-out architecture, partial failure handling, potential 5-30s delay on new versions, and the sources_failed field in response. No contradictions with annotations.

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

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

Description is dense but well-structured: purpose first, then usage, behavior, return details, and ecosystem scope. Every sentence adds value; slightly verbose but not excessively.

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 details the return structure (summary fields, advisory details, links, alternatives) and error behavior (graceful degradation, timeouts). Covers all needed context 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 covers 100% of parameters with descriptions. The description adds that version defaults to latest, but otherwise does not significantly augment the schema-provided semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, listing specific data sources (deps.dev, bundlephobia) and return elements. It distinguishes itself from siblings by focusing on npm ecosystem and mentioning alternatives for other package managers.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of adding an npm package. Also specifies not to use for non-npm ecosystems, directing users to another tool (deps.dev:version) 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds details about the embedding model (BGE-base-en), windowing (500-char overlapping), character limit (200K chars with truncation flag), and that results include offsets for verification. No contradictions.

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

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

The description is concise (about 6 lines) and well-structured. Each sentence serves a purpose: stating the action, usage context, technical details, and limitations. No redundant information.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers all necessary aspects: purpose, usage, behavioral details, parameter semantics, and return format (passages with offsets and scores). It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value beyond schema by providing example queries for the 'query' parameter, clarifying the max characters for 'text', and explaining the cap behavior. However, it could further detail the 'limit' parameter's default and range, which is already implied.

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, specifying the verb (search) and resource (inside a record). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and emphasizing context-saving for large records.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt' and provides an alternative strategy: pairing with ask_pipeworx_grounded. This gives clear guidance on tool selection.

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

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

Adds significant behavioral context beyond annotations: authentication requirements, parameter constraints (SMS verification, 10/day cap), webhook HMAC signing and auto-disable details. 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?

Well-structured and front-loaded with core purpose. Somewhat verbose but every sentence adds value. Could be slightly more concise but remains readable.

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

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

Comprehensive for complexity: covers types, parameters, delivery options, return values. No output schema, but return value is stated. Provides enough context for an agent to use correctly.

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

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

Schema coverage is 100%, but description adds substantial value with real-world examples, constraints (e.g., phone must be verified, webhook limitations), and clarifies optional fields. Exceeds baseline of 3.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream.' Specifies verb, resource, and return value ('Returns the new subscription id.'). Distinguishes from siblings 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?

Provides clear context: requires Pipeworx OAuth account, not for anonymous/BYO. Lists supported types and delivery channels with examples. Does not explicitly state when not to use or name alternatives, but the context is sufficient.

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 cover readOnly, openWorld, idempotent, and non-destructive hints. Description adds behavioral context: it draws from a live catalog, returns example questions with tool calls, and can be focused by topic. No contradictions.

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

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

Description is somewhat long but front-loaded with common queries and structured as bullet-like categories. Every sentence adds value, though it 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?

For a tool with one optional parameter, no output schema, and comprehensive annotations, the description is complete. It explains the output concept, usage patterns, and the purpose of the tool in the broader system.

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 topic parameter described. Description adds value by explaining the topic values (finance, pharma, etc.) and the effect of omitting the argument (full spread). Enhances schema meaning.

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

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

Description clearly states it returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself as the onboarding entry point, separate from sibling tools like ask_pipeworx or discover_tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear context for when to use and implies when not to (after onboarding).

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 value beyond annotations by explaining the behavioral trait: the row is deactivated, not deleted, preserving historical events via recent_alerts. It also reinforces the ownership check. Annotations only indicate readOnly=false, destructive=false, but the description fills in the specific mutation behavior.

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

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

The description consists of two concise, front-loaded sentences. Every sentence provides essential information: the action, ownership constraint, and the effect on the row. No extraneous 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 tool with one parameter and no output schema, the description is complete. It covers purpose, usage constraint, and behavioral outcome. No additional context is necessary.

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

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

The input schema describes the 'id' parameter as a UUID returned by subscribe, with 100% coverage. The description adds no further parameter details beyond mentioning 'by id.' With full schema coverage, the baseline score is 3.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the verb (cancel) and the resource (subscription). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description provides clear context for when to use the tool by noting ownership enforcement: 'you can only cancel your own subscriptions.' It also explains the consequence of deactivation versus deletion. However, it does not explicitly list conditions where the tool should not be used or suggest alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral traits: the two routing paths, the verdict taxonomy, and especially the semantics of could_not_verify (check did not happen, not evidence) and unsupported (no source found). This adds substantial context that annotations alone do not convey.

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

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

The description is lengthy but dense with high-value information, front-loaded with trigger phrases and purpose. Every section earns its place, though the opening list of query patterns is somewhat repetitive. It is structured logically, detailing routing, outputs, and failure semantics without tangential content.

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

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

Given the tool's complexity, the description is remarkably complete. It explains the two distinct processing paths, enumerates all verdict types, clarifies ambiguous verdicts, notes the inclusion of evidence citations, and justifies why this tool consolidates multiple sequential calls. No output schema exists, but the description sufficiently covers return values and expected behavior.

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

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

The schema already covers both parameters with descriptions (100% coverage). The description enhances this by explaining tolerance_pct's override behavior, default behavior, and practical usage for hallucination detection, adding meaning beyond the raw schema. Claim is given illustrative examples, though the schema already provides them.

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

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

The description opens with trigger phrases and explicitly states the tool's purpose: 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings by detailing the internal routing (SEC EDGAR for financial claims vs grounded pipeline for others) and mentions it replaces 4–6 sequential calls, making its specific role clear.

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

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

The description provides clear usage context: 'Use whenever the agent needs to check whether something a user said is factually correct,' supported by example query patterns. It does not explicitly name alternative tools or provide when-not-to-use guidance, but the trigger phrases and scope ('ANY OTHER factual claim') make the intended use unambiguous.

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