Nbp Pl

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

Annotations declare read-only, idempotent, non-destructive. Description adds behavioral details: default model is free, Anthropic requires BYO key, and it describes the return structure (per-model score, confidence, signals, raw_response). No contradiction.

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

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

Three sentences pack all essential info: purpose, default model, key parameters, return format, use cases. No filler; each 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?

Covers all 4 parameters, return structure, and use context. No output schema, but description explains return fields. Annotations cover safety. Complete for agent selection and invocation.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: expands entity description, lists supported model values, explains _apiKey purpose, and clarifies context usage. Enhances schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about a business and scores visibility (0-100 per model). It specifies the default model and distinguishes from sibling tools by mentioning scoring and specific return fields.

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 identifies use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Provides guidance on parameter usage (omit models for default, add _apiKey for Anthropic). Lacks explicit when-not-to-use vs siblings, 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral context: routing across 5,461 tools, argument filling, stable citation URIs, and a single fast call. It does not contradict annotations, but could disclose potential rate limits or response format details.

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

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

The description is front-loaded with 'PREFER OVER WEB SEARCH' and every sentence carries meaningful guidance: scope, examples, alternatives, and limitations. Although lengthy, it uses bullets-like structure and no filler, making it efficient for an agent to parse.

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 covers purpose, usage context, examples, alternatives, and behavioral expectations (citation URIs, speed). It is sufficiently complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% with all parameters being aliases for 'question', and the schema already describes the parameter clearly with examples. The description itself doesn't add extra parameter semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool routes factual questions to appropriate sources and returns structured answers with citations. It uses a specific verb ('routes', 'returns') and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and gives concrete examples of when to use it, plus specifies when to step up to ask_pipeworx_grounded or deep_research. It also notes it works on every tier and is fast, providing clear decision guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it is an experimental edge with candidate routing improvements, currently identical to the stable router, and falls back to nothing (i.e., still a full working router). 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 a bit longer than typical but every sentence carries meaningful information: beta status, identical router, current test state, usage instruction, and fallback guarantee. It is front-loaded with the purpose and structured logically, so the length is justified.

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 essential context: it is a beta universal router, currently matches the stable version, and is used for testing routing improvements. It also clarifies that it is a full working router with no fallback, and references the same response shape as ask_pipeworx. Given the high-quality annotations and schema, this is sufficiently complete.

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

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

Schema description coverage is 100%, with all six parameters (question and aliases) clearly documented in the schema. The description merely says 'same arguments' without adding any semantic detail beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states this is the beta version of ask_pipeworx, an identical universal router with the same tools and arguments. It distinguishes itself from the stable ask_pipeworx by emphasizing its experimental routing improvements, so the agent knows exactly what resource it targets.

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

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

Explicit guidance is provided: use it exactly like ask_pipeworx when you want the newest routing. It even notes that no candidate is currently active, meaning it matches ask_pipeworx exactly, and explains the purpose of comparing results against the stable router. This gives clear when-to-use context and implies the alternative (stable ask_pipeworx).

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, the description reveals key behaviors: refusal with specific reasons (not_in_source, no_tool_match, etc.), extraction 'using ONLY what the tool result contains,' and the extra LLM call cost. This is substantial contextual information that annotations don't provide. 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 efficient and well-structured: it opens with the core value proposition, explains the mechanism, details the return/refusal format, gives usage context, and ends with the cost tradeoff. No redundant sentences; all information is relevant and organized.

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

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

Despite lacking an output schema, the description fully specifies success and refusal return shapes, including refusal reasons. It addresses the tool's complexity, relationship to siblings, and usage guidance, making it 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% and the only parameter (question) is fully described with aliases. The description does not add parameter-specific semantics beyond that, but given the schema's completeness, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: hallucination-resistant answering with evidence extraction. It explicitly differentiates from ask_pipeworx by noting 'Same routing as ask_pipeworx' but adding grounded extraction. The return format with evidence and refusal reasons further clarifies its unique 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?

Provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also names the alternative tool ask_pipeworx and states the cost tradeoff ('Costs one extra LLM call'), making the decision 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 goes beyond annotations by detailing resolution, fan-out, response shapes, safety mechanisms (low confidence, closed markets, wide spreads), and resolution-rule risk. It reveals behavioral traits comprehensively.

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 very long and dense, albeit well-structured with sections. It could be more concise without losing critical 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 and lack of output schema, the description covers response shapes, edge cases, and safety checks thoroughly. It is complete for an agent to understand 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 description adds significant meaning beyond input schema: explains market input formats, depth enum values with defaults, and include_raw with usage guidance. Schema coverage is 100% but description enriches 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 researches a Polymarket bet by pulling relevant data in one call. The purpose is specific, but does not explicitly differentiate from sibling tools like polymarket_arbitrage or 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 explicit use cases such as 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It does not mention when not to use or alternatives, but the context is clear.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context: for company type, it pulls latest 10-K data with correct off-calendar fiscal year handling; for drug type, it pulls FAERS data. It also mentions sorting by primary metric and returning citation URIs, which are not in annotations.

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

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

The description is a single dense paragraph that front-loads user-intent examples. Every sentence provides essential information: purpose, usage guidance, data sources for each type, sorting behavior, and return value summary. 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 the tool's moderate complexity (two entity types, different data sources, sorting), the description covers all necessary aspects. It explains what data is pulled for each type, mentions correct fiscal year handling, notes the max 5 entities, and describes the return format (paired data + citation URIs). No output schema exists, but the description compensates adequately.

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%, providing clear enum for type and array constraints for values. The description adds value by explaining what each type retrieves (SEC EDGAR data for company, FAERS data for drug) and the expected value formats (tickers/CIKs for company, drug names for drug). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs, distinguishing it from sibling tool entity_profile which does single-entity lookup. The specific verb 'compare' and resource ('companies or drugs') are explicitly mentioned, and the examples map to user intents.

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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also lists natural language triggers like 'X vs Y' and 'rank these companies', making it easy for the agent to recognize appropriate contexts.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds constraints like 'max ~93 days, working days only', 'bid/ask for table C', and default behavior (latest rate). 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?

Single paragraph, front-loaded with main purpose, no redundant sentences. Every sentence provides essential information. Efficient and clear.

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

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

Given 6 parameters with full schema coverage and no output schema, the description adequately explains all invocation patterns, constraints, and differs from sibling. An AI agent can correctly select and use this 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?

Input schema covers all parameters (100% coverage). Description adds practical details beyond schema: maximum date range, working days constraint, and meaning of table C (bid/ask). Enhances understanding.

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

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

The description clearly states it retrieves PLN exchange rates for a single currency over time, specifies the verb and resource, and explicitly distinguishes from sibling 'exchange_rate_table' which returns the whole 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?

Explicitly says 'Use this for one currency; use exchange_rate_table for the whole list.' Also details when to use different parameters (latest, date, last_n, date range), providing clear guidance.

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

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

Goes far beyond the readOnly/idempotent annotations by disclosing decomposition into facets, parallel routing, findings packet structure with gaps[] and contradictions[], latency expectations, auth paywall, and semantic excerpting. No contradiction with annotations; adds rich behavioral context.

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

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

The description is dense but purposeful, covering auth, usage, behavior, and limitations in one paragraph. There is no redundant filler; every sentence provides necessary operational detail, though structuring into sections would improve scannability.

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

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

The tool is complex with no output schema, yet the description fully compensates by explaining the findings packet, gaps, contradictions, citation URI logic, edge cases like empty gaps for news topics, and expected latency. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema already fully describes both parameters, but the description adds context: depth:'thorough' is paid, explains second-hop recovery and contradiction scans, and gives latency expectations. For 'question', it reinforces the schema's guidance but adds actionable rationale ('decomposition is the point').

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

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

The description clearly defines the tool as grounded multi-source research across 1,419 structured data sources via parallel routing. It explicitly distinguishes itself from siblings: 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and when-not: single lookups or breaking news should use ask_pipeworx. Also mentions account prerequisites and alternative tools, covering exclusions and alternatives thoroughly.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds context about return format (schemas with examples, no second lookup) and usage advice, providing moderate added value beyond annotations.

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

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

