Frinkiac

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 behavioral details: default model is free, Anthropic requires BYO key and direct payment, and returns per-model data. It discloses key behavior beyond annotations.

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

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

The description is concise (4-5 sentences), front-loaded with the core purpose, and every sentence provides essential information. No redundancy or filler.

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

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

Given the parameter descriptions, annotations, and lack of output schema, the description adequately explains what the tool does, how to use it, and what to expect in return. It covers edge cases (optional API key, model selection) and provides sufficient context for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaning by explaining the default model, the purpose of _apiKey (BYO key, direct payment), and how 'context' helps disambiguate. This exceeds the baseline of 3.

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

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

The description clearly states the tool probes LLMs for knowledge about entities and scores visibility (0-100). The verb 'probe' and resource 'one or more LLMs' are specific, and the use cases (AI-marketing audits, pre-launch checks) distinguish it from siblings like 'scan_competitor_ai_presence'.

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

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

The description provides clear use contexts (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly list when not to use or compare directly to sibling tools. However, the context is sufficient for an agent to determine applicability.

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 convey safety (readOnly, idempotent, non-destructive). The description adds meaningful behavioral context: it returns structured answers with pipeworx:// citation URIs, is a fast single call, works on every tier, and handles routing to many sources. It does not contradict annotations and goes beyond the structured metadata.

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 earns its place: it front-loads the core preference, explains the mechanism, gives explicit triggers, provides examples, and lists sibling tools with step-up guidance. It is well-structured and not redundant, though slightly verbose.

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

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

Given the tool's complexity (a router over thousands of sources) and no output schema, the description sufficiently explains the return value ('structured answer with stable pipeworx:// citation URIs') and covers the main use cases and alternatives. It could more explicitly address behavior on out-of-scope queries, but overall it is complete enough for an agent to choose and invoke it correctly.

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

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

Schema description coverage is 100% (question plus five aliases each with descriptions). The description goes further by providing six concrete examples that illustrate the expected natural language input, which helps the agent form appropriate queries. This adds value beyond the bare schema, though it does not introduce new syntax.

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

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

The description clearly states the tool's function: it routes questions to the appropriate tool from 5,313 tools across 1,392 verified sources, fills arguments, and returns structured answers with citation URIs. This specific verb+resource+mechanism fully distinguishes it from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and explicitly says 'START HERE for most questions'. It provides clear when-to-use triggers (e.g., 'what is', 'look up', 'find') and names alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, plus a note about breaking news. This is ideal usage 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. The description adds valuable context: it's a beta with candidate routing improvements, currently no active candidate, and it's a full working router with no fallback. This goes beyond the structured annotations to explain the current experimental state and behavior.

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

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

The description is four sentences, each delivering distinct information: beta status, identical router definition, current no-candidate state, and usage guidance. It is somewhat verbose but every sentence earns its place, and the key points are front-loaded.

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

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

Given the complexity of a router with 5,313 tools and no output schema, the description covers essential aspects: what it is, current state, usage, relationship to stable version, and response shape (same as ask_pipeworx). It is complete enough for an agent to select and invoke 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?

The input schema has 100% coverage with detailed descriptions for all parameters (question plus aliases). The description mentions 'same arguments' but does not add any new parameter-specific semantics beyond the schema, so the 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 this is a 'Beta version of ask_pipeworx' and identifies it as a 'universal router' with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx and mentions the experimental edge, making its purpose and differentiation evident.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It does not explicitly mention alternatives like ask_pipeworx_grounded, but it clearly conveys when to use this tool vs the 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?

Annotations already declare readOnly/openWorld/idempotent, and the description adds detailed behavioral context: the exact return shape, refusal reasons, and the constraint that answers are extracted 'using ONLY what the tool result contains.' It also discloses the extra LLM call cost, which is valuable beyond the annotations.

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

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

The description is dense but every sentence contributes: purpose, mechanism, return format, refusal conditions, use cases, and cost trade-off. It front-loads the key differentiator (hallucination resistance) and avoids fluff.

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

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

For a tool with no output schema, the description fully specifies the success and refusal return structures, including all refusal_reason enum values. It also covers performance cost, use cases, and an alternative, making it self-sufficient 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?

All six parameters are aliases for 'question,' and the schema already covers 100% with descriptions. The description adds no further parameter-level detail, so the baseline of 3 applies per schema coverage.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode for high-stakes reads,' with a specific verb (extracts grounded answers) and resource (Pipeworx tool routing). It distinguishes itself from the sibling ask_pipeworx by adding refusal logic and an extra LLM call, making its unique purpose explicit.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also names the alternative: 'prefer ask_pipeworx for casual lookups,' covering both usage and exclusion.

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

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

Despite annotations already providing readOnlyHint and idempotentHint, the description adds extensive behavioral details: fan-out examples for different bet types, response shapes, resolver contract with confidence levels, parent event extractor, news fallback handling, safety short-circuits for low confidence and closed markets, spread warnings, and cancellation rule parsing. 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 very long and includes many details (fan-out examples, resolver contract, parent extractor, etc.). While each section adds value, the overall length reduces conciseness. The structure has clear sections (e.g., CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES), but the density could be overwhelming for quick scanning.

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

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

Given the tool's complexity (multiple data sources, classification, resolution matching), the description covers all critical aspects: input formats, classification categories, detailed fan-out examples, response structures, resolver confidence handling, parent event extraction, news fallback, safety mechanisms, and cancellation rules. Despite no output schema, the description compensates fully with response shape details.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value beyond the schema: it explains that 'market' can be a slug, URL, or question text; describes 'depth' with quick vs. thorough defaults; and provides practical guidance for 'include_raw' (recommended false). Examples further clarify parameter usage.

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

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

The description starts with a specific verb-resource pairing: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the input types (slug, URL, question text) and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on general research. This is a clear, actionable purpose.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' These are clear scenarios. However, it does not explicitly contrast with sibling tools or state when not to use it, though the use cases are well-specified.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds no additional behavioral insights (e.g., rate limits, auth needs, or output format). Since annotations cover core behavior, a score of 3 is appropriate.

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

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

The description is extremely concise (7 words) but lacks structure and completeness. It conveys the core resource and scope but is almost too brief to be useful.

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

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

The tool has a simple input schema, helpful annotations, and an output schema. The description provides the essential context (resource and key parameters) but does not elaborate on the tool's behavior beyond what is already in the schema and annotations. It is minimally 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?

The description reiterates the parameter names from the schema without adding new semantics. The 'show' parameter lacks description in both the schema and description, resulting in incomplete parameter documentation. With 67% schema coverage, a 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 identifies the resource ('Caption') and scope ('specific (episode, timestamp)') but lacks an explicit verb (e.g., 'Get', 'Retrieve'). It does not differentiate from sibling tools like 'search' or 'search_within' which could also retrieve captions.

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

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

No usage guidelines are provided. The description does not indicate when to use this tool over siblings such as 'search' or 'search_within', nor does it mention any prerequisites or constraints.

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 important context: it pulls the latest data from specific sources, handles off-calendar fiscal years, and returns sorted results with citation URIs. No contradictions.

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

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

The description is dense but covers all key aspects in a single paragraph. It is front-loaded with example queries. While not overly verbose, it could be slightly more structured (e.g., separate lines for company vs drug). Still, every sentence adds value.

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

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

For a tool with two parameters, no output schema, and annotations covering safety and idempotence, the description is highly complete. It explains when to use, what data is pulled, how results are sorted, and what output format to expect (paired data + citation URIs). 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?

The input schema has 100% coverage for both parameters, providing enums and descriptions. The description adds further meaning: explains the 'type' parameter's data sources (company vs drug) and the 'values' parameter's expected format (tickers/CIKs for company, names for drug). This goes beyond the schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It includes example queries ('compare X and Y', 'rank these companies') and specifies what data is retrieved for each type (SEC EDGAR/XBRL for companies, FAERS for drugs). This distinguishes it from sibling tools like sequential lookups.

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

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

The description explicitly recommends preferring this tool over sequential single-pack lookups when comparing entities. It provides concrete use cases (e.g., 'which is bigger/better'). However, it does not explicitly state when not to use it, though the preference is clear.

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

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

Despite annotations declaring read-only/open-world/idempotent, the description adds extensive behavioral detail: account requirements and paid tier for 'thorough', latency expectations (15-60s, up to ~90s), the never-invented gaps[] behavior, semantic excerpting instead of head-truncation, contradictions[] scanning, and hop/citation_uri fields. 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 every sentence carries operational value—account gating, alternatives, output shape, latency, and performance nuances are all included. It front-loads the critical account/login requirement and the alternative tool. Slightly dense, but appropriate for the tool's complexity.

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

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

For a complex tool with 2 parameters and no output schema, the description fully covers return format (findings packet with evidence, confidence, source, fetched_at, citation), limitations, timing, account requirements, and alternative routing. The lack of an output schema is compensated by the detailed description of what the agent can expect.

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

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

Schema coverage is 100% (both question and depth have descriptions), so baseline is 3. The description adds valuable context beyond the schema: it explains depth values in terms of facet counts, hop recovery, and contradictions[] scanning, and clarifies that broad/multi-part questions are expected. This elevates it above the baseline.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's 1392 structured data sources in one call, explicitly noting 'this is NOT open-web search.' It distinguishes from siblings by naming ask_pipeworx as the alternative for single lookups and news, making the purpose unmistakable.

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

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

Provides explicit when-to-use ('Best for broad/multi-part questions over structured data') and when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), naming alternative tools and explaining why deep_research would fail (empty gaps[]).

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. Description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No contradiction with annotations.

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

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

