Whiskyhunter

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

Annotations already indicate read-only and idempotent behavior; the description adds critical details: external API calls to Anthropic only if an API key is provided, and the user pays for those calls. It also outlines the return structure (score, confidence, signals, raw_response).

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

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

The description is four sentences long, each adding essential information: purpose, model options, output structure, and use cases. No redundant or vague 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 (4 parameters, no output schema), the description fully covers purpose, behavior, parameters, output structure, and use cases, leaving no obvious gaps.

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

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

All parameters are described in the schema (100% coverage), and the description adds context such as the default model (workers-ai), cost implications of _apiKey, and the disambiguation role of context.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model, which distinguishes it from sibling tools like scan_competitor_ai_presence that may have different outputs or methodologies.

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 specifies use cases (AI-marketing audits, brand checks, competitive monitoring) and explains default vs. paid model options, but lacks explicit when-not-to-use guidance or 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, destructiveHint. Description adds that the tool routes queries to one of 3,745 tools and returns structured answers with stable pipeworx:// citation URIs. This provides behavioral context beyond annotations, though does not cover limits or error behavior.

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

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

The description is moderately long but front-loaded with the key guidance ('PREFER OVER WEB SEARCH'). Every sentence adds value, providing examples and use cases. Could be slightly trimmed, but overall efficient and well-structured.

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

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

Given the tool's complexity (meta-tool over many sources) and the rich schema/annotations, the description covers purpose, usage, and output format (citation URIs). It lacks details on limitations or error handling, but is sufficient 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?

Schema has 100% description coverage with detailed parameter descriptions for all six aliases. The description only reiterates that the tool accepts a natural language question, adding negligible value beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool answers factual questions using authoritative structured data, with explicit domains (SEC filings, FDA, etc.) and citations. It distinguishes itself from web search by highlighting structured data and citation URIs, though it doesn't differentiate from sibling ask_pipeworx_grounded. Overall purpose is very clear and actionable.

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 strong guidance: 'PREFER OVER WEB SEARCH' and lists specific trigger phrases ('what is', 'look up', etc.). Includes examples and explicitly states to use even when web search could answer. No explicit when-not-to-use, but the guidance is comprehensive enough for an AI to decide.

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

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

Adds value beyond annotations by describing the extraction process, refusal reasons, and extra LLM cost. Annotations already cover read-only and idempotent nature, so some redundancy exists but not contradictory.

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?

Efficient single paragraph, front-loaded with purpose, each sentence adds essential information. 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 no output schema, description fully explains return structure, failure modes, and usage context. Covers all necessary behavioral details 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 all parameters documented. Description does not add new parameter-level information beyond what schema provides, meeting baseline with no extra 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?

Clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads. Distinguishes from sibling ask_pipeworx by emphasizing safety and refusal reasons.

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 (high-stakes, non-invented facts) and when not (casual lookups, prefer ask_pipeworx). Provides clear decision criteria.

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, open-world, and idempotent. The description adds behavioral context: it aggregates online whisky-auction data, prices are in each house's reporting currency, and it's keyless. 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 two sentences, each serving a purpose: stating what data is returned and adding key context (currency, keyless). No wasted words; front-loaded with the main result.

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 low complexity (one optional param, no output schema), the description covers essential aspects: data type, scope, currency, auth. Could mention return format (array of objects) but not critical.

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 'newest first' ordering detail not in the schema, but otherwise the parameter is straightforward and schema provides sufficient info.

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

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

The description uses specific verbs and nouns: 'Latest aggregate monthly stats per online whisky-auction house' and lists the exact fields returned. This clearly differentiates from sibling tools, none of which mention auction stats or whisky.

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 monthly auction stats but provides no guidance on when to use this tool versus alternatives (e.g., other data tools). It mentions 'Keyless' but doesn't specify prerequisites or exclusions.

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 behavior beyond annotations: fan-out examples, response shapes, resolver contract, parent event extraction, news fallbacks, safety blocking, wide spread warnings, cancellation rule parsing. No contradiction with annotations.

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

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

The description is very long but well-structured and every sentence adds value. It is front-loaded with purpose and then logically organized. Could be slightly more concise, but the density of information is justified by tool 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 no output schema, the description must cover return values and does so thoroughly: result.market, analysis, evidence, resolver contract, parent event, news fields, safety conditions. Edge cases and blocking routes are covered.

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

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