The description is well-structured, front-loaded with purpose, lists domains efficiently, explains return value, and ends with usage guidance. Every sentence adds value, no waste.

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

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

Given no output schema, the description explains exactly what is returned (names, descriptions, schemas with examples) and that results are callable directly. Covers purpose, usage, and output fully for a discovery tool.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description mentions 'returns the top-N' hinting at limit, but adds no significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, lists many domains, and specifies it returns ready-to-call schemas. It distinguishes itself from sibling research tools by positioning itself as the first step for exploring available options.

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

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

Explicitly says when to use: 'browse, search, look up, or discover' and 'Call this FIRST when you have many tools available'. Implies when not to use (when you already know the tool or want one answer), but doesn't name alternatives explicitly.

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 transparently details the tool's behavior: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, and notes limitations (patents soft-fail due to USPTO sunset). Annotations indicate read-only, open-world, idempotent, non-destructive; description adds valuable context beyond annotations.

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

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

The description is comprehensive and front-loaded with example queries. While every sentence is useful, it is slightly lengthy. Could be trimmed without losing essential information.

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

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

Despite lacking an output schema, the description enumerates the expected return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and acknowledges limitations. Given the tool's complexity and the available annotations, the description is complete enough for an agent to understand what it will receive.

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

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

Schema coverage is 100%, and the description adds concrete examples (ticker 'AAPL', CIK '0000320193'), clarifies that names are not supported, and explains that the type parameter is currently limited to 'company'. This adds significant meaning beyond the schema.

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

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

The description explicitly states the tool's purpose: generating a full cross-source profile of a US public company in one parallel call. It provides specific example queries and distinguishes itself from sibling tools like resolve_entity and compare_entities.

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 advises when to use the tool ('ALWAYS PREFER over chaining single-pack lookups') and when not to use it (names not supported, suggesting resolve_entity instead). This provides explicit guidance on alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying the rate format (PLN per unit, per 100 for some minors) and the 404 error condition on non-working days. 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 a single paragraph of about 6 sentences, front-loading the main purpose. It is efficient with no fluff, though could be slightly more compact.

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 covers purpose, parameter behavior, and error conditions. It omits the exact return format (e.g., list of currency codes) but is sufficiently complete for a straightforward data retrieval tool.

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

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

Schema coverage is 100%, but the description adds clarity: defaults to latest, last_n ignored if date provided, and explains table letters. This goes beyond the schema's 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 clearly states it provides NBP exchange-rate tables with PLN rates for many currencies. It distinguishes between table types A, B, C and mentions options like date and last_n. The purpose is specific and differentiated from sibling tools like currency_rate.

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 table type (A for major, B for other, C for bid/ask) and warns about 404 on holidays/weekends. However, it does not explicitly compare against sibling tools like currency_rate for single-currency queries, which would improve guidance.

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

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

Annotations already signal destructiveHint=true and idempotentHint=true. Description adds context about sensitive data but no new behavioral traits beyond annotations.

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

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

Two sentences: first defines purpose, second gives usage guidance. No wasted words, front-loaded.

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

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

For a 1-param destructive tool with no output schema, the description fully covers what, when, and pairs. No gaps.

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

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

Schema coverage is 100% and schema already describes the 'key' parameter. Description only says 'by key' which adds no additional meaning 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 starts with 'Delete a previously stored memory by key' which is a specific verb+resource+mechanism. It distinguishes from siblings by naming 'remember and recall' as paired tools.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Pairs with remember and recall, implying alternatives. Lacks explicit 'when not to use'.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by explaining the process: fetches the page, extracts title/description/key links, and emits markdown. This provides behavioral context 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?

The description is concise at four sentences, front-loading the main purpose. It avoids unnecessary details, though the first sentence could be slightly more streamlined. Overall well-structured for an AI agent.

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

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

