Usgs Volcano

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds billing context (free vs. BYO key), explains that the key is passed through, and outlines the return structure (score, confidence, signals, raw_response). This adds useful 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 concise—three sentences covering purpose, configuration, and use cases. No redundant information. The first sentence front-loads the main action and output. Every sentence serves a clear 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 listing the per-model response fields. It explains the two model options and the optional context. However, it does not detail how scores are calculated, what 'signals' contain, or error handling. With 4 parameters and 1 required, it's mostly complete but misses minor behavioral 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 description coverage is 100%, so all parameters are described. The description adds extra context: default model if 'models' is omitted, the purpose of 'context' for disambiguation (with examples like 'Boston restaurant'), and clarifies that '_apiKey' is only needed for Anthropic models. This adds 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?

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the verb 'probe', the resource 'LLMs', the output format, and default model. This distinguishes it from sibling tools 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 explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to use a free default vs. paid Anthropic model. However, it does not explicitly state when not to use the tool or compare it to sibling 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 cover readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it routes to multiple tools, returns structured answer 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?

Description is front-loaded with purpose and usage, but somewhat lengthy. Every sentence adds value, though could be slightly trimmed without loss.

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 explains return format (structured answer with citations). Covers all relevant aspects for a complex multi-source tool. Complete for its purpose.

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

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

Schema coverage is 100% with well-described aliases. Description does not add significant meaning beyond schema, which is already clear. Baseline 3.

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

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

The description explicitly states the tool answers factual questions using authoritative structured data with citations, and distinguishes it from siblings like ask_pipeworx_grounded and deep_research. Clear verb+resource+scope.

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

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

Explicitly recommends preferring over web search, provides concrete when-to-use and when-not-to-use guidance with examples and alternative tools. Covers both positive and negative use cases.

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

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

Annotations already provide read-only, idempotent, non-destructive hints. Description adds valuable behavioral details: costs one extra LLM call, returns structured response with evidence and refusal reasons, and lists possible refusal values. No contradictions.

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

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

Description is lengthy but every sentence adds value: behavior, use case, trade-offs, return format, refusal reasons. Front-loaded with key concept. Slightly verbose but not wasteful.

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

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

Without an output schema, the description thoroughly explains the return format, including success and refusal cases. Covers behavior, error states, and cost trade-off. Complete for a complex tool.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. Description does not add new semantic meaning beyond what the schema provides (which is already clear). Baseline 3 applies.

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

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

Clearly states the tool is a hallucination-resistant answer mode for high-stakes reads. Differentiates from sibling 'ask_pipeworx' by specifying it extracts answers solely from tool results and returns explicit refusals. Provides specific use cases (financial, legal, medical).

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also advises preferring 'ask_pipeworx' for casual lookups, giving clear guidance on tool selection.

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

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

The description extensively details behavioral traits beyond annotations. It explains the resolution process, classifier categories, fan-out examples per bet type, response shapes (market, analysis, evidence), resolver contract (confidence, alternatives, suggestions), parent event extraction, news fields with fallback handling, safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread warnings), and resolution-rule risk (cancellation rules). Annotations already indicate read-only, idempotent, non-destructive; the description adds rich context without contradiction.

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

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

The description is lengthy but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with the core purpose. Every sentence adds value, explaining specific behaviors and edge cases. While not concise, its comprehensiveness is warranted given the tool's complexity. A slightly shorter version might improve conciseness, but current structure is clear and informative.

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

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

Given the tool's complexity (3 parameters, no output schema, rich behavior), the description is remarkably complete. It covers input methods, resolution process, classifiers, fan-out examples, response fields (market, analysis, evidence, parent event, news), safety mechanisms (low-confidence, closed markets, wide spreads), and resolution-rule risk. Missing elements are minimal; examples in the schema complement the description. It fully prepares an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema's parameter descriptions; it focuses on overall behavior. The schema already describes 'market' as 'Polymarket slug, full URL, or question text', 'depth' as 'quick = 2-3 evidence sources, thorough = full fan-out', and 'include_raw' with default and effect. The description reinforces the fan-out concept but does not add novel parameter 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 the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input methods (slug, URL, question text) and explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It differentiates from siblings by focusing on single-call comprehensive research for Polymarket bets, while sibling tools cover arbitrage, edges, or broader 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 provides explicit when-to-use guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when the tool may not apply, such as low-confidence matches ('short-circuits with status:"low_confidence_match" and suppress analysis fields') and closed markets ('return status:"market_closed_or_inactive" and skip fan-out'). This helps agents decide when the tool is appropriate and when to avoid it.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds rich behavioral context: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), fiscal year handling, sorting by primary metric, and output including 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 well-structured with clear sections for company and drug types, and front-loaded with example queries. Although it is somewhat lengthy, every sentence adds valuable information.

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

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

