Usgs Volcano

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

Annotations already show readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds crucial behavioral context: it probes multiple models, requires BYO key for Anthropic (cost implication), and returns per-model scores with signals and raw responses. This goes beyond what annotations convey.

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

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

The description is three sentences, each earning its place: first sentence states the core action and default, second explains API key usage, third describes return format. It is front-loaded with the primary purpose and immediately useful for tool selection.

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 the return structure (per-model score, confidence, signals, raw_response + combined view). All 4 parameters are covered, with clear roles. The tool's complexity is moderate, and the description covers all necessary context for an AI agent to decide and invoke correctly.

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

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

Schema coverage is 100% with descriptive parameter names and descriptions. The description adds value by explaining the entity as a brand/business/product/person, noting that models array is optional, clarifying the purpose of _apiKey (passed through to Anthropic), and that context helps disambiguate common names. No redundancy.

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

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

The description clearly states it probes one or more LLMs for knowledge about a business/product/topic and scores visibility (0-100) per model. This verb+resource combo is distinct from siblings like ask_pipeworx or entity_profile, which focus on single model queries or entity 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 explicitly mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also clarifies when to provide an API key for Anthropic and that the default model is free, but does not explicitly state when not to use or alternatives among siblings.

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

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

No annotations exist, so description carries full burden. It discloses that the tool routes across 300+ sources and returns the result, but lacks details on failure modes, latency, or ambiguity handling. Adequate but could improve.

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?

Succinct and well-structured: opens with purpose, follows with usage guidelines, lists data sources, and closes with examples. Every sentence is informative without excess.

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

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

For a single-parameter tool with no output schema, the description covers purpose, usage, scope, and examples completely, leaving no significant gaps for an AI agent to resolve.

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 single 'question' parameter. Description adds value by providing example questions and explaining the breadth of query types, going beyond the schema's basic description.

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

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

The description clearly states it answers natural-language questions by automatically selecting the appropriate data source, providing specific verbs and examples ('What is X?', 'Look up Y'). It distinguishes itself from sibling tools that likely require manual tool selection.

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 you don't want to figure out which Pipeworx pack/tool to call') and provides concrete example questions, giving clear guidance on 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?

Description fully discloses behavior: it resolves the market, classifies the bet, fans out to appropriate data packs, and returns an evidence packet plus a market-vs-model comparison. Annotations already indicate readOnlyHint and destructiveHint false, but the description adds essential details about the internal logic and output structure.

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

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

Description is detailed but not overly verbose. Every sentence provides meaningful information. It is front-loaded with the primary action. Minor redundancy could be trimmed, but overall it is well-structured and 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 and lack of output schema, the description covers all necessary aspects: input types, default behavior, internal processing (classification, fan-out), and output structure. It ensures the agent has complete context to use the tool correctly.

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

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

Schema coverage is 100% with both parameters described. Description enhances by explaining acceptable input formats for 'market' (slug, URL, question text) and the default for 'depth' (thorough). It also clarifies the output, which is not in the schema. This adds value beyond the basic 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?

Description clearly states the tool's main action: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resources (Pipeworx data) and the verbs (research, pulling). It distinguishes itself from siblings by explaining that it combines multiple data packs into one call, which no other sibling tool does.

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

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

Description explicitly lists use cases: 'Use for "should I bet on X?", "what does the data say about this Polymarket market?", or "is there edge in this bet?"' and contrasts with alternatives by stating 'agents that get bet-relevant context here convert better than ones that have to discover the packs themselves,' guiding the agent when to choose this tool over others.

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

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

No annotations provided, so the description carries full burden. It discloses data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinicaltrials for drugs) and return format (paired data + citation URIs). Does not mention potential side effects like rate limits, but overall adequate.

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

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

Single paragraph, front-loaded with main purpose. Contains detailed information without excessive verbosity. Could be more structured with bullet points, but still 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, so description must explain return values. It mentions 'paired data + citation URIs', which is sufficient though somewhat vague. Covers essential aspects for a complex comparison tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context: explains enum values for type, gives examples for values, and clarifies input format beyond schema definitions.

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

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