Although there is no output schema, the description clearly explains the output format (standard llms.txt markdown as a single text blob). It covers all parameters and the tool's operation. Missing some details like error handling or prerequisites, but sufficient 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 both parameters described adequately. The description does not add new semantic information beyond what the schema provides; it merely rephrases the purpose of the url and max_links parameters.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action (generate), resource (llms.txt), and output (standard markdown). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on generating the file rather than scanning or auditing.

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 three explicit use cases (client indexing, personal drafting, competitor auditing), giving clear context for when to use. It does not explicitly state when not to use or compare with sibling tools, but the use case list is helpful.

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 context about data availability (404 for weekends/holidays) and constraints (max window length, working days only), 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 that front-load the core purpose and then detail usage modes and constraints. Every sentence provides necessary information without redundancy, making it highly 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 absence of an output schema, the description mentions the unit and purity but does not specify the exact return structure (e.g., date-price pairs). However, the coverage of input modes and constraints is sufficient for basic usage, leaving minor 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?

With 100% schema coverage, the schema already documents parameters concisely. The description adds value by explaining default behavior, parameter interactions (last_n ignored if date/start_date given), and the working days constraint, improving semantic 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 retrieves the NBP accounting price of gold in PLN per gram of pure gold, with specific unit and fineness. It distinguishes itself by specifying the source and default behavior, though no direct sibling for gold price 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 elaborates on when to use each parameter: default latest, single date, last_n points, or date window with a max range of ~93 working days. It also notes when data is unavailable (weekends/holidays). No explicit alternatives are given, but usage modes are clear.

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

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

Annotations already provide readOnlyHint, destructiveHint, etc. The description adds value by detailing the returned fields (id, type, params, etc.) and the default active filter, which is not in 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: first states purpose and returns, second provides usage guidance. Efficient and clear, though could be slightly more 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 tool's simplicity (list with one optional param, no output schema), the description covers all necessary aspects: purpose, return fields, parameters, usage context. Annotations handle safety. Complete.

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

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

Schema coverage is 100% for the one parameter (include_inactive). The description mentions 'active subscriptions' implying default behavior, but does not add substantial meaning beyond the schema.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifies the resource (subscriptions) and verb (list), and lists the return fields. It effectively distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for when to use the tool.

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

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

Annotations only state readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false, revealing little. The description compensates by disclosing rate limits (5 per identifier per day), quota impact (free, doesn't count against quota), and processing cadence (digest read daily, affects roadmap). 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 longer than average but every sentence serves a purpose: definition, usage categories, exclusion rule, message guidance, and operational impact. It is front-loaded with the core purpose. Slightly dense but well-structured and scannable; 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?

For a feedback tool with three parameters and no output schema, the description fully equips an agent to decide when and how to invoke it. It covers purpose, accepted categories, exclusion criteria, message content guidance, rate limits, and quota behavior, leaving little ambiguity about the tool's role.

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 all three parameters with descriptions (100% coverage), so baseline is 3. The description adds useful behavioral guidance for the message parameter: describe issues in terms of Pipeworx tools/packs and avoid pasting end-user prompts. It does not add syntax details for type/context, but the schema already provides adequate semantics.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete feedback categories (bug, feature/data_gap, praise) and differentiates itself from sibling tools like ask_pipeworx or subscribe by focusing on reporting feedback about the Pipeworx connection itself.

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 scenarios (wrong/stale data, missing tool, praise) and a clear when-not-to-use exclusion: feedback about non-Pipeworx MCP servers should be filed elsewhere. It even offers a decision heuristic ('Pipeworx tool names are the ones this connection lists'), making tool selection unambiguous.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds caching details, no PII, self-aggregating signal, complementing annotations fully.

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 front-loaded with core function, then use cases, then 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?

For a simple read-only tool with one optional parameter, the description provides all necessary context. Return values are implied. 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 only parameter (window) 100%. Description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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 by window. It specifies the data source and scope, distinguishing it from siblings like 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?

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool, aligning use case). No explicit 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?

Extensive behavioral details beyond annotations: explains monotonicity checks, partition-sum check, semantic anchor with Jaccard threshold, placeholder filter, fill check against live CLOB depth, and conditions for rejecting trades. Annotations already indicate read-only, idempotent, non-destructive, and description adds rich context 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 long but well-structured with clear sections for modes, semantic anchor, partition filter, fill check, and output format. It front-loads the main purpose and uses technical but appropriate detail. Could be slightly more concise, but every sentence serves a 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?