Given that there is no output schema, the description covers key aspects: data sources, input formats, sorting, and output includes paired data and citation URIs. It lacks explicit output structure details but is reasonably complete for a comparison tool.

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

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

The input schema already provides basic descriptions, but the description adds significant meaning by clarifying entity type semantics (tickers/CIKs for company, drug names) with concrete examples, and explains what data each type retrieves.

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 in a single parallel call. It provides specific examples of queries and explicitly distinguishes from sequential single-pack lookups, making it highly clear.

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

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

The description explicitly advises preferring this tool over sequential lookups when comparing entities, which is clear usage guidance. However, it does not explicitly mention when not to use it or directly name alternative tools like entity_profile, though the context is strong.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical context: account tier dependency (free vs paid for 'thorough'), parallel execution across 4,774 tools, returns findings packet with verbatim evidence and gaps, not open-web search, expected time 15-60s. No contradiction with annotations; the description clarifies the openWorldHint by limiting to structured catalog.

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 adds value. It front-loads the critical account requirement and alternative, then explains the tool's mechanism, output, usage context, and limitations. Structured logically: prerequisites → what it does → how it works → best for → when not to use → performance. No wasted words.

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

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

Despite no output schema, the description details the return format ('findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'). It covers prerequisites, alternatives, scope, behavior, limitations, and expected time. References sibling tools appropriately. Nothing essential is missing.

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

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

Schema coverage is 100%. Description adds meaning: for 'depth', it explains the enumerations ('quick=3, standard=5, thorough=8') and ties 'thorough' to paid plans. For 'question', it says 'Broad/multi-part is fine — decomposition is the point', which clarifies acceptable input beyond the schema's natural language requirement.

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: 'Grounded multi-source research across Pipeworx's 1242 STRUCTURED data sources'. It uses specific verbs ('decomposes', 'routes', 'returns'), specifies the resource (structured data sources), and distinguishes from siblings like ask_pipeworx (single lookup) and for current-news. The title 'Deep Research' is aligned.

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

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

Explicit guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also mentions account requirements: 'ACCOUNT REQUIRED (free — sign in via GitHub...)' and provides an alternative (ask_pipeworx) for unsigned users. No ambiguity.

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

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

Description adds valuable behavioral context beyond annotations: 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 (readOnlyHint, idempotentHint, destructiveHint are all consistent).

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

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

Front-loaded with purpose, then lists concrete data domains and return behavior. Efficient but slightly lengthy; 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?

No output schema, but description fully explains return structure (names, descriptions, schemas, curated examples) and behavior (top-N, ready-to-call). Covers 6 parameters, aliases, examples, and use case.

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

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

Schema coverage is 100% so baseline is 3. Description adds that 'accepts task, q, description, search as aliases' for the query parameter, providing useful alias information not in 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 by describing the data or task'—a specific verb ('find') and resource ('tools'). Clearly distinguishes from sibling tools which are specific data tools; this is a meta-tool for discovery.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for when to use, though does not list explicit alternatives or when not to use.

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

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

Annotations already declare readOnly, openWorld, idempotent, not destructive. Description adds valuable context: fans out across multiple sources, returns specific fields, notes patents sunset (soft-fail), fallback mechanism for news, and that it makes a parallel call. No contradictions.

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

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

The description is detailed but well-structured: starts with example queries, defines core purpose, lists data sources and what is returned, then addresses parameter constraints. Every sentence serves a purpose with 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?