Description is front-loaded with purpose and usage, includes a list of domains, and explains return value. Every sentence adds value, though could be slightly more condensed. Still efficient and well-structured.

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

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

Given the large sibling set, description clearly defines its role as a discovery tool to be used first. It explains return format (top-N with schemas and examples) without needing an output schema. Complete for the tool's complexity.

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

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

Schema coverage is 100% with all 6 parameters described. Description mentions default limit 20 and max 50, and explains that query accepts multiple aliases (task, q, description, search), adding value beyond the schema.

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

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

Description starts with 'Find tools' and lists specific domains like SEC filings, FDA drugs, etc., distinguishing it from sibling tools like search (which returns data) and discover_tools is for browsing available tools. Explicitly says 'Call this FIRST when you have many tools available' to differentiate from direct-answer 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 'Use when you need to browse, search, look up, or discover what tools exist for:' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Clear when-to-use and when-not-to-use guidance.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details the tool's parallel fan-out across multiple sources, soft-failure for patents, and returned fields. No contradictions with annotations. Adds useful 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 lengthy but well-structured, starting with example queries to quickly convey purpose. Every sentence adds value, though some redundancy exists (e.g., repeating input constraints). Appropriate length for the tool's complexity.

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

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

Given the tool's complexity and lack of output schema, the description is comprehensive. It covers input constraints, data sources, returned fields, fallback behavior, and limitations. Lacks details on pagination or rate limits, but those are minor for a one-shot profile.

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%. Description adds meaning: explains that only 'company' type is supported, and clarifies that value can be ticker or zero-padded CIK, with names requiring resolve_entity first. This enhances the schema's descriptions.

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

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