The description clearly states the tool compares 2-5 companies or drugs side by side. It uses specific verbs like 'compare' and identifies resources (companies/drugs). It distinguishes from sibling tools like entity_profile, which likely handles single entities.

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

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

Provides explicit usage cues: 'Use when a user says "compare X and Y"' etc. Explains the two types. Lacks explicit when-not-to-use, but context with siblings implies 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?

With no annotations provided, the description carries the full burden. It discloses that the tool returns 'top-N most relevant tools with names + descriptions,' which is accurate and sufficient. It does not mention any destructive behavior or side effects, which is consistent with a read-only discovery operation. The description is transparent about its function and limitations.

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

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

The description is a single coherent paragraph that front-loads the purpose ('Find tools...'). It includes a list of example domains and a usage instruction. While it is somewhat lengthy due to the examples, each sentence serves a purpose and contributes to clarity. Minor redundancy could be trimmed, but overall 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 and the absence of an output schema, the description adequately explains what the tool does and what it returns (names and descriptions of tools). It does not detail the format of the output or mention edge cases like no results, but the examples and usage instruction provide sufficient context for an agent to use it correctly. The definition is complete for a discovery tool.

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

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

Schema coverage is 100%, with descriptions for both 'query' and 'limit'. The description adds value beyond the schema by explaining that 'limit' controls the number of tools returned (top-N) and providing example queries. This helps the agent understand how to use the parameters effectively.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides a comprehensive list of example domains (SEC filings, financials, etc.) and explicitly distinguishes itself from sibling tools by instructing the agent to call this first to discover available options, rather than directly performing a specific action.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance. While it does not explicitly list when not to use it, the context implies that if the agent already knows the specific tool, this discovery step is unnecessary.

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

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

Despite no annotations, the description clearly states what the tool returns (SEC filings, financials, patents, news, LEI) and mentions pipeworx:// citation URIs. However, it omits any mention of being read-only or potential side effects. Still strong for a read-oriented tool with no annotation support.

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?

A single dense paragraph that front-loads the purpose, then covers use cases, return contents, and parameter details in logical order. Every sentence earns its place; nothing redundant.

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

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

For a tool with no output schema but moderate complexity (aggregates multiple data sources), the description fully enumerates what is returned and how to cite it. It also addresses the type limitation and parameter constraints, making it complete for an AI agent to use correctly.

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

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

Both parameters have schema descriptions (100% coverage), but the tool description adds meaningful extra context: for type, it notes only 'company' is supported and future plans; for value, it explains ticker vs CIK and explicitly warns that names aren't accepted—this guides correct 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 opens with a clear statement: 'Get everything about a company in one call.' It then lists concrete user queries ('tell me about X', 'research Microsoft') and explicitly contrasts with sibling tools like resolve_entity, making the purpose unmistakable.

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

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

Provides explicit when-to-use (company profile queries) and when-not-to-use (names not supported, must use resolve_entity). It also implies that for granular data you'd call individual pack tools, giving complete guidance on appropriate invocation context.

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

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

No annotations provided, so description carries full burden. It clearly states the action (delete memory by key), which implies irreversibility. Could be improved by noting behavior on missing key, but overall transparent for a simple deletion.

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

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

Two sentences: first defines action clearly, second provides context and usage guidance. No wasted words, front-loaded with core purpose.

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

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

For a simple tool with one parameter and no output schema, the description fully explains purpose, when to use, and relation to siblings. No gaps given the complexity.

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

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

Schema coverage is 100%. Description adds no extra meaning beyond schema's description of 'key' as 'Memory key to delete'. Baseline 3 is appropriate.

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

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

Description uses specific verb 'Delete' and resource 'memory by key', clearly distinguishing from sibling tools like 'remember' and 'recall' which store and retrieve respectively.

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

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