Given the complexity (multiple data sources, fallbacks, a deprecation note) and no output schema, the description is remarkably complete. It explains what each component returns (filings with URIs, fundamentals sorted, patents, news, LEI) and notes the soft-fail for patents.

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

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

Schema coverage is 100% with clear descriptions. Description adds value by explaining that type is currently only 'company', that value can be ticker or zero-padded CIK, and explicitly that names are not supported. Provides examples like 'AAPL' and '0000320193'.

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 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and return fields. It distinguishes from siblings by explicitly preferring over chaining single-pack lookups and referencing resolve_entity for names.

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: when user asks for a holistic view (e.g., 'tell me about X', 'brief me on Tesla'). Also states when not to use: names not supported; use resolve_entity first. Mentions alternatives like chaining single-pack lookups and notes limitations like patents soft-fail.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, which the description reinforces by stating 'delete'. The description adds minimal behavioral context beyond confirming deletion, but does not contradict annotations.

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

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

Two sentences with no wasted words. Information about usage and related tools is front-loaded. 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 simple tool with one required param and no output schema, the description covers purpose, usage context, and sibling relationships. No gaps for the complexity level.

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%, and the param 'key' is described as 'Memory key to delete' in schema. Description simply says 'by key', adding no new meaning. Baseline score of 3 applies.

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

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

Description explicitly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes itself from siblings 'remember' and 'recall' by focusing on deletion.

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

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

Description clearly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with 'remember' and 'recall', though it does not explicitly state when not to use it.

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

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

Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds concrete behavioral details: fetches page, extracts title/description/key links, and outputs standard markdown format. This supplements the annotations without contradiction.

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

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

The description is three sentences, starting with the core purpose and output, then the process, then use cases. Every sentence adds value with no redundancy or fluff.

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

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

Given the tool's low complexity (2 simple params, no output schema), the description adequately covers purpose, process, output format, and use cases. It could mention error scenarios or output size limits, but is otherwise 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%, so the schema already documents both parameters. The description adds minimal extra value: an example URL and reiteration of default/max for max_links. This meets the baseline but does not significantly enhance 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 generates a production-ready llms.txt file for any URL, specifying the verb ('generate'), resource ('llms.txt file'), and target audience (AI crawlers). It distinguishes from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on creating a file rather than just checking visibility.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, and auditing competitor perception. While it doesn't state when not to use the tool, the use cases provide clear context for when it is appropriate.

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, destructiveHint, idempotentHint, and openWorldHint. The description adds context about the filtered scope ('above Normal/Green status') but no additional behavioral traits beyond what annotations provide.

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

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

Two sentences with no waste. The purpose is front-loaded and every word earns its place.

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

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

Given zero parameters and an output schema, the description is sufficient: it explains what the tool does (lists elevated volcanoes) and its intent (quick fingerprint). It could briefly mention output format but not required.

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?

No parameters exist, so schema coverage is 100%. The description is not required to add parameter details; baseline 4 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 it lists volcanoes above Normal/Green status, using a specific verb and resource. It distinguishes itself from the sibling 'list_volcanoes' tool by filtering to elevated unrest or eruption.

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

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

The description implies when to use it (when only elevated status volcanoes are needed) and contrasts with 'list_volcanoes' implicitly. It lacks explicit 'when not to use' or alternative naming but is 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 already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the context of filtering and 'recent' but does not contradict annotations. It provides adequate transparency beyond the schema.

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

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

The description is two concise sentences that efficiently communicate the tool's purpose and key feature. No unnecessary words; front-loaded with essential information.

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

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

For a low-complexity tool with 2 optional parameters and an output schema, the description covers the purpose and filtering capability. It could mention the default limit (50) but that is in the schema. Overall, it is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description mentions 'filter by volcano slug' but adds no new meaning beyond what the schema says. 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 that the tool lists recent USGS volcano notices and reports, specifying types (observatory updates, VAN, VONA) and the ability to filter by volcano slug. This distinguishes it from sibling tools like list_volcanoes or recent_alerts.

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

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

The description implies usage for retrieving recent volcano notices but does not explicitly state when not to use it or suggest alternatives. Given the context of sibling tools, more guidance could be provided, but it's adequate for basic understanding.

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 value by listing return fields and clarifying default behavior (active subscriptions only). 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, no unnecessary words. Efficiently conveys purpose, return fields, and usage guidance.

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

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