The description clearly states the tool's purpose: generating a holistic cross-source profile of a US public company in one parallel call. It provides specific example queries and lists data sources and returned fields, distinguishing it from siblings like 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?

Explicitly states to prefer this tool over chaining individual lookups for holistic views. Specifies acceptable inputs (ticker or CIK) and directs users to resolve_entity for names. Includes fallback behavior for patents and notes limitations.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds no additional behavioral context beyond 'Delete,' which is already conveyed. No contradiction, but no extra value.

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 well-structured sentences that front-load the action and purpose. Every word earns its place; no 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 delete tool with one parameter and clear annotations, the description adequately covers usage context. It could mention idempotency, but it's not necessary given the annotation.

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 mentions 'by key,' but provides no additional meaning beyond what the schema already documents for the 'key' parameter.

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

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

The description clearly states 'Delete a previously stored memory by key,' which is a specific verb and resource. It pairs with remember and recall, but does not explicitly differentiate when to use this over other tools, so it's not a 5.

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 the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' This gives clear context and pairs with sibling tools, providing excellent 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, idempotentHint, and non-destructive nature. The description adds valuable context: fetches the page, extracts title/description/links, and emits markdown format. It does not detail error handling or limits, but covers core behavior.

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

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

The description is a single paragraph with front-loaded purpose. It includes some fluff (e.g., 'production-ready') but remains efficient and easy to parse. Could be slightly tighter, but good.

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 parameters, full schema coverage, no output schema, and annotations present, the description covers purpose, usage, output format, and basic behavior. Some details like prerequisites (internet access) or error scenarios are missing, but overall fairly 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%, and the description adds minimal additional meaning—it repeats the URL requirement and mentions max_links default/max values already in 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 generates a llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes itself by mentioning AI crawlers and the standard markdown format.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor visibility. It lacks explicit exclusion scenarios but gives 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 already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return fields and 'active subscriptions' detail. No contradiction.

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

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

