Dst Dk

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

The description adds behavioral context beyond annotations: it explains the return structure (per-model score, confidence, signals, raw_response + combined view), default model (Workers AI Llama-3.3-70b), and the cost/billing implication for Anthropic (user pays Anthropic directly). Annotations already indicate readOnly and idempotent, which align. No contradiction.

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

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

The description is front-loaded and wastes no words: 5 sentences covering purpose, default model, optional Anthropic with cost note, return structure, and use cases. Every sentence adds value.

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

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

Given no output schema, the description includes the output structure (per-model fields and combined view). Parameter documentation is thorough. Use cases are provided. However, it doesn't detail what 'confidence' or 'signals' mean exactly, and doesn't mention pagination or limits, but these are minor gaps for a probing 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?

All 4 parameters have descriptions in the schema (100% coverage), and the description adds significant enrichment: for 'entity' it gives examples, for 'models' it lists supported values and defaults, for '_apiKey' it clarifies the prefix and dependency on 'anthropic' in models, and for 'context' it gives examples and explains its disambiguating role.

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 a business/brand/product/topic and return a visibility score (0-100) per model. It uses a specific verb and resource, and differentiates from sibling tools like 'scan_competitor_ai_presence' by focusing on LLM knowledge probing and scoring.

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: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains the default model and the optional Anthropic probing with BYO key. While it doesn't explicitly exclude alternatives or provide when-not-to-use guidance, the context is clear enough for an AI agent to decide.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds valuable behavioral context: it routes the question to the appropriate tool among 2,866, fills arguments, and returns structured answers with stable pipeworx:// citation URIs, without contradicting annotations.

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

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

The description is informative but slightly verbose. It is well structured, front-loading the key directive ('PREFER OVER WEB SEARCH') followed by examples. Could be trimmed without losing clarity, but remains 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's simplicity (one parameter, no output schema, rich annotations), the description covers all necessary context: usage scenarios, behavior, and output format (structured answer with citations). No gaps remain.

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

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

The single parameter 'question' has 100% schema coverage with a clear description. The tool description adds extensive meaning by providing multiple example questions and clarifying the scope of acceptable queries, far beyond what the schema provides.

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

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

The description clearly states the tool's purpose: routing factual questions to one of 2,866 tools across 623 verified sources and returning structured answers with citations. It distinguishes itself from siblings by explicitly preferring this tool over web search and listing specific domains (SEC filings, FDA drug data, etc.).

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: for factual questions about real-world entities, events, or numbers, and includes many examples. It implicitly suggests avoiding subjective questions, but lacks explicit when-not-to-use or alternative tool mentions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds significant detail beyond annotations: it describes the fan-out process (parallel data packs), response structure (market/analysis/evidence), safety short-circuits for low-confidence and closed markets, and tradeability notes for wide spreads. 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 dense but justified given the tool's complexity. It is front-loaded with purpose and input formats, uses structured lists for classifiers and fan-out examples, and has clear sections. Could be slightly trimmed, but every sentence adds value.

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

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

Despite no output schema, the description fully explains the response shape (result.market with fields, result.analysis with model probability, result.evidence keyed by source). It covers edge cases (low-confidence, closed markets, illiquid spread) and fan-out logic for various categories. 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% with descriptions for all three parameters (market, depth, include_raw). The description adds substantial meaning: explains market can be slug/URL/text, depth defaults to thorough, and include_raw explains size trade-offs (summary vs raw payloads). Examples in schema further aid interpretation.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, question text) and explains the pipeline (resolve, classify, fan-out, return evidence). It distinguishes from sibling tools by focusing on Polymarket bets and lists use cases ('should I bet on X', 'what does the data say about Y').

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

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

The description provides explicit usage examples and classifiers, guiding when to use the tool. It includes safety notes (low-confidence, closed markets, illiquid spread) that help agents decide if results are actionable. However, it does not explicitly mention alternatives or when not to use it, though sibling tools imply options like validate_claim or compare_entities.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds critical behavioral details: post-Run-6 fix for correct most-recent filing, handling off-calendar fiscal years, sorted results by primary metric, and pipeworx:// 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 paragraph of five sentences, front-loaded with purpose, then usage, then behavioral details. No redundant sentences, but could benefit from bullet points for readability. Appropriate length for the complexity.

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

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