Returns fields are explicitly listed, usage guidance given, and schema covers the single parameter. No output schema needed given simple data structure.

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

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

Schema coverage is 100% with parameter description. Description reinforces the default behavior ('active') but does not add new semantic meaning beyond schema.

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

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

Description clearly states verb 'List' and resource 'the caller's active subscriptions'. Distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly advises using the tool to review subscriptions before adding more or to find an id to cancel, providing clear context. Lacks explicit when-not alternatives but is still effective.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds that it retrieves data from USGS, specifies the returned fields (alert level, aviation color code), and mentions the source, which is useful context beyond annotations.

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

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

The description is a single, well-structured sentence that conveys all essential information without redundancy. It is front-loaded with the main action and resource, followed by key attributes and filtering option.

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 an output schema (not shown but indicated), the description adequately describes what the tool returns (volcanoes with alert levels and color codes) and the optional filter. For a list tool, this is sufficient for an agent to understand the tool's purpose and output.

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

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

The single optional parameter 'observatory' is fully described in the input schema with its meaning and valid values. The description simply restates 'Filter optionally by observatory', providing no additional semantics beyond what the schema already offers.

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

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

The description explicitly states it lists US volcanoes monitored by USGS with alert level and aviation color code, and can filter by observatory. The verb 'list' and resource 'volcanoes' are specific, and it distinguishes from sibling tools, which are unrelated.

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

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

The description clearly states when to use: to get a list of US volcanoes with current alert levels and color codes, with optional observatory filtering. While it doesn't explicitly mention alternatives, the sibling tools are not similar, so the context is sufficient.

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

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

The description discloses rate limiting (5 per identifier per day), free usage, and that feedback doesn't count against quota. These traits are not in annotations, so the description adds significant 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?

The description is well-structured: purpose first, then usage guidelines, then behavioral notes. Every sentence adds value, though slightly longer than minimal. 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?

Given the tool's simplicity and lack of output schema, the description fully covers what the agent needs: what to provide, how it's used, and expected impact (roadmap influence).

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by instructing how to write the message (e.g., 'Don't paste the end-user's prompt', 'Be specific'), 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?

The description starts with a clear verb ('Tell') and resource ('the Pipeworx team'), and specifies the purpose: report bugs, missing features, or praise. It distinguishes from sibling tools by its unique feedback function.

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

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

The description provides explicit guidance on when to use each feedback type (bug, feature, data_gap, praise) and instructs the agent to describe issues in terms of tools/packs, avoiding end-user prompts. It also notes rate limits and free usage.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), description reveals source (CF analytics-engine), no PII, cached 5min-1h, and that it's a 'self-aggregating signal'. This fully informs the agent of 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?

Description is compact and well-structured with a mix of summary and enumerated use cases. Could be slightly shorter, but every sentence adds value.

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

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

Given no output schema, the description adequately describes return structure (top tools, packs, volume). Covers input, behavior, and use cases fully for a simple read tool.

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

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

Schema coverage for the single parameter is 100% and schema description already explains the enum values. The main description restates the window options but adds no new semantic information beyond the schema.

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

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

Clear verb ('Returns') and specific resource ('top tools, top packs, total call volume') over defined time windows. Distinguishes from siblings like discover_tools and ask_pipeworx by focusing on trending/call volume.

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?

Lists three explicit use cases and explains the value of shorter vs. longer windows. Does not specify when to avoid this tool, but the use cases are clear enough for appropriate 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 extensively details behavioral traits beyond annotations: methodology (monotonicity violations, partition checks), semantic anchor (Jaccard similarity threshold), partition filter (placeholder rejection), fill check against live order book, and edge cases (thin legs, fake edges). This adds significant context beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is well-structured and front-loaded with the core purpose. While it is lengthy (multiple dense paragraphs), every sentence adds necessary technical detail. Minor redundancy could be trimmed, but overall it is organized and informative.

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

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