Two sentences, front-loaded with purpose, 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?

Simple tool with one optional param, no output schema. Description covers purpose, when to use, return fields. Fully adequate.

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% with clear parameter description. Description does not add meaning beyond schema; baseline 3.

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

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

Clear verb 'List' and resource 'subscriptions' specified. Specifies 'caller's active' distinguishing scope. Returns fields listed. Distinct from siblings like subscribe/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 context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear when-to-use guidance, though no 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?

Description discloses rate limiting (5 per identifier per day), that it's free and doesn't count against quota. Annotations show no behavioral hints, so description fully compensates with useful transparency about usage costs and constraints.

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 concise (6 sentences), well-structured, and front-loaded with the core purpose. Every sentence adds value—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?

Covers what, when, how, and constraints (rate limit, quota). No output schema needed; description is self-contained. For a simple feedback tool, it is fully 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% and schema already explains parameters well, but description adds practical guidance: 'be specific, 1-2 sentences typical, 2000 chars max' and 'don't paste the end-user's prompt.' This enriches semantics beyond schema, justifying above baseline.

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

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

Description clearly states the tool sends feedback to Pipeworx about bugs, feature requests, data gaps, or praise. It distinguishes itself from the sibling tools, none of which are feedback-oriented.

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

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

Explicitly tells when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt, describe issue in terms of Pipeworx tools). Also mentions team reads digests daily and rate limits.

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

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

Describes data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). This adds significant context beyond annotations (readOnly, openWorld, idempotent). 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?

Very concise: short sentences, bullet points. Every sentence adds information. No fluff.

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

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

Given no output schema, description adequately explains return values (top tools, packs, total call volume) and caching. Single parameter is well-documented. Complete for agent decision-making.

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 window parameter completely. Description adds value by explaining shorter vs longer windows (hot vs steady-state). Since schema coverage is 100%, baseline is 3, but extra context raises to 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?

Description clearly states it returns top tools, packs, and total call volume over a window. It uses specific verb (returns) and resource, and distinguishes from sibling tools like discover_tools by focusing on what other agents are calling.

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 lists three use cases: discovering hot data sources, confirming canonical choice, and seeing alignment. However, it does not mention when not to use or compare to alternatives like search or discover_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 safe, read-only, idempotent behavior. Description adds extensive behavioral context: partition checks, semantic anchor (Jaccard similarity), placeholder filtering, fill check against live CLOB depth. No contradictions with annotations.

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

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

Description is detailed but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence provides necessary information for correct tool usage. Could be slightly more concise, but the complexity justifies the 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?

Despite no output schema, description fully explains the response structure (opportunities array, partition_check, fill check fields). Covers scanning modes, filters, and trade recommendations. Sufficient for an agent to select and use the tool correctly.

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

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

Schema coverage is 100% with descriptions for event and topic. Description goes well beyond by detailing how each parameter affects behavior (event mode walks child markets, does date/threshold ordering; topic mode searches related events, flattens markets). Also explains missing parameter defaults to trending_scan.

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

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

Description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and explains the no-argument default (trending_scan). This is specific and differentiates from sibling tools like polymarket_edges.

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

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

Explicitly says when to use which mode: no args for trending_scan, event for a specific market, topic for cross-event scan. Also provides fill-check guidance recommending not to trade when realizable edge ≤ 0, and directs custom sizing to polymarket_fill_risk.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral context: caching (1h at KV level), response structure (by_segment with three segments, diagnostics), edge calculation details (slippage, Kelly fractions, model families), and tradeable-edge knobs. No contradictions with annotations.

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

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

The description is relatively long but well-structured with clear sections: overall purpose, three model segments, tradeable-edge knobs, and response top-level. Every sentence adds value, though some parts are dense with parentheses and nested explanations. It is logically organized and front-loads the core 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?