No output schema, so description covers return data: paired data, citation URIs, sorted results, specific metrics per type. Fairly complete for a comparison tool, though could mention pagination or max response size.

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 valuable meaning: type='company' pulls specific financial metrics, type='drug' pulls adverse events, FDA approvals, trials. Values parameter explained with correct syntax and examples. Adds clarity beyond enum and array 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 compares 2-5 companies or drugs side by side, with specific verbs ('compare') and resources ('companies or drugs'). It differentiates from sibling tools by focusing on side-by-side comparison with specific data points, not single-entity 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 specifies use cases: 'compare X and Y', 'X vs Y', 'which is bigger', or rank-by-metric questions. Mentions efficiency gain over sequential lookups. Does not explicitly state when not to use, but context implies alternatives like entity_profile for single entities.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds context: returns top-N relevant tools with schemas and examples, and that no second schema lookup is needed. There is no contradiction, and the behavioral traits are well covered.

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

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

The description is a single paragraph that starts with the core purpose ('Find tools...'). It includes a list of example domains, which is informative but slightly verbose. Still, every sentence adds value, earning a 4. Could be more concise without the domain list, but it aids understanding.

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

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

With no output schema, the description explains return format (top-N tools with names, descriptions, schemas, examples). Input schema is fully covered. It lacks error handling or no-results behavior, but for a discovery tool the description is sufficiently complete for an AI agent to use it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the query parameter's purpose (describe task) and mentions limit implicitly via 'top-N'. It adds value by giving examples in the schema, but does not significantly extend beyond schema details.

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

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

The description clearly explains that the tool finds tools by describing data or task, listing diverse domains like SEC filings, FDA drugs, etc. It distinguishes from siblings by specifying it returns top-N relevant tools with full schemas, ready to call directly, which is not stated in other sibling tools like get_data or list_subjects.

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 to use when browsing, searching, or discovering tools, and to call it FIRST when many tools are available. It implies when not to use (when you already know the tool), but does not explicitly name alternatives like get_data for direct data access, hence not a 5.

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

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

Describes return fields with details (cik, filings with URIs, fundamentals with FY2025 note, patents status, news fallback, LEI). Annotations already indicate readOnly, idempotent, etc., and description adds value 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?

Front-loaded with purpose, but slightly long due to detailed return info. Still every sentence is earned.

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 covers all key behavioral aspects, limitations, and return format, making it complete for an agent.

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

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

Schema coverage is 100%, and description adds context: type only 'company', value ticker or zero-padded CIK, and clarifies name not supported.

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 'Get everything about a US public company in one call', with specific verb and resource. Distinguishes from siblings by noting it replaces multiple pack 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 provides when-to-use scenarios (e.g., 'tell me about X') and what not to use (names not supported, use resolve_entity first). Also mentions limitations like patents soft-fail.

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's 'Delete' aligns with the destructiveHint annotation. It adds context about clearing sensitive data, which enriches the behavioral understanding 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 efficient sentences, front-loaded with the action and purpose, with no extraneous information.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and behavioral context, making it self-sufficient.

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

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

Schema coverage is 100% and the parameter description 'Memory key to delete' directly repeats the schema documentation. No additional semantic value added beyond what the schema provides.

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

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

The description explicitly states 'Delete a previously stored memory by key' with precise verb and resource. It distinguishes from sibling tools like remember and recall, which are for storing and retrieving memories.

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

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

The description provides explicit usage contexts: when context is stale, task is done, or clearing sensitive data. It also mentions pairing with remember and recall, offering clear alternatives.

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

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

Description details the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'), which aligns with annotations (readOnlyHint=true). No contradictions.

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

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

Three purposeful sentences with no redundancy, front-loaded with main action and followed by usage scenarios.

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

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