Given no output schema, the description fully explains the response structure (opportunities array, partition_check fields, fill_check outputs) and covers edge cases (placeholders, similarity filters, fill conditions). It is comprehensive for a complex tool with zero required parameters.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning by explaining that event accepts slugs or full URLs, and topic takes a seed question. It enriches the schema with behavioral details (e.g., event mode walks child markets, topic mode searches related events), providing substantial added value.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between two explicit modes (event and topic), each with specific use cases, and differentiates from sibling tools like polymarket_fill_risk.

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

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

The description explains when to use each mode (event for specific market, topic for cross-event scanning) and provides guidance on not trading when realizable_edge_pp <= 0. It mentions polymarket_fill_risk for custom sizing. However, it does not explicitly compare against other sibling tools like polymarket_edges.

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, and idempotentHint. The description adds significant behavioral context: caching (1h), model families, response segments, per-opportunity fields, tradeable-edge knobs, Fed bet exclusion, and diagnostics. 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 verbose and dense with technical details. While front-loaded with a clear purpose, the length (several paragraphs) could be more concise. It is structured with paragraphs and bolded terms, but bullet points would improve readability.

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

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

With no output schema, the description explains the response top-level structure (by_segment, fed_candidates, fed_note, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, etc.). It also covers caching and knobs. However, the exact JSON format is not specified, which would be helpful for programmatic parsing.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining the rationale behind several parameters (e.g., min_liquidity and max_spread_pp as 'tradeable-edge filters', min_partition_leg_kelly for filtering thin partitions), going beyond the schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It is a specific verb+resource combination that distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description provides clear context for when to use the tool ('what should I bet on today') and mentions it avoids paging hundreds of markets. However, it does not explicitly state when not to use or name alternatives, though the context is strong enough for an agent to infer appropriate usage.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds depth: data source (daily snapshots), output structure (tracked, expired, snapshot_dates), computation details (trend and decay from |edge_pp_net|), and limitations (history depth bounded by TTL, gaps from cache-misses). No contradiction.

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

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

Description is long but front-loaded with core purpose. Each section (output arrays, limits) earns its place. Slightly dense but not unmanageable; structure is logical despite 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 thoroughly explains three output arrays, their fields, and data meaning. Covers inputs, behavior, and limitations well. Lacks exact data types, but otherwise complete for telemetry tool.

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

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

Schema covers both params with descriptions. Description adds default values (days=14, window='1wk'), range (days clamp 2-30), and explains window meaning ('snapshot family') and snapshot gaps. Adds significant value beyond schema.

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

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

The description states a specific verb-resource combination: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?'. It clearly distinguishes from sibling like polymarket_edges by focusing on persistence and decay rather than raw edge 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?

Provides explicit context on when to use: to assess if an edge is old and decaying ('a fresh wide edge and a 3-week-old wide edge are different trades'). Includes limitations (60-day TTL, not intraday) but does not directly compare to alternatives or state when not to use.

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

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

Annotations already indicate a safe, read-only, idempotent check. The description goes beyond by detailing returned fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, forced_directional_risk) and warnings about thin books and partial fills. No contradiction with annotations.

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

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

The description is lengthy but well-structured: a one-line summary, then REQUIRES, then separate sections for single-market and basket modes with clear bullet points. It front-loads the key purpose and usage. Could be slightly trimmed but remains 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?

No output schema exists, so the description must fully explain return values, which it does for both modes. It also covers edge cases (thin legs, forced directional risk) and provides enough detail for an agent to understand the tool's behavior and outputs.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two mutually exclusive modes (market vs event), default side behavior for basket mode, and size_usd interpretation differences between modes. This clarifies parameter usage 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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It is specific about the resource (Polymarket order books) and differentiates from sibling tools like polymarket_arbitrage and 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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why with concrete risks: theoretical overround not capturable on thin books and partial basket fills leading to unhedged directional positions.

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. The description adds extensive behavioral context: it details two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), and explains why mismatched bet shapes or temporal gaps make spreads meaningless. This goes far 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 long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and a concise warning. Every sentence adds unique value, though some details (e.g., lengthy explanation of counters) could be slightly tightened without losing clarity. Still, it earns a high score.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is complete. It explains the output structure, safety fields, and interpretation caveats (e.g., temporal alignment, non-equivalent bet shapes). Without an output schema, the description carries the full burden of explaining what the agent will receive, and it does so thoroughly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The tool description adds further meaning by listing the 10 topic values, explaining that explicit parameters override topic-mapped sides, and clarifying the parameter purpose. This enhances understanding beyond the schema alone.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts vs explicit event identifiers) and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, which focus on single venues.

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

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