The description adds significant meaning beyond the schema: explains market input formats (slug, URL, question), depth options (quick vs. thorough with examples), and include_raw behavior (summarized vs. full payloads). Schema coverage is 100% but description enriches understanding.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with specific verb-resource ('Research a Polymarket bet') and examples of use cases. It distinguishes from siblings by being the dedicated bet research 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?

Explicitly says when to use (e.g., 'should I bet on X') and provides examples. Also advises on when not to fully trust (low-confidence matches, closed markets) and warns about resolution-rule risks.

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 (readOnlyHint=true), open-world (openWorldHint=true), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds context: for companies it pulls latest 10-K data with proper fiscal year handling, for drugs it pulls FAERS data. It also mentions sorted results and citation URIs, going 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 relatively long but each sentence adds value, with example queries front-loaded. It efficiently conveys purpose, usage, behavioral details, and return format. Minor redundancy could be trimmed, but overall it's well-structured.

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

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

Given the tool's complexity (2–5 entities, two types, external data sources), the description is comprehensive. It covers all key aspects: entity types, data sources, fiscal year handling, sorted results, and citation URIs. No output schema exists, but return format is mentioned. Completely adequate.

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

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

Schema coverage is 100% and both parameters (type, values) are well-described in the schema. The description adds usage context (e.g., tickers for companies, names for drugs) but does not significantly enhance parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it performs side-by-side comparisons of entities (companies or drugs) in a single parallel call, with specific examples like 'Compare X and Y' and 'which is bigger / better / larger / more profitable'. It distinguishes itself from sequential lookups by replacing 8–15 of them.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool. It also gives example queries and explains the behavior for each entity type.

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 detailed behavioral traits beyond annotations: decomposition into sub-questions, parallel routing to 3,745 tools, return format with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, and explicit gaps[] array. Also states it never invents answers. All consistent with annotations (readOnly, idempotent, non-destructive).

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 the core value proposition in the first sentence. Four sentences cover what, how, when, and prerequisites without unnecessary words. Structure is logical and efficient.

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

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

Covers almost all relevant aspects for an AI agent: operation, usage, requirements, output hints, and timing. Lacks a precise description of the output structure format, but the description of 'structured findings packet' and the cited fields is sufficient for tool selection.

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 provides clear descriptions for both parameters (100% coverage). The description reinforces that 'broad/multi-part is fine' and mentions paid plan for depth, but adds no critical 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?

The description clearly states the tool's purpose: 'Grounded multi-source research in ONE call' with explicit details on how it decomposes questions and routes to thousands of sources. It distinguishes itself from sibling 'ask_pipeworx' by specifying that deep_research is for broad/multi-part questions.

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

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

Provides explicit usage guidance: 'Use for broad or multi-part questions' and 'use ask_pipeworx for single lookups.' Also mentions prerequisites (Pipeworx account, paid plan for 'thorough' depth) and expected timing (15-60s).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: it returns top-N most relevant tools with full input schemas and curated examples, ready to call directly without a second lookup. It also explains the return format, which goes 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?

The description is front-loaded with the core purpose, followed by examples and usage context. While it is somewhat lengthy, every sentence contributes information (purpose, when to use, return format, and aliases). It could be slightly tighter but 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 that the tool has 6 parameters (all described), no output schema, and no nested objects, the description adequately covers what the tool does and what it returns (top-N tools with schemas). It explains the return value's utility ('ready to call directly'). The context signals indicate low complexity, and the description is complete enough 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 description coverage is 100%, so baseline is 3. The description adds value by listing aliases (q, task, search, description) and clarifying that 'query' accepts natural language. It also provides examples. The 'limit' parameter is described as optional with defaults. This enriches 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: 'Find tools by describing the data or task.' It uses specific verbs like browse, search, look up, discover, and identifies the resource as tools. It distinguishes from siblings by explicitly stating 'Call this FIRST when you have many tools available and want to see the option set,' setting it apart from other tools that directly answer 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?

The description provides explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: [list of domains]' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It gives clear context and when to use, though it does not explicitly name alternative tools for exclusion.

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

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