Explicitly states when to use: when context is stale, task is done, or clearing sensitive data. Also recommends pairing with 'remember' and 'recall', providing clear guidance on alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by detailing the internal steps (fetch, extract, emit) and the output format (single text blob for site-root/llms.txt). No contradictions.

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

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

The description is a single, well-front-loaded paragraph of ~60 words. Every sentence contributes essential information: purpose, process, output, and use cases. 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 low complexity, full schema coverage, and annotations covering safety, the description is nearly complete. It explains the tool's function, behavior, and output. Minor omission: no mention of error handling for unreachable URLs, but acceptable.

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 well-described. The description does not add any extra meaning beyond what the schema provides, so baseline of 3 is appropriate.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file', and the purpose 'for AI crawlers to index the site cleanly'. It explicitly differentiates from sibling tools by specifying a unique function.

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

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

Description provides three concrete use cases: getting a client's site indexed, drafting for own project, or auditing competitor visibility. It does not explicitly list when not to use or alternative tools, 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.

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

No annotations are present, but the description transparently indicates this is a read-only listing tool (inferred from 'list'). It discloses the filtering criterion and scope, which is adequate for a non-destructive operation.

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 that are concise, front-loaded with the main verb and resource, and every word adds value. 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 zero parameters, no output schema, and a simple filtered list purpose, the description fully covers what the tool does and its unique value among siblings.

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 the description adds no param info, but the baseline is 4 as schema coverage is 100% and there is nothing to document.

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 volcanoes above Normal/Green status, using specific verbs 'list' and 'elevated' with a clear subject. It differentiates from sibling 'list_volcanoes' by focusing on 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?

It implies usage for a quick snapshot of active volcanoes via 'smallest practical fingerprint of what's happening right now.' While it doesn't explicitly state when not to use or name alternatives, the mention of 'currently' suggests real-time monitoring context.

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

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

With no annotations provided, the description should disclose behavioral traits. It only mentions 'Recent' and filter capability, but no details on ordering, pagination, authentication, or whether the operation is read-only.

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 efficient sentence, front-loading key information. It could benefit from slight structuring (e.g., bullet points) but is not overly verbose.

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

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

For a simple list tool with 2 optional parameters and no output schema, the description covers the main purpose and filter. However, it lacks details on default ordering, recency semantics, and error handling, making it minimally complete.

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

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

Schema coverage is 100%, and the description mostly reiterates the schema with 'Filter by volcano slug'. It adds minimal value beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb (list/reports) and resource (USGS volcano notices), specifies types (VAN, VONA), and distinguishes from sibling 'list_volcanoes' through the mention of volcano slug filtering.

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 fetching recent volcano notices, but does not explicitly state when to use or not use this tool, nor does it mention alternatives beyond the implied contrast with list_volcanoes.

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?

With no annotations, the description carries full burden. It discloses the read-only nature ('List'), the scope (US volcanoes monitored by USGS), and the returned fields (alert level, color code). No hidden side effects are implied.

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?

A single sentence that efficiently conveys the tool's purpose, output, and filtering option without any unnecessary words.

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

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

For a list tool with one optional parameter and no output schema, the description sufficiently explains the return content (alert levels and color codes). It could mention pagination, but given the likely small dataset, this is acceptable.

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. The description adds value by listing the observatory short codes and explaining the mapping, which goes beyond the schema's basic description.

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

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

The description clearly states the tool lists US volcanoes monitored by USGS, specifying the returned fields (alert level, aviation color code) and optional filtering by observatory. This distinguishes it from siblings like 'list_elevated' and 'list_notices'.

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

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

The description mentions optional filtering by observatory, implying usage context, but does not explicitly state when to use this tool versus alternatives or 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?

No annotations exist, so the description carries full weight. It discloses behavioral traits: rate limit (5 per identifier per day), that it's free and doesn't count against quota, and that the team reads digests daily affecting roadmap. This is comprehensive for a feedback tool.

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 (~100 words) and front-loaded with purpose and use cases. Every sentence adds value: purpose, when to use, how to describe, administrative notes. No wasted words.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description covers all aspects: purpose, usage, constraints (rate limit, quota), and expected input format. It is complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds extra guidance beyond schema: for 'message' it suggests length (1-2 sentences, 2000 chars max) and specificity; for 'type' it reiterates meaning. This adds value, justifying above the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature, data_gap, praise) and differentiates itself from sibling tools like ask_pipeworx by focusing on feedback rather than data queries.

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

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