Given no output schema, the description compensates by detailing the response structure (by_segment, diagnostics, fed_candidates) and all edge calculation details. With 9 parameters and high complexity, the description covers everything needed for an agent to use the tool effectively, including cache behavior and filter explanations.

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 9 parameters described. The description adds significant meaning beyond the schema, e.g., explaining that slippage_pp should account for Polymarket's zero fees but bid/ask spread, and why min_partition_leg_kelly is needed because partitions ignore min_kelly. This helps agents choose and set parameters correctly.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, distinguishing it from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement and three specific segments (model_driven, structural_arbitrage, concentrated_longshot). It uses specific verbs (scan, return) and resources (Polymarket markets, Pipeworx data).

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

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

The description explicitly explains the tool is built for 'what should I bet on today' and that it allows discovering opportunities without paging hundreds of markets. It also notes that Fed bets are excluded from ranking, providing context. However, it does not explicitly mention when not to use it or direct to alternatives among siblings, though the detailed context compensates.

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

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

The description adds substantial behavioral context beyond annotations: it explains the data source, response structure (tracked, expired, snapshot_dates), field meanings (trend, decay_pp_per_day), and data limitations (TTL, gaps). No annotation 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 well-structured but somewhat verbose. It front-loads the purpose and then provides comprehensive details. Every sentence adds value, but it 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 no output schema, the description thoroughly explains the response (tracked[], expired[], snapshot_dates[]), including field semantics and limitations. It fully covers what the tool returns and its constraints.

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% (both parameters described). The description adds context: defaults (days=14, window='1wk'), clamping (2-30), and how days/window affect the response. It also explains the RESPONSE structure, adding 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?

The description states it provides 'edge persistence and decay telemetry' from daily snapshots, clearly answering what the tool does. It distinguishes from sibling tools like 'polymarket_edges' by focusing on historical tracking and decay metrics.

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 answers the core question of when to use the tool ('how long has this edge existed and is it shrinking?') and contrasts fresh vs. old edges. It also includes LIMITS, but does not explicitly compare to alternatives beyond its own purpose.

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. The description adds valuable behavioral context: walks the ladder, returns detailed fill metrics, and highlights the dominant loss mode (partial fills converting arb to directional position). 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 well-structured with capitalized mode headings and key warnings (USE THIS). While dense, it is efficient given the complexity of two modes. Slightly verbose but 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?

Despite no output schema, the description lists all return fields for both modes, explains the verdict, and covers risk scenarios. Complete for an agent to understand what to expect and how to interpret results.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains modes (market vs event), default auto detection for basket side, and clarifies size_usd interpretation for basket as settlement notional. Enriches understanding beyond schema.

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

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

The description clearly states it checks realizable-vs-theoretical edge against live order-book depth. It explicitly distinguishes two modes (single-market and basket) and differentiates from siblings by specifying when to use this tool before arbitrage or edge trades.

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

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

It provides explicit guidance: use this before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It warns about theoretical overround being uncapturable on thin books and that partial basket fills lead to unhedged directional risk.

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

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

Beyond annotations (readOnly, idempotent), description details response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and honestly acknowledges when spreads are meaningless. 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?

Long but well-organized with clear sections. Some redundancy (e.g., repeated 'pre-mapped ≠ tradeable' emphasis). Could trim minor verbose phrasings.

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 covers response fields and safety conditions comprehensively. Lacks a concrete output example to aid agent understanding. Still very strong.

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

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

All 3 parameters have schema descriptions (100% coverage). Description adds operational context: hierarchical override logic (topic vs explicit), examples, and clarifies how parameters interact. Every parameter's semantics are fully explained.

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

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

Description clearly states it computes cross-venue spreads between Kalshi and Polymarket with two modes (topic shortcuts or explicit tickers). Distinguishes from siblings by focusing on cross-venue arbitrage signal.

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?

Describes when to use topic vs explicit modes, warns most topics return compatibility warnings, and explains conditions when spreads are invalid. However, does not mention alternative tools (e.g., polymarket_arbitrage) for intra-venue spreads.

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, idempotentHint, etc. The description adds no extra behavioral context beyond the obvious.

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

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

The description is extremely short and front-loaded, but lacks structure or additional detail that would justify its brevity.

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

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