Annotations already convey readOnly, openWorld, idempotent, non-destructive. Description adds behavioral context: aggregates multiple auction houses, prices in reporting currency, returns keyless data. This complements annotations well, but could mention rate limits or pagination. No contradictions.

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

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

Three sentences, front-loaded with key information, no fluff. Every sentence adds value: output description, data source, input 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?

Given no output schema, the description explains return fields (max/min/mean, volume, lots) and time range (~60 months). With one parameter and good annotations, the description is fully adequate.

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

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

Schema covers slug fully (100% coverage). Description adds value by specifying that slugs come from list_distilleries and providing examples, which helps the agent generate correct inputs.

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 provides monthly price/volume history for a single distillery, listing specific metrics (max/min/mean bid, volume, lots count). It clearly distinguishes from sibling tools like auction_stats (broader) and compare_entities (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 tells the user to pass a slug from list_distilleries and gives examples. Implicitly guides when to use (for single distillery monthly history) versus alternatives. Could be improved by explicitly stating when not to use, but overall clear.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds details on parallel fan-out, soft-fail for patents, fallback mechanisms, and specific return fields. 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 relatively long but front-loaded with example queries and every sentence adds value. Could be slightly more concise but 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 complexity (multiple sources, many return fields), the description is very complete, covering all key aspects even without an output schema. Returns are fully described.

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 value by explaining parameter types with examples (ticker or CIK), and clarifying that names are not supported, going 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's purpose: providing a full cross-source profile of a US public company in a single parallel call. It lists specific sources and return fields, and explicitly distinguishes it from chaining single-pack lookups.

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

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

Provides explicit when-to-use (holistic view) and when-not-to-use (names not supported, recommend resolve_entity first). Also suggests preferring over 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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, reinforcing the permanence and safety implications 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 concise sentences: first states the core function, second provides use cases and pairing advice. No redundant information.

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

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

Given the tool's simplicity (1 required param, no output schema), the description fully covers purpose, usage, and complementary tools. No gaps.

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

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

Schema coverage is 100% with one parameter 'key' (string, described as 'Memory key to delete'). The description does not add extra semantic meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' using a specific verb and resource. It distinguishes itself from sibling tools 'remember' and 'recall' by being the deletion counterpart.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also advises 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, idempotent, non-destructive behavior. The description adds detail about the specific actions (fetches page, extracts info, emits markdown) and the output format, providing useful context beyond annotations.

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

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

The description is two sentences plus a bulleted list of use cases, tightly written with no filler. The key action and output are front-loaded, making it easy for an agent to parse quickly.

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 two parameters (one required) and no output schema, the description adequately explains the process and output (a single text blob). No additional context seems necessary.

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 both parameters are well-described in the schema (url: 'Full URL of the site to summarize', max_links: includes default and max). The main description does not add additional parameter meaning, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file by fetching a URL, extracting title/description/key links, and emitting standard markdown. This distinguishes it from sibling tools like scan_competitor_ai_presence or ai_visibility_check, which have different purposes.

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

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

The description lists three concrete use cases (indexing a client's site, drafting for own project, auditing a competitor). While it does not explicitly state when not to use or compare to siblings, the use cases provide sufficient context for appropriate invocation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Description adds the behavioral note that it is keyless and describes the output structure. However, no additional details on rate limits, pagination, or potential consumption limits are provided, which would add value beyond the annotations.

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

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

Two concise sentences with no fluff. First sentence defines purpose and scope, second sentence adds usage guidance and keyless note. Every sentence earns its place.

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

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

Given the tool's simplicity (2 optional parameters, read-only, no output schema) and rich annotations, the description adequately covers purpose, output, and relationship to sibling. Minor gap: no mention of total distilleries count or pagination behavior beyond the limit parameter.

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 input schema already describes both parameters (limit and search). The description adds no new parameter semantics beyond restating that search is case-insensitive; it is redundant with the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool lists whisky distilleries tracked by whiskyhunter.net, specifies scope (300+ distilleries), and mentions return fields (name, slug, country). It also differentiates from the sibling tool distillery_prices by directing usage of the slug with that 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 explicit guidance on using the returned slug with distillery_prices for price history, and notes the tool is keyless (no API key). Does not explicitly mention when not to use it or other alternatives, but the context is clear.

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

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

Annotations already declare readOnly, idempotent, not destructive. The description adds return field names and scope (active by default). No contradictions, but no additional behavioral depth beyond annotations.

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

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

Two concise sentences, front-loaded with verb and resource. No wasted words; each sentence adds value.

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

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

For a simple list tool with one optional parameter and no output schema, the description adequately covers what is returned and when to use it. Could mention pagination but not necessary for this scope.

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 for the single parameter. The description does not elaborate on the parameter, but the schema description is sufficient. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists subscriptions and specifies return fields. It mentions 'active subscriptions' which is a slight mismatch with the include_inactive parameter, but the core purpose is clear and distinguishable from sibling subscribe/unsubscribe.

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

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

Provides explicit use cases: reviewing monitoring and finding IDs for cancellation. Implicitly guides when to use this tool versus siblings (subscribe/unsubscribe) by mentioning 'before adding more' or 'to cancel.'

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 behavioral context beyond annotations: rate limit (5 per day), free, not counting against quota. It does not mention any destructive or read-only behavior, consistent with annotations. It could disclose what happens to the feedback (digests, roadmap signal) but that's 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 tight, front-loaded with the main purpose, and each sentence provides actionable information. No unnecessary words. Perfectly concise for the 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?

The description covers the essential aspects: purpose, usage guidelines, formatting instructions, rate limits, and quota impact. It does not explain the optional context parameter in detail, but the schema does. For a low-complexity tool, this is nearly complete. Could mention that context is optional.

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

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

Schema already fully describes parameters with 100% coverage. Description adds guidance on how to format the message (relate to tools/packs, avoid user prompts). This is helpful but not essential. 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 uses specific verbs ('tell', 'describe') and resources ('Pipeworx team', 'tools/packs'), and explicitly lists use cases ('bug', 'feature/data_gap', 'praise'), clearly distinguishing it from sibling tools like 'pipeworx_trending' or 'ask_pipeworx'.

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

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

The description provides clear scenarios for usage (bug, feature/gap, praise) and explicit 'don't' instruction (don't paste user prompt). It includes rate-limit and quota info. However, it does not give alternative tools for when not to use, so not a 5.

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

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

Beyond annotations that already mark it as read-only and idempotent, the description adds valuable transparency: it explains the tool is self-aggregating, derived from analytics, contains no PII, and is cached with specific durations. This fully informs the agent about behavior.

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

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

The description is well-structured with key information upfront. Each sentence adds value, though it is slightly verbose. Could be trimmed slightly 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?

Despite lacking an output schema, the description adequately explains the return values (top tools, top packs, total call volume). Given the tool's simplicity and the strong annotations, it provides sufficient context for an agent.

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

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

Schema coverage is 100% and includes descriptions for the enum values. The description adds extra semantic context by explaining that shorter windows surface hot trends while longer windows show steady-state demand, going beyond the schema.

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume over a window. It uses a specific verb 'Returns' and distinguishes itself from siblings like 'discover_tools' by focusing on trending data.

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

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

The description lists three concrete use cases (discovering hot data sources, confirming canonical choice, seeing alignment). While it doesn't explicitly state when not to use or name alternatives, it provides clear context for 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 safe, idempotent, non-destructive operation. The description adds significant behavioral detail: fill check logic, semantic anchor with Jaccard similarity, partition filter with placeholder detection, and conditions under which signals are not actionable. 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 dense but efficient, packing essential operational details into a coherent narrative. However, it could benefit from clearer sectioning (e.g., bullet points) for readability, but it avoids redundancy and front-loads key constraints.

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

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

Given the tool's complexity (two modes, multiple sub-checks, fill analysis), the description covers all major aspects: mode selection, thresholds, response fields, and limitations. Without an output schema, it provides sufficient detail about the response structure and conditional behaviors.

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 100% schema description coverage. The description adds examples (e.g., 'fed-decision-may-2026') and explains the behavioral difference between 'event' and 'topic' modes, providing context beyond the schema.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes between single-event and cross-event modes, which differentiates it from sibling tools like polymarket_edges.

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

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

The description explicitly requires one of 'event' or 'topic', warns against calling with no args, recommends 'event' for specific markets and 'topic' for cross-event scanning. It also mentions 'polymarket_fill_risk' for custom sizing, guiding the agent to an alternative tool.

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

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

The description extensively details behavioral traits beyond annotations: caching at 1h KV level, Fed bet exclusion rationale, model family mechanics, output structure with diagnostics, and knob behaviors. It aligns with annotations (readOnlyHint, idempotentHint) and adds substantial 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 detailed and well-structured with clear sections, but it is quite long. For a complex tool, this level of detail is acceptable, but some information (e.g., detailed model math) could be trimmed or referenced elsewhere. First sentence effectively states the core purpose.

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

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

Given the tool's complexity (9 parameters, no output schema), the description covers all necessary aspects: purpose, usage, behavioral details, parameter roles, output structure, and diagnostics. It explains why certain segments appear empty and why Fed bets are excluded, making it self-contained and sufficient for confident invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by grouping parameters as 'tradeable-edge knobs' and explaining the purpose of min_partition_leg_kelly for partition opportunities. This provides context 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's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly targets the 'what should I bet on today' use case and distinguishes its scope by describing three model families and the exclusion of Fed bets. While sibling tools exist, the description differentiates by highlighting the comprehensive scanning and disagreement detection.

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: it is built for discovering betting opportunities without manual paging. It explains tradeable-edge knobs and when Fed bets appear but are excluded. However, it does not explicitly state when to use alternative tools like polymarket_arbitrage or polymarket_edge_tracker, which would improve guidance.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: how snapshots are written, gaps in data, that decay is computed from daily closes, and the bounded history depth. 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 structured with clear sections: purpose, args, response, limits. It is front-loaded with the core question it answers. While lengthy, every sentence adds value and avoids redundancy. Could be slightly more concise but still well-organized.

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

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

Given there is no output schema, the description thoroughly explains the three response arrays (tracked, expired, snapshot_dates) with field details. It also covers caveats like TTL and snapshot gaps, making the tool's behavior fully understandable 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?

Both parameters are described in the schema with coverage 100%. The description adds meaning beyond schema by specifying defaults (days=14, window='1wk'), constraints (days clamp 2-30), and interpreting the window parameter as 'snapshot family'. This helps the agent understand parameter impact.

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

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

The description clearly states the tool provides 'Edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from siblings like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description gives explicit context with the example of a fresh wide edge vs. a 3-week-old wide edge, implying when to use this tool (to understand edge history). It also mentions limits like 60-day TTL and snapshot gaps, providing guidance on interpretation. However, it does not explicitly name 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral detail: walks the ladder, returns specific fields, warns about partial fills and directional risk, and mentions size clamp. This adds context beyond the annotations, but the annotations already cover safety profile.

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 but well-structured with sections separated by periods and key points in all-caps. It front-loads the purpose and requirements. Each sentence adds value, but some 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?

No output schema exists, yet the description fully explains all return fields for both modes, including edge cases (thin legs, forced directional risk). It provides complete context for usage, making up for the lack of output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the meaning of side options, default behavior for basket mode, and interpretation of size_usd as settlement notional. It also clarifies how parameters affect return fields.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and specifies inputs like market slug and side. The tool's purpose is distinct from siblings polymarket_arbitrage and polymarket_edges, as explicitly stated.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, e.g., partial basket fills convert an arb into an unhedged directional position, the dominant loss mode.

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, non-destructive. The description adds extensive behavioral context: response structure (leg-by-leg prices, top spreads), safety fields (compatibility_warning, temporal_alignment), and explanation of skipped cross types. It fully discloses edge cases where spreads are meaningless.

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 (~350 words) but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence contributes unique information. It could be slightly more concise, but the density is justified by the tool's complexity.

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

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

Given the tool's complexity and absence of an output schema, the description is exceptionally complete. It covers response fields (leg prices, spreads, compatibility_warning, temporal_alignment, counters) and explains all safety fields thoroughly. No gaps remain for the 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%, so baseline is 3. The description adds value by explaining the interplay between parameters (explicit tickers override topic-mapped sides) and listing the 10 topic shortcuts. It provides examples and clarifies how each parameter is used, raising it above baseline.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts vs explicit tickers) and explains the concept of spread and when it's meaningful, making it distinct from siblings 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 explicitly tells when to use each mode: topic for pre-mapped macros, explicit tickers for custom pairings. It warns that most pre-mapped topics return compatibility_warning and that pre-mapped doesn't guarantee tradeability, providing clear when-not-to-use guidance.

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

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

Annotations declare readOnly and idempotent. Description adds that omitting key lists all keys and that results are scoped to an identifier, providing useful context beyond annotations.

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

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

Three concise sentences front-load the primary action and purpose, with zero wasted words.

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

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

For a simple retrieve/list tool with one optional parameter and no output schema, the description fully covers purpose, usage, scoping, and pairing with 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?

Schema covers key parameter (100% coverage). Description explains behavior when key is omitted (list keys) and gives examples of key values, adding meaning beyond the schema.

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

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

Clearly states it retrieves a saved value or lists keys, with verb 'retrieve' and 'list', and distinguishes from siblings 'remember' and 'forget'.

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

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

Provides examples of when to use (look up user's target ticker, address, research notes) and mentions scoping. Does not explicitly state when not to use or alternative tools beyond remember/forget.

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

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

Adds behavioral details about mark_read mutating read state and polling compatibility, beyond the annotations that declare readonly and idempotent.

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

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

Single well-structured paragraph with front-loaded purpose, 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, description lists returned fields and mentions polling and alternative API, adequately covering all 5 optional 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 covers 100% of parameters with descriptions, and the tool description adds concrete examples and context like 'e.g. sec_8k' for type and default limit of 50.

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 'Pull fired events from your subscription feed', specifies returned fields, and distinguishes from sibling tools like list_subscriptions.

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

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

Provides context on polling suitability and mentions alternative direct API endpoint, but lacks explicit when-not-to-use or comparison to siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description goes beyond by detailing the fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and the accepted date formats. 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 dense but front-loaded with intent examples. Every sentence contributes unique information (sources, fallbacks, date formats, comparison to sibling). Slightly long but justified given the multi-source 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 data sources, fallback logic, structured output), the description covers all needed context: fan-out behavior, fallback reasoning, API sunset notice, return structure (changes[], total_changes, pipeworx:// URIs). No output schema, but the description sufficiently describes the response shape.

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%. The description adds valuable context: the type parameter is limited to 'company', the since parameter explains ISO vs. relative with example values, and value clarifies ticker or CIK. Includes a recommended monitoring window, enriching 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 user-facing query examples, immediately clarifying the tool's purpose as a multi-source change feed for a company over a time window. It distinguishes itself from the sibling tool entity_profile by contrasting static vs. dynamic data, 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?

Explicitly tells when to use this tool ('change feed for a company in the last N days') and when not to ('Use entity_profile instead when you want the static profile'). Also provides typical monitoring periods ('30d' or '1m'), giving concrete guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds value by explaining scoping by identifier, session persistence durations, and that data is stored as key-value pairs, which provides necessary context beyond the annotations.

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

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

The description is four sentences long, front-loaded with the core action and examples, and every sentence provides necessary information without redundancy. It is concise yet comprehensive.

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 key-value memory tool with no output schema, the description fully covers what the tool does, when to use it, how data is stored, and its persistence behavior. No gaps are evident 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%, so the baseline is 3. The description includes examples of key names (e.g., 'subject_property') and clarifies that value is any text, but this largely mirrors the schema's own descriptions without adding significant new semantics.

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

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

The description uses a specific verb ('Save data') and clearly identifies the resource ('data the agent will need to reuse later'). It provides concrete examples (ticker, address, preference) and explicitly distinguishes itself from sibling tools 'recall' and 'forget'.

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

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

The description explicitly states when to use ('when you discover something worth carrying forward'), mentions pairing with recall and forget, and clarifies the persistence differences between authenticated users (persistent) and anonymous sessions (24 hours), leaving no ambiguity about 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?

All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and indicate a safe, read-only, idempotent operation. The description adds valuable behavioral context beyond annotations: it explains that each call cascades through several lookup endpoints, mentions citation URIs, and specifies the exact return data for each type. This gives the agent a clear understanding of internal behavior 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?

The description is well-structured and front-loaded with examples, making the tool's purpose immediately clear. It contains a few redundant phrases (e.g., 'accepts ticker, CIK, or company name as input — auto-disambiguated') but overall remains efficient. The length is justified by the need to cover two entity types thoroughly.

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

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

Given the absence of an output schema, the description provides complete contextual information about return values for both entity types, including citation URIs. It also explains the cascading behavior. No additional details are necessary for an agent to understand what the tool does and what it returns.

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 significantly enhances parameter understanding. For the 'type' enum, it explains the return values for each option. For 'value', it lists acceptable input formats (ticker, CIK, name for company; brand or generic name for drug) and provides examples. This goes beyond the schema's basic descriptions and helps the agent correctly formulate inputs.

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's core purpose: resolving user-spoken names to canonical/official identifiers. It provides concrete examples ('What's the ticker for...') and explicitly lists supported entity types (company, drug) with their return values. The phrase 'Use FIRST whenever you have a name but need an ID' further clarifies its primary role, effectively distinguishing it from sibling tools like compare_entities or entity_profile.

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

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

The description explicitly states when to use the tool ('Use FIRST whenever you have a name but need an ID'). It also details what inputs are accepted for each type and mentions that it replaces multiple manual lookups. However, it does not explicitly state when NOT to use it or contrast with alternatives. Still, the context is clear enough for an agent to select it 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds value by explaining the multi-probe behavior (using ai_visibility_check per entity), ranking, and return fields (score, confidence, signal density). No contradictions with annotations.

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

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

The description is concise and well-structured, with each of the four sentences serving a purpose: defining the action, explaining the process, giving a use case, and stating the output. There is no redundant 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?

The tool has 4 parameters (1 required), no output schema. The description explains the return type (ranked list with score, confidence, signal density) adequately. It does not explain the ai_visibility_check inner workings but that is acceptable for an aggregate tool. Slightly more detail on output format could help but is not critical.

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 all parameters and their meanings. The description does not add additional parameter-level details beyond the schema, which is acceptable. Baseline score of 3 is appropriate.

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

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

The description clearly states that the tool compares AI visibility across multiple entities side-by-side, probes each entity with ai_visibility_check, and returns a ranked list. It is distinguished from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by being specific to AI visibility auditing.

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

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

The description provides a use case example ('competitive AI-marketing audits') and implies when to use (when needing side-by-side comparison) but does not explicitly state when not to use or mention alternatives. It is clear enough for an agent to understand the context.

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

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

Annotations readOnlyHint, openWorldHint, idempotentHint are already present. Description adds significant behavioral details: fans out across two services, returns summary block, per-advisory detail, alternative versions, and crucially warns about bundlephobia's first measurement taking 5-30s and graceful degradation via sources_failed.

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 is front-loaded with purpose. While it contains valuable detail, it is somewhat long; a bit more structural separation (e.g., bullet points for return fields) could 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?

Despite no output schema, the description completely enumerates return fields: summary block with 9 fields, per-advisory detail, links, alternative versions, and error handling (sources_failed). Covers all necessary context for a tool with 2 simple 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 descriptions for both parameters. Description adds value: for package, it clarifies scoped packages are accepted; for version, it states defaults to latest when omitted. This goes beyond the schema.

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

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

The description starts with 'Composite should I add this npm package to my project check' clearly stating the verb (check) and resource (npm package). It distinguishes from siblings by being a composite scan across deps.dev and bundlephobia, specific to npm packages.

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: 'Use whenever an agent asks is X safe / popular / small' and includes exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' Also notes partial failure timing.

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 details beyond annotations: it specifies the embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), character cap (200K), and truncation behavior. Annotations already declare readOnlyHint and idempotentHint, but the description enriches understanding of how the tool works internally.

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

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