The description explains when to use topic mode vs explicit parameters, and explicitly warns that most pre-mapped topics return compatibility_warning, so users should not assume tradeability. Safety fields like compatibility_warning and temporal_alignment guide correct interpretation, and the warning 'pre-mapped ≠ tradeable' sets expectations.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds scoping to user identifier and pairing info, enhancing transparency 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?

Two sentences, front-loaded with purpose, no redundant information. Every sentence provides 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?

With one optional parameter, no output schema, and annotations covering safety, the description fully explains purpose, usage, and scoping, leaving 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?

Parameter schema covers 'key' with 100% description; description adds contextual examples and behavior when omitted, adding value beyond schema.

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

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

Description clearly states the tool retrieves values saved via 'remember' or lists all keys when omitted, distinguishing it from siblings like 'remember' and 'forget'.

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

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

Explicitly describes when to use (look up stored context) and pairs with remember/forget, but does not explicitly exclude use cases or mention alternatives.

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

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

Annotations already indicate readOnly and idempotent hints. The description adds detailed behavior such as the mark_read side effect (flagging events read) and that polling is acceptable. There is no contradiction with 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 compact (5 sentences), front-loaded with purpose, and each sentence adds unique value (return fields, filtering, mark_read, polling, alternative access). 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?

Given no output schema, the description covers key return fields and usage patterns. It could detail pagination or the effect of limit, but overall it is sufficiently complete for an agent to decide and invoke the tool.

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

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

Schema coverage is 100% with all 5 parameters described. The description adds usage context for type, since, and mark_read but does not explain limit or unread_only beyond what schema provides. Baseline 3 applies.

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

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

The description clearly states the tool pulls fired events from a subscription feed, with a specific verb ('Pull','Returns') and resource ('fired events from your subscription feed'). It distinguishes from sibling tools like list_subscriptions and subscribe, which manage subscriptions rather than retrieve alerts.

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 guidance on filtering by type and since, using mark_read for read tracking, and notes that polling works fine. It also mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral detail beyond annotations: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, relative date handling, and return structure including pipeworx:// citations. 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 moderately long (multi-sentence paragraph) but every sentence serves a purpose: example queries, source behavior, parameter details, and sibling differentiation. It is front-loaded with user-facing examples that help the agent recognize appropriate use cases. Minor redundancy could be trimmed.

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

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