Given the presence of an output schema, the description does not need to explain returns, but it fails to explain the input parameter or provide usage patterns, making it incomplete.

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 0%, and the description does not explain the 'show' parameter or its allowed values. This leaves the agent with no guidance on how to use the parameter.

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

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

The description clearly states it returns a random screencap and its caption. However, it does not distinguish from sibling tools like 'caption' or specify the source beyond examples.

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

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

No guidance on when to use this tool or alternatives. The description is too brief to provide context for appropriate use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable context about scoping and pairing with remember/forget, enhancing transparency.

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

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

Single, well-structured sentence front-loads purpose, then provides usage scenario and scoping. 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?

Tool is simple with one optional parameter, no output schema, strong annotations. Description covers all needed aspects: retrieval, listing, scoping, pairing. 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% with description for 'key' parameter. Description adds no new semantics beyond what schema already provides (omit to list all keys is in schema description).

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

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

The description clearly states the tool retrieves a saved value or lists keys, with specific use cases (ticker, address, notes). It distinguishes from siblings remember and forget.

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

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

Provides clear context for when to use (look up stored context) and scoping info (anonymous IP, BYO key, account ID). Does not explicitly exclude alternatives but pairs with siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' explaining a side effect 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?

Four sentences, front-loaded with the main action, no wasted words. Efficiently explains functionality, filtering, and behavioral flag.

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

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

Despite having no output schema, the description fully explains the return structure (source, citation_uri, raw payload) and covers optional parameters. For a simple read-only tool, this is complete and actionable.

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

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

Schema coverage is 100%, so description adds minimal extra meaning beyond parameter descriptions. It reinforces the purpose of filtering by type/since and effect of mark_read, but doesn't introduce new 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 clearly states 'Pull fired events from your subscription feed' and specifies the return structure (source, citation_uri, raw payload). It distinguishes from sibling tools like list_subscriptions by focusing on recent alerts from the feed.

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

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

Description mentions polling works fine and provides an alternative endpoint for scripts/dashboards. However, it does not explicitly define when not to use this tool or compare to other subscription-related siblings.

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

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

Discloses fan-out to multiple sources, fallback on rate limits/5xx, soft-fail for USPTO, parallel execution, and return structure. Annotations (readOnlyHint, idempotentHint, destructiveHint=false) are consistent and supplemented with operational 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?

Concise single paragraph that front-loads common user queries, uses examples, and packs essential details without redundancy. 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?

Despite no output schema, the description specifies the return format (changes grouped by source, total_changes, citation URIs). Covers error handling (soft-fail), parameter behaviors, and alternatives. No 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?