The description is well-structured, front-loading the core purpose and usage, then providing technical details. Each sentence adds value, and there is no redundancy or unnecessary fluff. Appropriate length for the complexity.

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

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

Despite no output schema, the description explains that the tool returns top-N passages with character offsets and similarity scores. It also covers the truncation flag for long inputs. Given the moderate complexity and full coverage of inputs and outputs, the description is complete.

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

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

With 100% schema description coverage, the baseline is 3. The description enhances semantics by providing concrete examples for the query parameter (e.g., 'supply-chain risk'), clarifying the text parameter as 'the text you already pulled', and noting the 200K char limit. This adds practical usage context beyond the schema.

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

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

The description clearly states the verb 'search' and the resource 'inside a fetched record'. It distinguishes from siblings by explicitly mentioning pairing with ask_pipeworx_grounded and focusing on already-fetched text, making the tool's unique role 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 says to use when the record is too large to fit in the prompt and explains how it saves context. It mentions pairing with ask_pipeworx_grounded but does not explicitly list when not to use. Still, clear guidance is provided.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=true) are present. Description adds detailed behavioral info: persistence requirement, return of subscription id, webhook HMAC signing and auto-disable after 10 failures, and delivery channel constraints. No contradiction with annotations.

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

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

Description is detailed but front-loaded with purpose. It uses a single paragraph with inline lists for types, which is somewhat dense but efficient. Every sentence adds value; however, additional structuring (like bullet points) could 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?