Explicit usage guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes negative guidance ('don't paste the end-user's prompt') and constraints (rate-limited to 5 per identifier per day).

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 valuable behavioral context beyond annotations: self-aggregating signal, caching duration, and no PII. 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 concise, well-structured with bullet points for use cases, and front-loaded with the main purpose.

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

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

For a tool with one optional parameter and no output schema, the description covers caching, aggregation source, and privacy, making it fully complete.

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

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

Schema coverage is 100% with enum values described. The description adds meaning by explaining that shorter windows surface hot topics and longer windows show steady-state demand.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window. It uses specific verbs and resources, and it is distinguishable from sibling tools like discover_tools.

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

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

Three explicit use cases are provided, giving clear context for when to use the tool. However, it does not explicitly mention when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe. Description adds rich behavior: walks child markets, groups related markets, checks monotonicity, returns ranked opportunities with reasoning. No contradictions; fully discloses internal logic.

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: three sentences with clear structure. First sentence states purpose, second explains two modes, third gives rationale for cross-event mode and expected return. No filler; each sentence adds essential context.

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

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

Given no output schema, description adequately specifies return value ('ranked opportunities with suggested trade direction + reasoning'). Covers both modes, explains why cross-event is needed, and references monotonicity violations. Combined with full schema coverage and annotations, nothing is missing for effective use.

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

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

Input schema has 100% coverage with descriptions. Description adds meaning by explaining the purpose of each mode with concrete examples (e.g., 'when-will-bitcoin-hit-150k', 'Strait of Hormuz traffic returns to normal'), and clarifies how the parameters relate to tool behavior (walking child markets, searching across events).

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

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

Description uses specific verb 'find arbitrage opportunities' and resource 'Polymarket', distinguishes two modes ('event' and 'topic'), and clearly explains what monotonicity checking does. This differentiates it from siblings like 'bet_research' or 'polymarket_edges'.

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

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

Explicitly describes two modes with clear cues: 'pass a single Polymarket event slug' for event mode, 'pass a topic / seed question' for topic mode. Explains why cross-event mode is necessary to catch cases missed by single-event mode. Lacks explicit when-not-to-use but provides strong context.

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

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

The description goes beyond annotations by detailing the V1 model (crypto-price bets, lognormal from FRED, live coinpaprika price), process (scans top markets, groups by asset, fetches price history once, computes probability, ranks by edge), and output (top N with suggested direction). This provides rich behavioral context.

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

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

The description is relatively verbose but every sentence contributes meaningful information. It is front-loaded with the core action and use case. Minor reduction could be possible, but it is well-structured for an AI agent.

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

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

Despite lacking an output schema, the description sufficiently explains the return values (top N ranked by edge magnitude with suggested trade direction). With no required parameters and simple schema, the description provides a complete picture for agent usage.

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 does not add new information about parameters beyond what is in the schema; it only mentions 'top N ranked by edge magnitude' which aligns with the 'limit' parameter description.

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

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

The description clearly states the tool scans high-volume Polymarket markets and returns those where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It implicitly distinguishes from sibling tools like polymarket_arbitrage and bet_research by focusing on edge 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?

The description explicitly targets the 'what should I bet on today' question, indicating when to use it. However, it does not explicitly mention when not to use it or compare alternatives like bet_research or polymarket_arbitrage, which would strengthen 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, idempotent, non-destructive. Description adds that it returns leg-by-leg prices and spreads in percentage points, and explains the two modes, which is valuable context beyond annotations.

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

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

Description is front-loaded with core purpose, then explains the delta, modes, and return structure. Slightly verbose but well-organized and 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 the complexity (two modes, no output schema), the description covers what it does, how to use, and what it returns. Lacks error handling details but is sufficient for an agent.

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

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