Given the tool's complexity (multiple data sources, fallback logic, parameter formats, and no output schema), the description is remarkably complete. It covers return structure, source behavior, parameter grammar, and a key alternative (entity_profile). It fully compensates for the lack of an output schema.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning beyond the schema: it explains that 'since' accepts both ISO and relative shortcuts, recommends '30d' for typical monitoring, and clarifies that 'value' can be a ticker or CIK. This enriches the schema significantly.

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 concrete example queries ('What's new with X', 'latest on Y') that immediately clarify the tool's purpose. It clearly states 'change feed for a company in the last N days/weeks/months' and distinguishes from sibling entity_profile by specifying that recent_changes returns dynamic changes while entity_profile returns static profile.

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

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

The description provides explicit when-to-use guidance with example phrases and explicitly names the alternative entity_profile. However, it does not address when not to use this tool relative to other siblings like search_within or scan_competitor_ai_presence, limiting its exclusion 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?

Description adds valuable context beyond annotations: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. 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?

Four concise sentences, front-loaded with primary action, no redundant or unnecessary text.

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

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

Given no output schema, description fully covers purpose, usage, behavior, and parameter context for a simple storage tool.

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

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

Schema already covers both parameters with descriptions. The tool description reinforces the key-value concept and provides usage examples, adding moderate value.

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 saves data for reuse across conversations and sessions. It specifies the verb 'Save' and the resource 'data', and the examples distinguish it from siblings like forget and recall.

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

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

Explicitly tells when to use (discover something worth carrying forward) and why (to avoid looking it up again). Mentions pairing with recall and forget for completeness.

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, and destructiveHint. The description adds value by explaining internal cascading behavior ('cascades through several lookup endpoints') and detailing return values per type (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand for drug). 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 moderately sized but well-structured: starts with example queries, then states purpose, then details types. Every sentence adds value, though 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 adequately explains return values and behavior for both entity types. Internal cascading behavior and parameter coverage make it complete for an AI agent.

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

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

Schema coverage is 100% and already has decent descriptions. The description adds further meaning by providing examples, explaining auto-disambiguation, and specifying what each type accepts and returns.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, with specific examples and explicit mention that it should be used first when needing an ID. It distinguishes from sibling tools by focusing on name-to-ID resolution.

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

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

The description provides clear usage context: 'Use FIRST whenever you have a name but need an ID.' It gives example queries and notes it replaces multiple lookups, but does not explicitly exclude cases like when an ID is already known.

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 reveals internal behavior (probes each entity with ai_visibility_check, ranks by score) and return format (ranked list with score, confidence, signal density). It also mentions the required API key condition. This adds significant context beyond the annotations (readOnlyHint, idempotentHint, etc.).

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, well-structured, front-loaded with the main action. Every sentence contributes essential information without redundancy.

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

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

Despite lacking an output schema, the description explains the returned data (score, confidence, signal density) and covers all parameters. It references the sibling tool ai_visibility_check for further detail, making it complete for a multi-entity comparison tool.

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

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

The schema description coverage is 100%, and the description adds extra meaning: first entity treated as 'subject' for narrative, context applied to every probe, and the condition for _apiKey. 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 it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces the most/least recognized. It uses a specific verb ('compare') and resource ('AI visibility across entities'), and distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description provides concrete use cases ('competitive AI-marketing audits') and an example question. It implies when to use this tool (multi-entity comparison) versus the single-entity ai_visibility_check, though it does not explicitly state when not to use it.

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

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

Beyond annotations (readOnly, idempotent, destructive=false), the description details multi-service fan-out, return format, and potential delays (5-30s first measurement) with graceful degradation. 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?

Front-loaded with purpose, then covers data sources, usage, return, and limitations. Each sentence adds value, though slightly verbose for a composite scan tool.

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

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

With no output schema, the description fully explains return structure (summary fields, advisories, links, alternatives) and handles edge cases (timeouts, ecosystem bounds). Complete for a 2-param tool.

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

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

Schema coverage is 100% and already documents package name and optional version. The description only redundantly repeats that scoped packages are accepted and default is latest, adding no new semantic value.

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 a composite check for npm packages covering safety, popularity, and size. It distinguishes from sibling tools (e.g., scan_competitor_ai_presence) by focusing on dependency evaluation.

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 dictates when to use: 'Use whenever an agent asks "is X safe / popular / small"'. Provides a concrete example ('what does adding lodash cost me') and excludes non-npm ecosystems with alternative 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 indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: embedding model (BGE-base-en), chunking method (500-char overlapping windows with cosine similarity), character cap (200K chars with truncation and flagging), and output format (passages with offsets and scores). 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?

Every sentence is informative and earns its place. The description is front-loaded with the core purpose, then provides guidelines, behavioral details, and pairing advice. It is concise yet comprehensive, with no filler.

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

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

Given the tool's complexity (semantic search, chunking, length limits, pairing with sibling) and absence of an output schema, the description fully covers return values (passages with character offsets and similarity scores) and all relevant behavioral details. It is complete for an agent to use effectively.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats schema info for 'text' (max 200K chars) and 'query' (natural-language with examples) but does not add new parameter semantics. Since schema already fully describes parameters, the description offers no additional value.

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: 'Semantic search INSIDE a fetched record.' It provides concrete examples of use cases (SEC 10-K, article, long tool result) and distinguishes itself from sibling tools like ask_pipeworx_grounded, ensuring the agent understands its specific role.

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

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

Explicitly tells when to use the tool: 'when the record is too big to cram into the prompt.' It explains the benefit (saves context, returns relevant passages) and pairs with ask_pipeworx_grounded for grounded reasoning. This provides clear context and alternatives.

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

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

Annotations indicate it's a mutation (readOnlyHint=false) and idempotent, which aligns with creation. The description adds rich behavior: subscription persistence requires OAuth, delivery channels always include the feed, email/sms/webhook have specific constraints, webhook includes HMAC signing and auto-disable after 10 failures. No contradictions with annotations.

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

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

The description is well-structured: starts with core purpose, then requirements, then type examples, then delivery. Every sentence adds value. Slightly verbose in the webhook and delivery details, but still efficient for the complexity.

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

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

Given the tool's complexity (multiple subscription types, nested params, optional delivery options), the description covers all aspects: return value, account requirement, type-specific params, delivery channels with constraints, and post-subscription behavior (webhook signing). No output schema exists, but the description appropriately mentions the return of subscription id and webhook secret.

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 enriches each parameter with concrete examples (e.g., sec_8k params show items codes, polymarket_edge shows topic and min_spread_bps). It also explains delivery channels in detail, including webhook secret and verification process, far beyond the schema's short 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 action 'Create a proactive monitoring subscription', identifies the resource as 'live-data event stream', and mentions it returns the subscription id. It differentiates from sibling tools like list_subscriptions and unsubscribe by being the creation 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?

Provides necessary prerequisites (requires Pipeworx OAuth account), details delivery channel constraints (phone verification, 10/day SMS cap), and notes that anonymous/BYO users cannot persist subscriptions. However, it doesn't explicitly contrast with alternatives like ask_pipeworx or recent_alerts.

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 hints. The description adds value by explaining the output format (category-bucketed examples with exact tool+argument shapes) and the source (live catalog of thousands of tools). No contradiction exists.

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 common user queries and clearly structures its purpose, output, and usage. While slightly verbose, every sentence adds value. It could be trimmed slightly but remains effective.

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

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

Despite lacking an output schema, the description fully explains what is returned (examples with tool+argument shapes), the source, and the parameter behavior. For a simple, well-annotated tool, this is complete and leaves no ambiguity.

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 parameter (topic). The description adds meaning by listing specific focus area options (finance, pharma, etc.) and explaining the behavior when omitted ('cross-category spread'). This goes beyond the schema's generic 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 explicitly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It lists specific categories and distinguishes itself by recommending use 'FIRST' when the agent does not know what Pipeworx can do, differentiating it from siblings like ask_pipeworx or discover_tools.

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

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

The description clearly says to call with no arguments for full spread or pass a topic to focus. It also advises 'Use this FIRST when you do not yet know what Pipeworx can do for you,' providing clear context. It does not explicitly state when not to use it, but the guidance is sufficient.

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

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

Discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts, adding context beyond annotations that indicate non-destructive but not 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?

Two sentences, front-loaded with the core action, no fluff. Every sentence provides essential information.

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

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

Given the simple tool (1 param, no output schema, annotations cover safety), the description fully covers usage constraints and behavioral effects.

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

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

Schema coverage is 100% with a clear description for the only parameter. The description adds no new semantic information beyond reinforcing 'by id'.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use and when not to. Also explains consequences for historical data.

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

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

The description adds significant behavioral context beyond annotations: it specifies the supported domain (company-financial claims), the data source (SEC EDGAR + XBRL), and the exact return format (verdict values, structured form, actual value with citation, percent delta). No contradiction with annotations.

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

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

The description is a single paragraph that front-loads usage triggers and purpose. Every sentence adds value, though it is slightly longer than strictly necessary. It is 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 (1 param, no output schema, rich annotations), the description covers purpose, usage, scope, and output details completely. It could mention rate limits or authentication, but that is not essential for this tool.

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

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

Schema coverage is 100% for the single parameter 'claim'. The description adds natural-language guidance and examples of what kinds of claims are suitable, which 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 specific trigger phrases like 'fact check' and 'verify the claim that…', and distinguishes it from siblings by noting it replaces 4–6 sequential calls.

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

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

The description explicitly tells when to use it: 'whenever the agent needs to check whether something a user said is factually correct.' It provides examples of user intents. There is no explicit when-not, but the context is clear enough.

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