Tool has no output schema, but description mentions return of subscription id. It covers all subscription types, parameter formats, delivery channels, authentication requirements, and rate limits (SMS cap). Comprehensive for a creation tool.

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

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

Schema coverage is 100%, but description provides extensive per-type parameter examples and constraints (e.g., item codes, sponsor/condition requirements) that go beyond the schema's descriptions. Delivery object also well-documented with 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?

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on subscription creation.

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

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

Description explicitly requires a Pipeworx OAuth account (no anonymous/BYO), and notes constraints like phone verification and SMS cap. It does not name alternatives to this tool, but the context is clear enough for an agent to determine when 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 (readOnlyHint, etc.), the description explains that it returns category-bucketed example questions with tool+argument shapes, and can be called with no arguments or with a topic. 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 with an opening line capturing common queries, a summary of output, and usage notes. It is informative but slightly verbose; could be more concise without losing clarity.

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

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

Given the tool's simplicity (one optional param, no output schema), the description fully covers purpose, usage, parameter semantics, and behavioral aspects. No gaps.

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

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

Schema coverage is 100% for the single parameter. The description adds value by explaining that omitting topic gives a full spread and passing a specific topic focuses the results.

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 example questions for Pipeworx, categorized by topic. It uses specific verbs and resources, and distinguishes itself from sibling tools by being the onboarding entry point.

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

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