Comprehensive coverage of the tool's behavior, including output structure (opportunities[], partition_check), internal checks, and trade recommendations. No output schema exists, but the description adequately describes return values. References another tool for custom sizing, showing completeness.

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

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

The description adds significant meaning beyond the schema: explains what event slugs or topics look like, provides examples, and describes the behavior of each parameter mode. With 100% schema coverage but no enums, the description enriches understanding of parameter usage and expected values.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific use cases, and the verb 'Find' plus resource 'arbitrage opportunities' is precise. It differentiates from siblings 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?

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also warns when not to trade (realizable_edge ≤ 0). However, it does not directly compare to sibling tools or state when to avoid the tool entirely.

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 extensively discloses internal behavior: model families (crypto_price, news_momentum, partition_overround, etc.), edge calculation, response segments, diagnostic info, and caching policy. No contradictions with annotations (readOnly, idempotent). Adds significant value beyond the structured fields.

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

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

The description is front-loaded with the purpose but is verbose and contains extensive detail that could be streamlined. While well-structured, it exceeds what is needed for concise communication.

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 (9 parameters, no output schema, rich internal logic), the description is exceptionally complete. It explains models, response structure, diagnostic information, and caching, fully compensating for the lack of an output schema.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds context on parameter interplay (e.g., min_kelly vs min_partition_leg_kelly) and usage scenarios, going beyond mere parameter definitions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market prices, using a specific verb and resource. It is built for 'what should I bet on today', which implies its use case, but does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 ('discover opportunities') and details configurable knobs for filtering, but lacks explicit when-not-to-use guidance or alternatives among sibling 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. The description adds value by explaining that snapshots are written on cache-miss (gaps in data), history depth is bounded by 60-day TTL, and decay is from daily closes. 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 detailed and front-loads the purpose. Every sentence adds value, but it is somewhat lengthy for an AI agent. The response format explanation is thorough but could be slightly more 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?

Given the tool has 2 optional parameters, no output schema, and rich annotations, the description fully explains the response format (tracked[], expired[], snapshot_dates[]) and each field. It also covers data source limitations, making it 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?

Input schema covers 100% of parameters. The description adds the clamp range for days (2-30) and clarifies the window parameter options (24hr, 1wk, 1mo) beyond the schema's default. This provides meaningful extra 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 the tool provides 'edge persistence and decay telemetry' and answers specific questions about edge duration and shrinkage. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on historical persistence rather than current snapshots.

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 includes a LIMITS section that clarifies history boundaries (60-day TTL, from snapshot enablement) and notes that decay numbers are from daily closes, not intraday. It does not explicitly mention alternatives, but the context implies when to use this tool versus others.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and warns about thin legs and directional risk. No contradiction with annotations.

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

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

The description is long but well-structured with clear mode separation and bullet-like listings. Every sentence provides necessary detail for correct usage, given the complexity and risk of misuse. Could be slightly tighter, but the structure is effective and front-loaded with 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?

Despite having no output schema, the description comprehensively lists all return fields for both modes, including verdict meanings and warnings. It covers edge cases (thin legs, partial fills) and definitions (clean/degraded/cannot_fill). For a complex tool, this level of detail is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context: explains parameter behavior in mode-specific terms (e.g., size_usd as 'max spend on buys, target proceeds on sells' for single-market, and 'settlement notional S (shares per leg)' for basket). It also notes defaults and clamps. This additional clarity justifies a 4.

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

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

The description clearly states the tool is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and differentiates between single-market and basket modes. It explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this check before acting on their signals.

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

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