Despite no output schema, the description fully specifies output format ('single text blob ready to drop at site-root/llms.txt') and covers input, process, and expected result.

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 includes default/max for 'max_links'. The description adds no new parameter meaning beyond what the schema already provides.

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

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

The description clearly states the tool generates an llms.txt file for AI crawlers, with specific verb ('generate') and resource ('llms.txt'). It lists use cases and implies differentiation from siblings like 'ai_visibility_check'.

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

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

The description lists explicit use cases ('getting a client's site indexed...auditing how an AI crawler would see a competitor') but does not explicitly state when not to use 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing behavioral nuances like aggregation of omitted variables, format-specific behaviors (JSON-stat default, semicolon CSV for BULK/CSV), and the wildcard '*'. 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 fairly concise given the complexity, with key information front-loaded. However, it could be slightly more streamlined; it packs many details into one paragraph. Still, every sentence earns its place and it's 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?

Given the schema covers all parameters and there is no output schema, the description sufficiently explains return formats (JSON-stat vs CSV) and usage patterns. It provides all necessary context for an agent to use the tool correctly without requiring additional lookups.

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

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

Schema coverage is 100%, so parameters are already documented. However, the description adds meaningful semantics beyond schema: explaining that variables values can be '*', omitted variables aggregate to total, and the difference between JSONSTAT and BULK/CSV formats. This enriches the parameter understanding.

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

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

The description clearly states the tool pulls data from a table, with specific verb 'Pull data from a table' and resource (tableId and variables map). It distinguishes from siblings like table_info (likely metadata) and other unrelated tools, making its 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 provides detailed usage instructions: how to use variables map with codes/ids, value formats (single id, array, or '*'), omitted variables behavior, and format options. However, it does not explicitly state when not to use this tool or mention alternatives, though the context is clear enough for an agent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds context about tree navigation and recursion but does not reveal any behavioral traits beyond what annotations provide.

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

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

Two sentences, front-loaded with purpose, no redundant information. Every word contributes meaning.

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

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

Adequate for a simple tree-browsing tool with good annotations and schema coverage. However, it lacks a description of the return value format (e.g., list of subjects with metadata), which would improve completeness.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds practical guidance for 'subjects' and 'recursive' but does not deepen semantics for 'lang' or provide examples of valid IDs. 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 browses the Statistics Denmark subject tree and gives concrete examples of top-level subjects (People, Labour, etc.). It specifies the action (browse) and the resource (subject tree), distinguishing it from sibling tools that deal with data retrieval or entity profiles.

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

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

Provides clear usage instructions: omit 'subjects' for top-level, pass an id to drill into children, and set 'recursive' for full subtree expansion. However, it does not explicitly state when not to use this tool or compare to alternatives, though sibling context makes this implicit.

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, so the description adds minimal behavioral context beyond the expected read-only table listing. The description mentions return fields but does not disclose any additional behavioral traits.

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

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

The description is extremely concise: two sentences that cover purpose, filtering, and return value. Every word earns its place, and key information is front-loaded.

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

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

Despite lacking an output schema, the description explicitly states the return fields. All parameters are optional and well-described in the schema. Combined with clear annotations (readOnlyHint, openWorldHint, etc.), the description provides complete contextual information for a listing tool.

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

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

Schema coverage is 100% with well-documented parameters. The description provides a brief summary of filter options but does not add significant meaning beyond what the schema already conveys. Baseline score of 3 is appropriate.

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

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

Description clearly states it lists/search available tables and specifies the filtering options and return fields. It distinguishes itself from sibling tools like table_info and get_data by noting that it returns table ids for use with those tools.

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

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

The description implies usage context by mentioning 'use with table_info / get_data', but does not explicitly state when not to use it or provide direct alternatives. The guidance is clear enough for an agent to infer appropriate use.

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

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

Beyond the annotations (which are all false), the description discloses important behavioral traits: rate-limiting, free usage, no impact on quota, and that the team reads feedback daily. No contradictions with annotations.

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

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

The description is concise and well-structured, starting with the core purpose, then usage guidelines, then constraints. 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 (sending feedback) and the lack of an output schema, the description is complete. It covers what the tool does, when to use it, how to structure feedback, and important constraints. No gaps remain.

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

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

Schema description coverage is 100%, but the description adds context beyond the schema, such as the character limit (2000 chars max) and the advice to be specific about which tool and error. It also reinforces the purpose of each enum value and provides guidance on the 'context' object fields.

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: to provide feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes itself from sibling tools by focusing specifically on feedback about Pipeworx tools/packs, and the input schema enumerates specific feedback types.

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

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

The description provides explicit instructions on when to use the tool (for bugs, features, data gaps, praise, or other) and what not to do (don't paste end-user prompts). It also mentions rate limits (5 per identifier per day) and that it's free and doesn't count against the tool-call quota.

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 openWorldHint. The description adds valuable context: data source ('CF analytics-engine'), no PII, caching behavior, and aggregation method. No contradiction with annotations.

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

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

The description is four sentences plus a bulleted list, front-loaded with the core function, then use cases, then technical details. Every sentence adds value with no redundancy or fluff.

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

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

Given one simple parameter and no output schema, the description covers data source, caching, and privacy. However, it lacks precise output shape (e.g., list of objects with counts). Slight gap but still adequate for a straightforward 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% and the schema's parameter description already explains the window enum and effect. The main description repeats this information without adding new semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window. It uses specific verbs ('returns') and resources ('top tools, top packs, total call volume'), and distinguishes from siblings by focusing on trending usage rather than general discovery or data retrieval.

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 provided: discovering hot data sources, confirming canonical choice, and checking alignment. The description implies when to use (trending analysis) but does not directly name alternatives or state exclusions. Still, the guidance is helpful and clear.

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

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

The description discloses internal details such as monotonicity checks, partition sum approximation, Jaccard similarity threshold, and placeholder filtering, going well beyond annotations. It is consistent with the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations.

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

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

The description is detailed and structured with clear sections (TWO MODES, SEMANTIC ANCHOR, PARTITION FILTER). While every sentence adds value, it is somewhat lengthy; minor trimming could improve conciseness. Information is front-loaded with the main purpose.

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

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

The description covers the main logic and output fields (opportunities[] and partition_check), but mentions 'skipped_low_similarity' without confirming it is part of the response. No output schema exists, so the description should fully specify the return structure. Minor inconsistency prevents a perfect score.

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?

Both parameters in the schema have descriptions, but the tool description adds significant value by explaining the role of each parameter in context, including examples and mode-specific behavior. This is helpful for correct invocation.

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 finds arbitrage opportunities on Polymarket, specifying two distinct modes (event and topic) with detailed explanations. The verb 'Find arbitrage opportunities' is specific and the resource (Polymarket) is clear, though it does not explicitly distinguish 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 explains when to use each mode (event slug vs. topic seed question) and provides examples. It does not explicitly state when not to use the tool or compare it to alternatives, but the mode guidance is clear and actionable.

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

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

Beyond idempotent/read-only annotations, the description reveals caching (1h), exclusion of fed_rate bets from ranking, grouping into three segments with detailed model explanations, and tradeable-edge knobs. No contradiction with annotations.

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

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

The description is lengthy but well-structured: purpose first, then detailed segment explanations, then knobs, caching, and exclusion. Each sentence adds necessary information for a complex tool, though could be slightly more concise without losing essential context.

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

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

Despite no output schema, the description fully explains the return structure (by_segment with three segments and their fields). Covers parameter usage, edge metrics, caching, and exclusion logic. Everything needed for correct invocation is present.

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

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

All 9 parameters have schema descriptions (100% coverage), and the description adds context for tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly), explaining how they filter opportunities. Also explains output fields like edge_pp_net and kelly_fraction.

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 scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific user goal ('what should I bet on today'). It distinguishes from siblings by focusing on disagreement detection rather than arbitrage or spread 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 provides explicit context for use (discovery without paging), mentions cache duration, and excludes fed_rate bets while directing to fed_rate_context. Implicitly differentiates from polymarket_arbitrage, but could be clearer about when to use alternatives like bet_research.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by detailing the return format: leg-by-leg prices in raw probability and spread in percentage points. This enhances transparency beyond annotations.

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

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

The description is concise and well-structured: a single sentence for purpose, a sentence for rationale, and clear bullet-style delineation of modes and return format. 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 lack of output schema, the description fully explains return values. It covers all usage scenarios (topic and explicit modes) and parameter interactions, leaving no ambiguity for correct invocation.

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

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

All three parameters are fully described in the schema. The description adds meaning by explaining the two operational modes and how parameters interact (topic auto-maps, explicit tickers override). This clarifies the relationship beyond individual parameter 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 defines the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It explains the value proposition (arbitrage signal) and distinguishes itself from sibling tools by covering both topics and explicit pairings.

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 (to capture arb signal from price differences) and provides two modes: topic shortcuts for common events and explicit tickers for custom pairings. While it does not explicitly state when not to use, the context is intuitive and no alternatives are needed given the unique cross-venue function.

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 and idempotent behavior. The description adds value by explaining scoping (per identifier) and the relationship with sibling tools, but does not cover potential edge cases like missing keys.

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 yet informative. Two sentences front-load the main purpose and immediately provide actionable guidance.

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

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

For a simple retrieval tool with full schema coverage and no output schema, the description is complete: explains when to use, scoping, and pairing with sibling tools.

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

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

The only parameter 'key' is fully described in the schema (100% coverage). The description repeats that omitting it lists all keys, adding minimal extra meaning beyond the schema.

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

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

The description clearly states the tool's function: retrieving a value saved via 'remember' or listing all keys. It distinguishes from sibling tools like 'remember' and 'forget'.

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

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

Explicitly describes when to use (look up stored context without re-deriving) and mentions alternatives (pairing with remember/forget). Provides context for scoping.

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

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

Description adds significant behavioral context beyond annotations: parallel fan-out to multiple sources, fallback logic, soft-fail for USPTO, and output format (changes[] grouped by source, total_changes count, citation URIs). No contradiction with annotations.

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

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

Description is comprehensive but efficient, with key information front-loaded. Could be slightly more concise, but every sentence adds value and it is well-organized.

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

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

Given no output schema, the description fully explains the return structure (grouped changes, total count, URIs). It also covers source details and fallback behavior, making the tool's behavior fully transparent for an agent.

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

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

Schema coverage is 100%, but description adds value by explaining the 'since' parameter accepts both ISO dates and relative shorthand with examples, notes 'type' is restricted to 'company', and clarifies 'value' can be a ticker or CIK. This goes beyond the schema's minimal 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?

Description explicitly states what the tool does: 'What's new with a company in the last N days/months?' and lists example queries. It also distinguishes from sibling tool 'entity_profile', making the purpose clear and distinct.

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

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

Provides explicit when-to-use guidance with examples ('what's happening with X', 'updates on Y') and explicitly tells when to use an alternative ('Use entity_profile instead when you want the static profile...'). Also describes fallback behavior between GDELT and GNews.

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?

Describes key-value storage, scoping, and 24-hour retention for anonymous sessions, which adds meaningful behavioral context beyond annotations. No contradiction with idempotentHint=true.

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

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

Three sentences, no wasted words, front-loaded with purpose, then usage guidance, then storage 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?

Complete for a storage tool: inputs well-defined, behavior explained, sibling tools mentioned. No output schema needed as success is implicit.

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

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

Schema coverage is 100%, so description doesn't need to add much; it provides naming examples but no new semantic detail.

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 saves data for later reuse, provides concrete examples (ticker, address, preference), and distinguishes it from sibling tools recall and forget.

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

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

Explicitly tells when to use it ('discover something worth carrying forward'), explains scoping by identifier, and mentions persistence differences between authenticated and anonymous sessions.

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

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

Annotations already mark the tool as readOnlyHint, idempotentHint, and non-destructive. The description adds value by revealing that each call cascades through multiple internal lookup endpoints, replacing 2-3 manual lookups, and that company input is auto-disambiguated. No contradiction with annotations.

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

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

The description is succinct yet informative, using a clear structure: overall purpose, usage hint, then type-specific details, ending with an efficiency note. It front-loads the key action and avoids repetition, though the type details could be slightly streamlined.

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

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

Given no output schema, the description adequately explains return fields for both types (e.g., ticker, CIK, RxCUI). It also covers the accepted inputs and mentions internal cascading. It does not address error handling or edge cases, but for a resolution tool, the essential information is present.

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

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

Input schema covers 100% of parameters with enums and descriptions. The description adds meaning beyond the schema: for the 'type' parameter, it explains what each type returns; for 'value', it lists valid input formats (ticker, CIK, name for company; brand/generic for drug) and mentions auto-disambiguation for company.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers needed by other tools, specifying supported entity types (company, drug) and the exact return fields. The phrase 'Use FIRST when you have a name but need an ID' further sharpens the purpose, distinguishing it from sibling tools like compare_entities or entity_profile.

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

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

The description explicitly says 'Use FIRST when you have a name but need an ID', providing a clear usage context. It details acceptable input formats per type but does not explicitly state when not to use it or mention alternatives among the sibling list (e.g., entity_profile for more details).

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 that it probes each entity, ranks, and returns a ranked list with score, confidence, signal density per entity. 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 plus a clarifying example. Front-loaded with core action. Zero 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 covers purpose, internal operation, and output format. Sibling tools provide context. Adequately complete for agent invocation.

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

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

Schema coverage is 100% with all parameters described. Description adds key context: first entity treated as 'subject', rest as competitors; context disambiguates common names. Provides value beyond schema.

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

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

Clearly states the tool compares AI visibility across multiple entities, uses ai_visibility_check internally, ranks by score, and surfaces most/least recognized. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (different type).

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 usefulness for competitive AI-marketing audits and gives an example question. Does not explicitly list when not to use or alternative tools, but context is clear enough for an agent to infer proper use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds metadata specifics but does not disclose additional behavioral traits like rate limits or prerequisites. With rich annotations, the description's added value is limited.

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

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

The description is two sentences: first defines purpose with specifics, second gives actionable usage advice. No fluff, efficient and front-loaded.

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

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

The tool has simple inputs, no output schema, but the description explicitly lists what the output contains (title, unit, last updated, variables). Combined with annotations, the description is sufficient for an agent to understand input, output, and usage workflow.

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 both parameters. The description does not add extra meaning beyond the schema, meeting the 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?

The description clearly states it returns metadata including title, unit, last updated, and full variable list with codes and value ids. It also specifies the usage context: 'READ THIS BEFORE get_data', which distinguishes it from sibling tools like get_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 explicitly advises using this tool before get_data to learn variable codes and value ids, providing clear when-to-use guidance. It does not explicitly mention alternatives or when not to use, but the context is straightforward.

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

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

Discloses return values (verdict types, structured form, actual value with citation, percent delta) and domain limitations (v1 company-financial claims). Annotations already provide readOnlyHint, idempotentHint, etc., with no contradiction.

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

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

Description is well-structured and efficient, though slightly lengthy. It front-loads the purpose and then provides necessary details 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 complexity and lack of output schema, the description fully explains return values and domain boundaries. It covers all necessary context for an agent to decide and invoke the tool.

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

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

Schema coverage is 100% with a description for the single 'claim' parameter. The description adds value by explaining acceptable claim types and giving examples, though the schema already covers the basics.

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

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

Description clearly states the tool fact-checks natural-language claims against authoritative sources, specifies supported domain (company-financial claims for US public companies via SEC EDGAR), and provides examples. It distinguishes itself from sibling tools by being specialized for claim validation.

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 when to use (checking truth of statements like 'Is it true that...?') and what it replaces (4-6 sequential calls). While it doesn't list alternatives, the specificity makes usage clear.

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