The description explicitly says to use this tool first when the agent doesn't know what Pipeworx can do or to learn how to call meta-tools. It provides clear context but does not explicitly list 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 the tool is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false), and is idempotent. The description adds valuable details beyond annotations: the row is deactivated (not deleted) and historical events remain via recent_alerts. This clarifies the exact behavioral effects.

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

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

The description is extremely concise, consisting of two clear sentences. The primary action is front-loaded, and every sentence provides essential information without unnecessary words. It is well-structured for quick comprehension.

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 parameter and no output schema, the description covers the primary purpose, constraints (ownership), and consequence (deactivation). It references the sibling tool 'recent_alerts' for historical data access. This is fairly complete, though it could mention that calls are idempotent (covered by annotations) or what happens if the subscription doesn't exist.

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 already has 100% coverage with a description for the 'id' parameter. The tool description does not add new semantic information about the parameter beyond what the schema provides (it is the subscription id). Following the baseline for high coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Cancel a subscription by id.' It uses a specific verb ('cancel') and resource ('subscription'), and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by its unique action. The additional details about ownership enforcement and deactivation behavior provide further clarity.

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

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

The description explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), which guides when the tool is applicable. It also implies when not to use (if you lack ownership) and references the related tool 'recent_alerts' for historical data. While not exhaustive, it provides clear context for usage.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds valuable behavioral context: mentions return verdict types, extracted structured form, citation, and delta, and explains the underlying data sources (SEC EDGAR+XBRL). 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 front-loaded with examples and key points. Each sentence adds value, but it is slightly lengthy. Could be trimmed without losing meaning, 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?

Given the tool's complexity (claim verification with one parameter and no output schema), the description fully explains its domain, use case, output structure, and value proposition. It is complete for an agent to select and invoke correctly.

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

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

Only one parameter 'claim' with schema description coverage at 100%. The description adds natural-language examples but does not add additional semantics beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description explicitly states the tool verifies natural-language claims against authoritative sources, with specific verb 'validate' and resource 'claim'. It provides example queries and distinguishes itself by stating it replaces multiple sequential calls, making purpose very 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 clearly says to use whenever the agent needs to check factual correctness of a user's statement, and specifies the domain (company-financial claims). However, it does not explicitly state when not to use or suggest alternatives among the sibling tools, so it lacks exclusions.

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