Adds significant value beyond 100% schema coverage: explains `type` only supports 'company', `value` accepts ticker or CIK with examples, `since` accepts ISO date or relative shorthand with recommendation. Provides fallback and usage context for each parameter.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, listing the sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishing from entity_profile. Example queries at the start make the purpose immediately understandable.

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 this tool ('What's new with X') versus entity_profile ('static profile'). Gives parameter guidance for `since` (prefer '30d' or '1m') and explains the GDELT→GNews fallback logic.

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

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

Annotations provide idempotentHint=true, destructiveHint=false. Description adds scope (by identifier), persistence differences (authenticated vs anonymous, 24-hour expiry) — valuable 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?

Five sentences, front-loaded with purpose, no redundant words. Efficient and clear.

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

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

Complete for a simple key-value write tool. Explains storage duration and scope despite no output schema.

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

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

Schema has 100% coverage with good descriptions. Description adds context (examples of keys/values) and scoping info, slightly enhancing parameter understanding.

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

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

The description clearly states the verb (save) and resource (data for reuse), and distinguishes from siblings like recall and forget by mentioning them.

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

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

Explicitly says when to use (discover something worth carrying forward), provides examples (ticker, address, preference), and mentions pairing with recall/forget.

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 the tool is read-only, idempotent, and non-destructive. The description adds value by stating that each call cascades through multiple lookup endpoints, replacing 2-3 manual lookups. This provides insight into the internal behavior without contradicting annotations.

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

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

The description is front-loaded with examples and is informative. Every sentence adds value, but it is somewhat long. A slightly more concise version could be written without losing meaning.

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

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

Given the tool has 2 parameters and no output schema, the description thoroughly explains the return values for each entity type, the internal cascading behavior, and the supported input formats. It provides all necessary context for an AI agent to use it correctly.

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

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

Schema coverage is 100%, but the description significantly enhances understanding by explaining what each type returns (e.g., company returns ticker, CIK, name, and URI; drug returns RxCUI, ingredient, brand, and URI) and what inputs are accepted (e.g., ticker, CIK, or name for company). This goes well beyond the schema description.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to a canonical identifier. It provides specific examples like ticker, CIK, RxCUI, and explains that it is used when other tools require IDs. This differentiates it from sibling tools like 'entity_profile' or 'search'.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It also details the supported types and what each returns. However, it does not explicitly mention when not to use this tool or directly compare to alternatives like 'entity_profile' or 'search'.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds behavioral details: it probes each entity with ai_visibility_check, returns a ranked list with score, confidence, signal density. This enriches the agent's understanding beyond the annotations.

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

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

Two sentences, no wasted words. The first sentence states the core action, the second provides use case and output description. Information is front-loaded and efficient.

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

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

Given the tool's complexity (4 parameters, no output schema), the description adequately covers purpose, internal process, output format, and parameter nuances. It is complete enough for an agent to use correctly without further clarification.

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

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

Schema descriptions cover all 4 parameters (100%). The description adds value by explaining that the first entity is treated as 'subject' for narrative, and clarifying usage of context and models parameters. This provides additional 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 uses a specific verb ('compare'), resource ('AI visibility'), and scope ('multiple entities side-by-side'). It clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides explicit use case ('competitive AI-marketing audits') and context ('does Claude know about us as well as our competitors?'). It does not explicitly state when not to use, but the context implies alternatives (e.g., ai_visibility_check for single entity).

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 valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30s, and sources_failed will list timeouts. No contradictions with annotations.

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

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

The description is detailed but dense, with no filler. It could be slightly more concise, but every sentence adds value. Structure is logical: purpose, usage, return info, edge cases. Slightly longer than minimal, but justified by complexity.

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

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

No output schema exists, so the description must explain return values. It does so comprehensively: summary block fields, per-advisory detail, links, alternative versions. It also covers edge cases like partial failures and ecosystem 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 coverage is 100% with clear descriptions for both parameters. The description adds minor context (scoped packages accepted, default to latest version), but the schema already provides adequate meaning. A high baseline of 3 is appropriate, with an extra point for the helpful clarifications.

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

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

Description explicitly states the tool performs a composite check for adding npm packages, covering license, advisories, version history, and bundle size. It clearly distinguishes from siblings by noting fallback to deps.dev for other ecosystems, making the purpose unambiguous.

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

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

Directly specifies use cases: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". It also clarifies ecosystem scope (npm only in v1) and fallback options for other package managers, providing 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 read-only, open-world, idempotent, and non-destructive behavior. The description adds that it returns screencaps, which is consistent but not additional behavioral detail beyond annotations.

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

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

The description is a single short sentence, making it concise. However, it omits usage guidelines and context that could be added without bloat.

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

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

Given the simple tool with good schema and annotations, the description is minimally adequate. It lacks details about available shows, limits, or example usage, which could be helpful.

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

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

Schema coverage is 100%, with each parameter well-described. The description adds no new parameter-specific information beyond what the schema provides.

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

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

The description clearly states the tool finds screencaps matching a quote, which is a specific verb and resource. It distinguishes from siblings like 'deep_research' or 'search_within' by focusing on screencaps.

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

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

No guidance on when to use this tool versus alternatives. Among siblings, there are multiple search tools (e.g., 'deep_research', 'search_within'), but the description offers no explicit 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?

The description adds significant behavioral details beyond the annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation and flag, and that every passage carries an offset for verification. 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 highly concise: two clear sentences plus a third with technical details. All sentences are front-loaded and essential for understanding the tool's purpose, usage, and behavior.

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

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

Given no output schema, the description explains the return format (passages with offsets and similarity scores) and covers limits (200K chars) and edge cases (truncation flagged). It is fully complete for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. The description enhances this by providing default values (limit=5), range (1-20), and usage hints for query (e.g., example queries). This adds meaningful context 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 'Semantic search INSIDE a fetched record' and specifies the return of passages with offsets and similarity scores. It distinguishes itself from sibling tools like 'search' (likely web search) and 'ask_pipeworx_grounded' (which grounds over passages), making the purpose unambiguous and distinct.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and suggests pairing with 'ask_pipeworx_grounded'. It provides clear context for when to use, though it does not explicitly state when not to use it (e.g., for short texts).

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

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

Annotations indicate idempotent, non-read-only, non-destructive. Description adds: returns subscription id, OAuth requirement, webhook signing secret returned once, auto-disable after 10 failures. These go beyond annotations and provide safety-relevant 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?

Single well-structured paragraph, front-loaded with purpose, no redundancies. Every sentence adds necessary detail (prerequisites, type examples, delivery constraints) without excess.

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 complexity (nested params, no output schema, multiple delivery modes), description covers prerequisites, type-specific params, all delivery channels with constraints. Lacks explicit response shape beyond 'new subscription id', but webhook signing secret note partially compensates. Overall thorough.

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%; description adds value by providing type-specific example parameter structures (e.g., sec_8k with ticker and items, polymarket_edge with topic and min_spread_bps) and explaining webhook signing details, which the schema descriptions only hint at.

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 verb 'create' and the resource 'proactive monitoring subscription to a live-data event stream', specifies return type 'new subscription id', and distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 context: requires Pipeworx OAuth account, lists supported types with examples, details delivery channels and constraints (e.g., SMS requires verified phone, 10/day cap; webhook HTTPS only, auto-disabled after 10 failures). Does not explicitly contrast with sibling tools but the use case is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds behavioral context: returns categorized examples, can be filtered by topic, and serves as a learning tool for meta-tools. No contradictions and expands on the safe, read-only behavior.

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

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

The description is a single paragraph that front-loads trigger phrases and purpose. Every sentence adds value: triggers, output explanation, usage instructions, and when to use first. Could be slightly more concise but is efficient and well-structured.

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

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

Given the tool's simplicity (one optional param, no output schema) and the rich annotations, the description fully covers its purpose, usage, output, and role in onboarding. It explains the return format, filtering, and when to use it, leaving no obvious gaps.

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

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

Schema coverage is 100% with one optional 'topic' parameter. The description adds significant meaning beyond the schema by listing the exact topic options (finance, pharma, etc.) and explaining that omitting it gives a full spread. It also describes the output structure (category-bucketed examples with exact tool+argument shapes), which is not in the schema.

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

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

Description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It mentions trigger phrases like 'What can I ask Pipeworx?' and lists use cases. However, it does not explicitly differentiate from siblings like 'discover_tools' or 'ask_pipeworx', though it implies its role as a first-step discovery tool.

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

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

Description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains calling with no arguments for full spread or with 'topic' for focus. No mention of 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?

Beyond annotations (non-destructive, idempotent), description explains row is deactivated not deleted, preserving history. Ownership enforcement also disclosed.

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

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

Extremely concise: two sentences, front-loaded with action, 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?

All needed context provided: action, single parameter source, ownership rule, effect on data (deactivation vs deletion), and reference to sibling tool for historical data.

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 describes 'id' parameter completely (100% coverage). Description adds no new semantic detail about the parameter 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 uses specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing from sibling 'subscribe'. Ownership enforcement adds clarity.

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 ownership enforcement (only your own subscriptions) and implies use for cancellation. No explicit alternatives or when-not-to, but clear enough.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and nondestructive. The description adds rich behavioral detail: the two-path routing (SEC EDGAR vs. grounded pipeline), exact percent-delta math, output components (verdict, value, citation, reasoning), and that it replaces multiple calls. No contradictions with annotations.

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

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

The description is efficient at ~150 words, front-loaded with usage examples and routing logic. Every sentence adds value, but could be slightly more concise by merging redundant phrases.

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 (two processing paths, multiple output fields) and the absence of an output schema, the description covers all essential behaviors: input, routing, output components, and rationale. No critical gaps.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by explaining tolerance_pct overrides, its use for hallucination detection, and the default cap at 5. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources.' It provides concrete example queries and distinguishes between structured SEC EDGAR + XBRL fast path for financial claims and a grounded pipeline for other claims, differentiating it from sibling tools like search or 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?

The description explicitly instructs: 'Use whenever the agent needs to check whether something a user said is factually correct.' It gives clear context but does not explicitly exclude non-factual claims or mention alternatives, though the routing logic implies boundaries.

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