The description gives explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the rationale (theoretical overround not capturable, partial fills create directional risk), helping the agent decide when to invoke the tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral details: compatibility warnings, temporal alignment, skipped counters, and the caveat that real spreads are rarer. 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 relatively long but well-structured with capitalized section headers (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence provides value, though it could be slightly more concise without losing 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 tool complexity (cross-venue spread, multiple modes, safety fields), the description is thoroughly complete. It explains response structure (leg-by-leg prices, matched spread) and safety fields in detail, compensating for the lack of output schema.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning by explaining the topic enum values, auto-fetching behavior, and overriding semantics for explicit tickers, going 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes and lists sibling tools, so the agent can differentiate.

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

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

The description provides explicit guidance on when to use each mode (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility warnings. It does not explicitly name alternatives but gives strong context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping by identifier and pairing with remember/forget, providing useful context beyond annotations.

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

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

Three concise sentences front-loaded with core action. Each sentence adds distinct value: action, use case, scoping and related tools. 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 retrieval tool with one optional parameter and no output schema, the description fully covers what the tool does, when to use, and its relationship to remembering and forgetting. Sufficient 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 covers the single parameter with description of optionality; description reinforces omission behavior. No additional parameter-level details beyond schema, meeting baseline for high coverage.

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

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

Clearly states the tool retrieves a saved value or lists all keys. Uses specific verb 'Retrieve' and resource 'value previously saved via remember', distinguishing 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?

Provides explicit when-to-use (look up context stored earlier, avoid re-deriving) and how (omit key to list all). Contrasts with remember and forget, giving clear context for 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?

Annotations already indicate read-only, idempotent, non-destructive. Description adds details on returned fields (source, citation_uri, raw payload), the effect of mark_read (flags events read so next call shows newer ones), and that it accesses a persisted feed. Adds value beyond annotations.

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

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

Four concise sentences, each adding distinct information. No redundant words. Efficiently covers purpose, parameters, behavior, and alternatives.

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 read-only list tool with no output schema, the description adequately explains return content and key behaviors (filtering, mark_read, polling). Minor gap: no mention of default limit or pagination beyond the schema's description.

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 all 5 parameters with descriptions. The description adds examples ('e.g. sec_8k'), clarifies that 'since' expects an ISO timestamp, and explains the behavior of 'mark_read' and 'unread_only'. This enhances understanding.

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

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

The description clearly states the tool 'pulls fired events from your subscription feed' and returns 'the most recent alerts', specifying the action and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Provides clear context for use: filtering by type and since, setting mark_read for read tracking. Mentions that polling works and points to an alternative script/dashboard URL. Lacks explicit when-not-to-use but is still helpful.

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 the annotations: it reveals fan-out to SEC EDGAR, GDELT/GNews fallback (with rate-limit handling), USPTO soft-failure, and the return structure. Annotations already mark it read-only and idempotent, and the description complements this 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?

Description is well-structured with front-loaded examples, clear explanation of sources, parameter details, return format, and alternative tool. Each sentence adds value, and length is appropriate 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?

Despite having no output schema, the description adequately describes the return (changes grouped by source, total_changes count, citation URIs). It covers fallback behavior, parameter formatting, and alternative tool. No major gaps given 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%, so baseline is 3. Description enhances by providing recommended default for 'since' ('30d' or '1m'), explaining 'value' accepts ticker or CIK, and noting 'type' only supports 'company'. This adds useful guidance 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?

Description clearly states the tool provides a change feed for a company over a time window, using examples like 'What's new with X'. It explicitly distinguishes from the sibling tool 'entity_profile', which provides static profiles instead.

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

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

The description gives clear use case examples (e.g., 'latest on Y', 'what happened to Z this week') and explicitly advises to use 'entity_profile' for static profiles. It also explains the tool fans out to multiple sources, setting appropriate expectations.

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

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

Annotations declare idempotentHint=true and destructiveHint=false, so description doesn't repeat that. But adds value with persistence details: scoped by identifier, 24-hour retention for anonymous, persistent for authenticated users. No contradiction.

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

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

Three sentences, front-loaded with purpose, then usage guidelines, then behavioral details. No unnecessary words; every sentence earns its place.

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

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

Given 2 required parameters, no output schema, the description covers purpose, usage, persistence, and pairing with siblings. It provides all necessary context for an agent to use this tool correctly.

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

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

Schema coverage is 100% with clear descriptions for key and value. Description mentions key-value pair and gives examples but does not add significant new semantics beyond what 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?

Description clearly states 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes itself from sibling tools 'recall' and 'forget' by explicitly mentioning them as companions.

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: 'Use when you discover something worth carrying forward...' and provides examples like resolved ticker, target address. Also instructs to pair with recall/forget, 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds significant context: cascading through multiple lookup endpoints internally, auto-disambiguation, and the exact citation URIs returned. This goes beyond annotations to explain internal behavior and output characteristics.

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

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

While long, every sentence earns its place: examples, usage priority, supported types with return values, and value-add note. Structured with SUPPORTED TYPES and clear formatting. Front-loaded with the most important usage 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?

No output schema, but the description explicitly lists return fields for each supported type and the citation URI format. It addresses disambiguation, accepted input formats, and the tool's purpose in a workflow. For a two-parameter tool with full schema coverage, this is complete.

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

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

Schema coverage is 100%, with detailed descriptions for both 'type' and 'value' including enum values and input examples. The description's additional explanations (e.g., auto-disambiguated for company) are helpful but largely redundant with the schema. Baseline of 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states it resolves user-spoken names to canonical identifiers required by other tools, with specific examples (ticker, CIK, RxCUI). It distinguishes from siblings by noting it is the first step when an ID is needed, which aligns with its name and title.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups. Supported types and input variations are listed, making the intended use cases clear. No exclusions needed because the tool is purpose-specific.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds it probes via 'ai_visibility_check', ranks, and returns per-entity metrics (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?

Three sentences, front-loaded with main action. 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?

No output schema, but description explains return format (ranked list with metrics). Parameters fully covered. Use case clearly described. Complete for a comparison 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 100% means baseline 3. Description adds value by noting first entity is treated as 'subject' for narrative, and that 'context' disambiguates common names.

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?

Clear verb 'Compare' with specific resource 'AI visibility across multiple entities'. Distinct from sibling tools like 'ai_visibility_check' (single entity) and 'compare_entities' (generic).

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 use case: 'competitive AI-marketing audits' with example question. Implies use when comparing multiple entities, but does not explicitly state when not to use or name alternatives.

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

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

The description adds significant behavioral context beyond annotations: it details that it fans out to two services, handles partial failures gracefully, and notes that bundlephobia's first measurement can take 5-30 seconds. It also mentions that sources_failed will list timeouts. No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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 reasonably concise given the complexity of the tool. It is front-loaded with the main purpose and use case, then details return fields, limitations, and error handling. Each sentence adds value, though it could be slightly shorter by omitting the list of return fields since they are detailed later.

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 lists all return fields (summary block fields, per-advisory detail, links, alternative versions). It covers ecosystem limitations, partial failures, and timing behavior. For a two-parameter tool, this provides complete 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?

The input schema already describes both parameters with 100% coverage (package name, version). The description adds value by clarifying that scoped packages (e.g., '@types/node') are accepted and that version defaults to the latest. This supplements the schema without redundancy.

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

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

The description clearly states the tool's purpose as a composite check for evaluating npm packages, specifying it fans out to deps.dev and bundlephobia. It uses specific verbs like 'scan' and refers to the exact question it answers ('should I add this npm package to my project'). It distinguishes itself from siblings by focusing solely on npm packages and mentioning its composite nature.

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 tells when to use the tool: when an agent asks about safety, popularity, or size of an npm package. It also specifies limitations: NPM ecosystem only for v1, and references deps.dev:version for other ecosystems. This provides clear guidance on when not to use it and 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?

Discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and input limit (200K chars with truncation flag). No contradiction with annotations; adds significant detail beyond the already safe idempotent/read-only hints.

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

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

Five sentences with front-loaded core action. Each sentence adds value: explanation, examples, pairing, technical details, limit. Slightly long but not wasteful.

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

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

Despite no output schema, description thoroughly covers return values (passages, character offsets, similarity scores) and usage context. Pairs with sibling tool, making integration clear. Complete for a search tool with strong annotations.

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

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

Schema coverage is 100% with parameter descriptions. The description reinforces the purpose of each parameter (e.g., query examples) but does not add new semantic details beyond what the schema provides. Meets baseline for high coverage.

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

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

Clearly identifies verb (semantic search), resource (inside a fetched record), and scope (returns passages with offsets and scores). Distinguishes from sibling tool ask_pipeworx_grounded by describing the relationship.

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?

States when to use (record too big for prompt) and how to pair with ask_pipeworx_grounded. Mentions character cap and truncation. Does not explicitly state when not to use (e.g., for small texts), 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?

Annotations already declare non-read-only, non-destructive, open-world, idempotent. Description adds constraints like OAuth requirement, SMS cap, webhook auto-disable, and delivery channel details, far exceeding annotation hints.

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

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

Front-loaded with purpose and requirements, then logically organizes types and delivery channels in separate paragraphs. 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?

With no output schema, description returns subscription id. Covers all parameters, delivery options, and edge cases (SMS verification, webhook secret, auto-disable). Complements sibling tools effectively.

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 enriches each parameter with real-world examples (e.g., sec_8k with items codes), explains required fields for clinical_trial, and details delivery format and constraints.

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 creates a subscription to a live-data event stream, distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by specifying proactive monitoring and returning subscription id.

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 requires Pipeworx OAuth account and notes that anonymous/BYO cannot persist, giving when-to-use context. Does not explicitly list alternatives but implies them through sibling 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?

Description discloses that it returns example questions with tool+argument shapes drawn from a live catalog. Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds context about the dynamic nature and meta-tool learning capability, 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?

The description is detailed but front-loaded with trigger phrases and a clear purpose. Every sentence adds value, though it could be slightly more concise. Still well-structured 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 tool's role as an onboarding entry point with a single optional parameter and no output schema, the description fully covers usage, examples, and relationship to sibling tools. It is complete for its purpose.

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

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

Schema coverage is 100% and the description not only lists the topic parameter but explains its purpose and the exact values (finance, pharma, etc.), providing 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 explicitly states the tool returns category-bucketed example questions for Pipeworx, with exact tool+argument shapes. It includes multiple trigger phrases ('what can I ask?') and clearly distinguishes from siblings like ask_pipeworx.

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 arguments for full spread, or pass a topic to focus. Directly says 'Use this FIRST when you do not yet know what Pipeworx can do', which gives clear context for usage.

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 crucial behavioral context beyond annotations: ownership enforcement and deactivation (not deletion). This explains the idempotentHint and destructiveHint, making the tool's behavior fully transparent.

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

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

Two concise sentences, front-loaded with the main action. 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?

Adequately complete for a cancellation tool: explains what happens to the data (deactivated, not deleted) and historical availability. No output schema exists, but the description covers the essential behavioral outcome.

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 'id' is fully described in the input schema. The tool description does not add additional meaning beyond what the schema provides, so baseline score applies.

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

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

Clearly states the action 'Cancel a subscription by id' with the resource and identifier. Distinguishes from sibling tools like subscribe and list_subscriptions by specifying the cancellation operation and ownership enforcement.

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?

Implicitly guides usage by mentioning ownership enforcement and that the subscription is deactivated (not deleted). No explicit when/not-to-use instructions, but the context is clear given the sibling set.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds behavioral details: the two verification paths, return of verdict with five categories (confirmed, approximately_correct, refuted, inconclusive, unsupported), actual value with pipeworx:// citation, and reasoning. It also notes performance benefit (replaces 4-6 sequential calls), but does not contradict annotations.

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

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

The description is well-structured with representative examples up front, followed by technical detail. It is not overly verbose, though the final point about replacing 4-6 calls could be integrated more succinctly. Overall, it earns its length.

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

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

Given there is no output schema, the description fully explains return values (verdict, actual value, citation, reasoning) and processing logic. It covers both claim types with appropriate detail, making the tool's behavior 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% with both parameters already described. The description provides context for using tolerance_pct (e.g., hallucination detection with 1-2%) but does not add significant meaning 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 defines the tool's purpose as verifying natural-language factual claims against authoritative sources. It provides multiple example phrasings ('Is it true that…', 'fact check') and distinguishes this tool from siblings by detailing two specific processing paths: structured SEC EDGAR/XBRL for company-financial claims and grounded pipeline for other claims.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' While it does not enumerate when not to use or directly compare to each sibling, the description implicitly differentiates by focusing on fact verification, leaving research or question-answering to other tools like deep_research or ask_pipeworx.

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