Schema has 100% coverage with descriptions. The description enriches with examples, explains topic as pre-mapped macros, and clarifies that explicit params override topic. Adds meaning beyond schema.

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

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

The description clearly states it calculates cross-venue spreads between Kalshi and Polymarket for the same question, distinguishing it 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?

It explains two modes (topic shortcuts and explicit tickers), when to use each, and that the spread is an arbitrage signal. It doesn't explicitly state when not to use, but context is clear.

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

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

With no annotations, description fully discloses behavior: retrieves or lists values, scoped to identifier, pairs with remember and forget. Does not cover rate limits or response format, but is transparent about core operations.

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

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

Three sentences, each essential: function, usage examples, scoping/pairing. Front-loaded with primary action, no waste.

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

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

Completeness is high given no output schema: explains purpose, usage, scoping, and sibling tools. Lacks return format details, but agent can infer from context. Adequate for decision-making.

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

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

Schema coverage is 100% with good descriptions. Description adds value by clarifying the optional key parameter and its effect (omit to list all keys), and provides use context beyond schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys if the key argument is omitted. It specifies the verb (retrieve/list) and resource (saved values), 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?

Provides explicit examples of when to use (e.g., user's target ticker, address, prior research notes) and explains scoping to an identifier. Lacks explicit when-not or alternative tool mention, but context is clear.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool fans out to three external sources (SEC EDGAR, GDELT, USPTO) in parallel, explains input formats for 'since', and describes the return value (structured changes, count, citation URIs). It does not mention rate limits or authentication, but for a read-only aggregator this is adequate.

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 and front-loaded with purpose and examples. It packs essential information (sources, parameter format, return type) without excessive fluff. Could be slightly tighter but overall 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?

For a tool with no output schema and three parameters, the description covers input, behavior, and output reasonably well. It explains the parallel fan-out and return format. Minor gaps: no mention of error handling or limitations, but still fairly complete given the tool's complexity.

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

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

Schema description coverage is 100%, but the description adds extra context: for 'since' it recommends '30d' or '1m' for typical monitoring; for 'value' it gives examples of tickers and CIK; for 'type' it notes only 'company' is supported. This meaningfully supplements 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: retrieving recent changes for a company, with specific example queries like 'what's happening with X?' and 'news on Apple this month'. It distinguishes itself from sibling tools like 'entity_profile' and 'compare_entities' by focusing on temporal updates.

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 multiple example user queries. It does not explicitly state when not to use or list alternative tools, but the examples and context make usage clear.

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

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

Given no annotations, the description discloses key behaviors: scoping by identifier, retention periods for authenticated vs anonymous users. Does not mention overwriting or limits but covers essential aspects.

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

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

Five concise sentences, each adds value: purpose, usage instructions, storage mechanism, persistence, sibling references. No redundancy or wasted words.

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

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

For a simple write tool with two parameters and no output schema, the description covers purpose, usage, storage semantics, persistence, and sibling relationships. No missing critical context.

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 3. The description reinforces the purpose of key-value pairs but does not add significant new parameter-level information beyond the schema examples.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, specifying a key-value pair storage. It distinguishes from siblings by explicitly pairing with recall and forget.

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

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

Provides explicit use cases (e.g., remembering resolved tickers, user preferences) and persistence details (24-hour for anonymous, persistent for authenticated). Lacks explicit 'when not to use' but examples guide appropriately.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns IDs and citation URIs, lists the ID types, and gives examples. It implies a read-only lookup with no side effects, which is sufficient.

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. Each sentence contributes useful information, including examples and a note about replacing multiple calls. No redundant or superfluous content.

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

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

Given the simple input schema and lack of output schema, the description sufficiently explains the tool's purpose, input parameters, return content (IDs and URIs), and usage context. It could mention handling edge cases like ambiguity, but overall it is complete enough for effective use.

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

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

Schema coverage is 100% with parameter descriptions. The tool description adds value by explaining acceptable input values (ticker, CIK, name; brand or generic name) with concrete examples, going beyond the schema's minimal descriptions.

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

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

The description clearly states the verb 'Look up' and the resource 'canonical/official identifier' for companies or drugs. It distinguishes itself from sibling tools by specifying that it provides identifiers (CIK, ticker, RxCUI, LEI) needed by other tools and that it replaces multiple lookup 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?

Explicitly tells when to use the tool ('when a user mentions a name and you need the CIK...') and provides ordering guidance ('Use this BEFORE calling other tools that need official identifiers'). No explicit when-not-to-use, but context is clear.

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

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

Description details behavioral traits beyond annotations: probes each entity, ranks by score, surfaces most/least recognized, returns score/confidence/signal density. Treats first entity as subject for narrative. 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?

Four sentences, front-loaded with primary action. No wasted words; each sentence adds essential information.

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

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

Given no output schema, description covers return format (ranked list with score/confidence/signal density). Addresses purpose, parameters, usage, and behavioral details. Complete for a comparison tool.

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

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

Schema has 100% coverage with descriptions. Description adds context: first entity is subject, models supported, _apiKey dependency, context disambiguates. Adds 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 states specific action: compare AI visibility across multiple entities side-by-side, probing with ai_visibility_check and ranking. Distinguishes itself from sibling ai_visibility_check by emphasizing multi-entity comparison.

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

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

Explicitly mentions use case: competitive AI-marketing audits. Implies when to use (multiple entities) but does not explicitly state when not to use or list alternatives, though context with siblings aids differentiation.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This information is beyond what annotations provide and helps the agent manage expectations.

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

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

The description is relatively long but well-structured, with the main purpose in the first sentence, followed by usage, return type, ecosystem limitations, and behavior notes. Every sentence adds useful information with minimal redundancy. Slight wordiness prevents a higher score, but it remains effective.

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

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

Given no output schema, the description thoroughly explains the return structure (summary block fields, advisory details, links, alternative versions) and handles edge cases like partial failures. This provides enough context for an agent to understand the tool's output and behavior completely.

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

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

Both parameters are fully described in the input schema (100% coverage). The description adds value by explaining that scoped packages are accepted and version defaults to latest, which reinforces and clarifies the schema. However, the schema already covers the basics, so the description provides moderate additional benefit.

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

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

The description clearly identifies the tool as a composite check for evaluating npm packages using deps.dev and bundlephobia, with a specific verb ('scan') and resource ('dependency'). It distinguishes from alternatives by noting that other ecosystems fall under deps.dev:version directly, making the purpose unambiguous.

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

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

The description explicitly states when to use the tool: whenever an agent asks about safety, popularity, or size of an npm package. It also provides an exclusion for other ecosystems and notes graceful degradation with bundlephobia timeouts, giving clear guidance on usage context.

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

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

No annotations are provided, so the description carries full responsibility. It details the output (verdict types, extracted form, actual value with citation, percent delta) and notes version limitations (v1 supports only company-financial claims). This sufficiently sets agent expectations.

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, front-loading the core purpose, then providing usage guidance, version scope, and output summary in a clear, well-structured paragraph with no superfluous content.

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

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

Given the tool's moderate complexity (single parameter, no nested objects, no output schema), the description covers purpose, usage, output format, and limitations. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The input schema already describes the 'claim' parameter with an example. The description adds crucial context about the domain of claims it can handle (company-financial) and the underlying data source, which goes beyond the schema's generic description. This compensates for the schema's limited scope.

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

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

The description clearly states the tool's purpose: fact-checking natural-language factual claims against authoritative sources. It specifies the domain (company-financial claims for US public companies) and the data source (SEC EDGAR+XBRL), making it highly distinguishable from sibling tools like ask_pipeworx or compare_entities.

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

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

Provides explicit usage scenarios with example queries ('Is it true that…?', 'Verify the claim that…') and indicates it replaces multiple sequential calls, but does not explicitly state when not to use it or compare with specific siblings. Nonetheless, the guidance is clear and practical.

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