Yelp

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds context that the default model is free (Workers AI) and that using Anthropic requires a BYO key (billing transparency). It also describes the return format (per-model objects with score, confidence, signals, raw_response). 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 three sentences long, front-loading the main purpose. Every sentence adds necessary information (purpose, models, billing, returns). No redundant or vague phrasing.

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 partially explains the return (per-model object with fields, combined view). It omits details about the structure of signals or raw_response, but for a probe tool with clear annotations (idempotent, read-only) and 4 parameters, it is functionally complete.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds practical examples for entity (e.g., 'Pipeworx'), clarifies model options and defaults, explains _apiKey requirement, and details context usage. This adds value beyond the schema, justifying a score above the baseline of 3.

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

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

The description states the tool probes LLMs for knowledge about an entity and scores visibility per model. It clearly identifies the verb (probe), resource (LLMs), and output (score, confidence, signals). The mention of default and optional models distinguishes it from sibling tools like 'scan_competitor_ai_presence'.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use optional parameters (_apiKey for Anthropic, context for disambiguation). It lacks direct exclusions or comparisons to alternatives, but the guidance is clear enough.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds significant behavioral context: it routes to 3,336 tools across 747 sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. This goes beyond what annotations provide and is fully consistent.

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

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

The description is informative but somewhat lengthy. It front-loads the key guidance and provides examples. It could be slightly more concise, but every sentence adds value.

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

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

Despite having no output schema, the description explains the return format (structured answer with citation URIs). It covers the tool's scope, usage patterns, and routing behavior, making it comprehensive for a tool of this 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% with each parameter fully described. The description adds no additional parameter information beyond the schema, but the schema itself is rich with aliases. Baseline 3 is appropriate as the description does not need to add more.

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 is for answering factual questions about structured data with citations, listing many domains and giving examples. It distinguishes itself from web search by explicitly stating 'PREFER OVER WEB SEARCH'.

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

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

The description provides explicit guidance on when to use this tool over web search, listing concrete question types and patterns (e.g., 'what is', 'look up', 'find'). It does not explicitly state when not to use, but the context is clear and sufficient for an agent 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?

The description extensively details behavioral traits beyond annotations: safety mechanisms (low-confidence, closed markets, wide spreads), resolver contract, parent event extractor, news fallback, and response shapes. Annotations already 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?

The description is lengthy but well-structured with sections and examples. Every sentence adds value. Slightly more concise could improve, but the complexity justifies the length.

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

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

Despite no output schema, the description fully explains return shapes, error conditions, and edge cases (blocking routes, low-confidence paths). It covers all fields an agent would need to interpret results.

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

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

Schema coverage is 100%. The description adds meaning beyond schema with examples of market input formats, depth options, and include_raw behavior. It clarifies how parameters affect fan-out and output size.

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

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

The description clearly identifies the tool as researching a Polymarket bet by pulling Pipeworx data, resolving the market, classifying the bet, and fanning out to data sources. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on single-bet research.

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

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

The description provides explicit use cases (e.g., 'should I bet on X', 'what does the data say about Y') and examples. It lacks explicit when-not-to-use guidance but is otherwise strong. Context from siblings is available.

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, openWorld. Description adds critical details: company data sources (SEC EDGAR/XBRL latest filing fix, off-calendar fiscal years) and drug data (FAERS, FDA, trials). 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?

Front-loaded purpose and use cases, then provides detailed breakdown per type. Slightly long but well-structured and every sentence adds value.

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

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

Given no output schema, description fully explains return data (financial metrics for companies, adverse events/approvals/trials for drugs), sorting by primary metric, and citation URIs. Complete for both entity types.

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

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

Schema coverage is 100%, but description enriches both parameters: explains what each 'type' fetches and gives concrete examples for 'values' (tickers/CIKs for company, drug names).

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

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

The description clearly states the tool compares 2-5 companies or drugs side by side, specifying exact data fetched per type and distinguishing it from single-entity tools like 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?

Explicitly lists use cases: 'compare X and Y', 'vs', 'which is bigger', and rank-by-metric. Also implies not for single-entity queries by focusing on 2-5 entities.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it returns top-N relevant tools with full schemas and examples, ready to call directly. 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 concise, with the main purpose in the first sentence. It uses bullet-like lists in plain text and front-loads key usage guidance. Every sentence adds value.

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

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

Given the tool's complexity (6 params, no output schema), the description adequately explains what is returned (names, descriptions, schemas with examples). It could mention error handling or rate limits, but it's sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds value by explaining that 'query' accepts aliases (task, q, description, search) and that 'limit' defaults to 20 (max 50). This enriches the schema information.

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 lists numerous examples of use cases, making it specific and distinguishable from sibling tools (which are specific tools, not a discovery mechanism).

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

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

Explicit instruction to 'Call this FIRST when you have many tools available and want to see the option set.' This clearly indicates when to use. No explicit when-not-to-use, but the guidance is strong enough.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it lists exactly what is returned (cik, company_name, recent_filings with URIs, fundamentals with a note about data freshness, patents with sunset warning, news fallback, LEI). It discloses soft-failures and data source limitations, going 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 front-loaded with the main purpose and then provides detailed return information and usage notes. While it is relatively long, every sentence adds value. It could be slightly more concise but is well-structured and readable.

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

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

Given the complexity of the tool (aggregating data from multiple sources) and the lack of an output schema, the description thoroughly explains what the tool returns, including potential limitations (patents sunset, fundamentals note, GDELT→GNews fallback). It also addresses input constraints (names not supported) and provides a usage example. This makes it very complete for an AI agent.

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

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

Schema description coverage is 100%; the description for 'value' in the schema already specifies 'Ticker (e.g., "AAPL") or zero-padded CIK (e.g., "0000320193"). Names not supported.' The main description repeats this but adds no new parameter-level meaning beyond the schema. Hence baseline 3.

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

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

The description clearly states the tool's purpose: 'Get everything about a US public company in one call.' It uses a specific verb ('get') and resource ('everything about a US public company'). It also distinguishes from sibling tools by noting it replaces 10+ pack tools.

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

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

The description explicitly tells when to use this tool: 'Use when a user asks "tell me about X", "research Acme", "brief me on Tesla"...' It also gives guidance on when not to use it: 'names not supported (use resolve_entity first).' This provides clear context and alternatives.

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

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

Annotations already indicate destructiveHint=true, and the description reinforces this by describing deletion. It adds value by specifying scenarios like clearing 'sensitive data,' which provides behavioral context beyond the annotations.

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

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

The description is two sentences, front-loaded with purpose, and every sentence adds value. No unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and behavioral context. It is complete and informative.

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

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

The input schema has 100% coverage with a clear description for the 'key' parameter. The description does not add new information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the verb (delete) and resource (memory). This distinguishes it from sibling tools like 'remember' and 'recall,' which involve storage or retrieval.

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

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

The description provides explicit guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall,' offering clear context for when to use this tool versus alternatives.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds that it fetches the page, extracts title/description/key links, and emits standard markdown format, providing context beyond annotations.

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

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

The description is a single efficient paragraph, front-loaded with purpose, and every sentence adds value. 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, clear schema, and annotation coverage, the description sufficiently covers input, process, output, and use cases. It is complete for effective tool selection and invocation.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema. The description adds no extra meaning beyond this, meeting the baseline for parameter semantics.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the output format and purpose. It distinguishes itself from sibling tools by focusing on a specific standard output for AI crawlers.

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 specific use cases: indexing a client's site, drafting for own project, auditing competitor visibility. It provides clear context on when to use, though it does not explicitly mention when not to use.

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

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

Annotations already declare readOnly, idempotent, etc. Description adds context about the specific returned fields (rating, price, hours, etc.), which is useful beyond annotations.

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

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

Two sentences, no wasted words, front-loaded with main purpose. Efficient and easy to parse.

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

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

No output schema, but description lists key return fields. With annotations covering safety, this is fairly complete for a simple retrieval tool.

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

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

Schema has 100% coverage with good descriptions for both parameters. Description only adds an example usage, not additional semantics. 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?

Clearly states the tool gets full details for a single business by id or alias, and lists specific return fields (rating, review count, etc.). Distinguishes from siblings like search_businesses which searches lists.

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 a concrete example and mentions the required parameter, but does not explicitly state when to use this tool vs alternatives (e.g., search_businesses for multiple results). The hint is clear but lacks exclusion 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 readOnlyHint, openWorldHint, idempotentHint. Description adds return fields but does not disclose rate limits, auth needs, or error behavior beyond the _apiKey parameter hint.

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

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

Two sentences plus an example, front-loaded with purpose, no superfluous text. Efficient and clear.

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

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

Adequate for a read-only tool with 4 parameters and no output schema. Lists return fields and provides example, though no output structure details beyond field names.

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. The tool description adds an example but does not significantly expand on parameter 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?

Clear verb 'get', specific resource 'reviews', scope 'recent for a business', and output fields listed. Distinguishes from siblings by focusing on reviews rather than business details or search.

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

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

Provides an example but no explicit guidance on when to use this tool versus alternatives like search_businesses or get_business. Context is implied but not fully specified.

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

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

Beyond the annotations (which only set readOnlyHint, etc., to false), the description adds valuable behavioral context: the team reads digests daily, feedback directly affects roadmap, rate-limited to 5 per identifier per day, and it doesn't count against the tool-call quota. This fully discloses the tool's non-obvious behaviors.

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

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

The description is a single, well-organized paragraph that front-loads the purpose, then provides usage instructions, and ends with behavioral notes. Every sentence adds value and there is no redundancy or unnecessary detail.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description covers all necessary aspects: purpose, when to use, behavioral notes, and guidelines. The schema covers parameter details fully, and the description fills in the usage context completely.

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

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

The input schema has 100% coverage with descriptions for all three parameters, so the baseline is 3. The description does not add new meaning beyond the schema's descriptions; it provides overall context but not per-parameter details. Hence, 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: to tell the Pipeworx team about bugs, feature requests, data gaps, or praise. It uses a specific verb ('Tell') and identifies the resource ('Pipeworx team'), and the enumerated types (bug, feature, data_gap, praise, other) distinguish it from sibling tools that serve different functions.

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

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

The description explicitly tells when to use the tool (e.g., when a tool returns wrong data for bug, when a tool is missing for feature/data_gap, or for praise) and what not to do (don't paste end-user prompts, describe in terms of Pipeworx tools/packs). It also notes rate limits (5 per identifier per day) and that it's free, providing clear context for use.

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

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

Beyond annotations (readOnlyHint, openWorldHint), the description adds valuable behavioral details: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and aggregated signal derivation. This fully informs the agent of the tool's operational characteristics.

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

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

The description is tightly written with three sentences and a bullet list, front-loading the key purpose and use cases. Every sentence adds value, making it highly concise 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 low parameter count, no output schema, and comprehensive annotations, the description fully covers what the tool returns, how it works, caching, and privacy considerations. It is complete for an agent to correctly invoke the tool.

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

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

The single parameter 'window' is well-described in the schema with enum values. The description adds context on interpreting shorter vs longer windows, enhancing the semantic meaning beyond the schema alone.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a specified window, distinguishing it from sibling tools like 'discover_tools' or 'ask_pipeworx' by focusing on aggregated trending data from other AI agents.

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

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

Three explicit use cases are provided, offering clear guidance on when to use the tool (e.g., discovering hot data sources, confirming canonical choices). However, it does not explicitly state when not to use it or name alternatives, which would further enhance guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail: Jaccard similarity threshold (>=0.30), partition filter (placeholder fraction >20% returns null), gap threshold (>3pp), and response structure. 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 the core purpose and two modes, then systematically details each mode. Every sentence contributes unique information without redundancy. For the complexity of the tool, it is appropriately concise.

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

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

Given no output schema, the description fully explains the response structure (opportunities[] with gap_pp, suggested_trade, reasoning, and partition_check). Combined with annotations, all necessary context for an AI agent to correctly invoke and interpret results is present.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema, especially for 'topic': it explains the cross-event search and semantic anchor. The schema's brief descriptions are enhanced by the tool's operational 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It details two explicit modes ('event' and 'topic'), distinguishing itself from sibling tools like polymarket_edges and polymarket_kalshi_spread.

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

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

The description provides clear context for when to use each mode (event slug vs. topic seed question) and explains cross-event mode catches patterns that single-event misses. It does not explicitly state when not to use or list alternatives, but the guidance is sufficiently clear for an AI agent.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, etc. The description goes far beyond: it details three model segments, response structure (by_segment), edge components (edge_pp_net, kelly_fraction), a 24h-move warning, and caching at KV level. It also explains why Fed bets are unreliable without paid data. 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 quite long (multiple paragraphs) but well-structured with segments and bullet-like lists. It front-loads the purpose but then dives into dense technical detail. While all content is relevant, some agents might find it overwhelming; conciseness could be improved.

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

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

Given the complexity (9 parameters, no output schema), the description is exceptionally complete: it explains the response top-level structure, caching, edge calculations, filter knobs, and diagnostics for empty segments. Without an output schema, it fully compensates by detailing the output format.

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

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

Schema covers all 9 parameters (100% coverage). The description adds value by explaining tradeable-edge knobs (min_liquidity, max_spread_pp) and min_partition_leg_kelly in a way that clarifies when to use them beyond the schema's descriptions.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the purpose as 'what should I bet on today' and distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement. The verb 'scan' and resource 'Polymarket markets' are explicit.

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

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

The description provides robust usage context: it helps agents discover opportunities without paging hundreds of markets, explains tradeable-edge knobs (min_liquidity, max_spread_pp), and notes exclusions (Fed bets excluded from ranking). However, it does not explicitly compare to sibling tools like polymarket_arbitrage to guide selection.

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

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

Annotations indicate read-only, idempotent, open-world hints. The description adds extensive behavioral detail: two operational modes, response structure (leg-by-leg prices, spread in pp), safety fields (compatibility_warning, temporal_alignment), and counters for skipped comparisons. No contradiction with annotations.

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

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

The description is long but well-structured: begins with purpose, then modes, response format, and special cases. Every sentence adds necessary detail. Slightly verbose but 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?

Without an output schema, the description fully explains the return format (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross_type counters) and covers edge cases like matched_pairs:0 scenarios. This makes the tool self-contained for an AI agent.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining the interplay: topic auto-maps, explicit tickers/slugs override, and lists all pre-mapped topics. It also clarifies that kalshi_event_ticker and polymarket_event_slug can be used together without topic.

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 specifies the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It clearly outlines two modes (topic shortcuts and explicit pairings) and details the response shape, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explains when to use the tool (to find spread opportunities) and warns that many pre-mapped topics currently return compatibility warnings, thus not always tradeable. It could explicitly mention alternatives but provides strong context on limitations.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping by identifier and behavior when key is omitted, enhancing transparency.

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

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

Multi-sentence but efficiently front-loads purpose and key behaviors without unnecessary verbosity.

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 explains return as value or list of keys, and mentions scoping. Could detail error handling for missing keys, but overall 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% with clear description. Description adds context by giving examples of what keys represent and reiterating omission behavior.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, with examples (target ticker, address, research notes) 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?

Explicitly states when to use (to look up stored context without re-deriving) and pairs with remember/forget, but does not specify when not to use.

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

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

Discloses fan-out parallel calls to multiple sources, fallback behavior (GDELT→GNews), and soft-fail for USPTO, plus return format. Exceeds annotation hints with concrete behavioral details.

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

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

Well-structured with purpose first, then source details, parameter usage, return format, and sibling comparison. Slightly verbose but information-dense.

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?

Completely covers input format, multi-source behavior, fallbacks, output structure, and relationship to sibling tool, all without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds example values for 'since' and clarifies 'type' restriction, but does not significantly extend parameter meaning beyond schema.

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

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

Clearly states it retrieves recent changes for a company within a time window, provides example queries, and distinguishes from sibling tool 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?

Explains when to use (change monitoring) and when not (use entity_profile for static profile), but does not enumerate other 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?

Annotations already provide idempotentHint=true and destructiveHint=false. Description adds value by explaining key-value storage, scoping by identifier, persistence differences (authenticated vs anonymous), and pairing with recall/forget. 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?

Four sentences, each purposeful. First states purpose, second usage, third technical details, fourth pairing with siblings. Efficient and front-loaded.

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

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

For a simple key-value store tool with no output schema, the description covers usage, scope, persistence, and relationships with sibling tools. Complete for the complexity level.

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

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

Schema covers both parameters with descriptions at 100% coverage. Description adds examples of key naming conventions and that value is any text, but does not significantly enhance beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, with specific examples like resolved tickers and user preferences. It distinguishes from sibling tools by naming 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?

Explicitly says when to use (when discovering something worth carrying forward) and pairs with recall/forget for retrieval/deletion. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: it 'cascades through several lookup endpoints internally' and replaces manual lookups. For each type, it details the exact return fields (e.g., ticker, CIK, citation URI for company). 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 front-loaded with the core purpose and usage directive. The structure is logical: purpose, when to use, then detailed type descriptions. It is informative without being verbose, though minor redundancy exists (e.g., 'SUPPORTED TYPES' and bullet-like format).

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 what the tool does, when to use it, inputs and outputs for each type, and internal behavior. There is no output schema, so the description compensates by detailing return values. However, it does not address error handling or edge cases, and no mention of rate limits or prerequisites. Still, it is fairly complete for its 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?

The schema already covers parameters with enums and descriptions, achieving 100% coverage. The description adds semantic value by explaining that for company, it accepts ticker, CIK, or name and returns specific fields including a citation URI. For drug, it explains input and output similarly. This enriches 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 resolves user-spoken names to canonical identifiers needed by other tools. It specifies supported types (company, drug) and what identifiers are returned, making it easy to distinguish from siblings. The phrase 'Use FIRST when you have a name but need an ID' explicitly guides when to use it.

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 clear usage condition: 'Use FIRST when you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups, implying efficiency. It does not explicitly state when not to use, but the condition is strong enough to guide correct 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context about probing each entity, ranking, and returning scores/confidence/signal density, which aligns with annotations. 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 two efficient sentences with a relevant example quote. It is front-loaded with the purpose and includes key details without fluff. Every sentence adds value.

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

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

Despite no output schema, the description adequately covers the return format (ranked list with score, confidence, signal density). It explains the process and usage context, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema, particularly that the first entity in the array is treated as the subject for narrative. The parameter descriptions in the schema are adequate but the tool description clarifies ordering.

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 (compare), resource (AI visibility), and scope (side-by-side multiple entities). It distinguishes from sibling tools like ai_visibility_check by focusing on comparison and ranking.

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 clear use case (competitive AI-marketing audits) and an example question. It implicitly tells when to use this tool instead of a single-entity check, though it does not explicitly mention alternatives 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, confirming safe read operation. Description adds valuable behavioral details: fans out to two services, partial degradation with timing (5-30s for new version bundlephobia measurement), and return structure (summary block, advisory details, links, versions). 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 somewhat long (around 150 words) but every sentence adds necessary detail. It is front-loaded with the main purpose and usage, then covers behavioral details and limitations. Minor improvements could tighten phrasing, but overall it is well-structured.

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

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

Given no output schema, the description thoroughly explains return values: summary block fields (is_latest, license, published_at, etc.), per-advisory detail, links, and alternative versions. Also addresses error handling (partial failures, timing issues). Covers all necessary context for agent usage.

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

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

Schema coverage is 100%, so schema already documents both parameters well. Description adds context: scoped packages (e.g., '@types/node') are accepted, and version defaults to latest when omitted. This extra nuance justifies a 4, though the schema covers the core semantics.

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

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

The description clearly defines the tool as a composite check for npm packages, fanning out to deps.dev and bundlephobia to evaluate safety, popularity, and size. It uses specific verbs ('scan', 'check') and distinguishes itself from sibling tools, none of which target npm dependency analysis.

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

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

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. Also provides exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving clear alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds context about using the Yelp API and the optional _apiKey parameter, 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?

Two sentences plus an example, front-loaded with main purpose. No unnecessary words.

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

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

The description covers the main purpose and returned fields, but lacks details on pagination or result limits. Annotations cover idempotency and read-only. Overall adequate for the complexity.

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

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

Schema coverage is 100% with each parameter described. The description does not add new meaning; it only gives an example. 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 searches for local businesses and restaurants on Yelp by term and location, listing returned fields. It is distinct from siblings like get_business and get_reviews.

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 an example but no explicit guidance on when to use this tool versus alternatives like get_business for detailed info or get_reviews for reviews. Usage context is only implied.

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

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

The description discloses behavioral traits beyond annotations, such as using SEC EDGAR+XBRL, returning specific verdict types (confirmed, approximately_correct, etc.), providing citations, and replacing multiple sequential calls. Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds valuable context.

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

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

The description is concise, with no redundant sentences. It front-loads the core purpose, then provides usage guidance, scope, and return information in an efficient manner.

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 (one parameter, no output schema, but detailed annotations), the description fully covers what the agent needs: what it does, when to use it, what it returns, and its limitations. The information is sufficient for correct 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?

Only one parameter exists with a schema description. The tool description enhances this by clarifying that the claim should be a natural-language factual statement and provides examples. Since schema coverage is 100%, baseline is 3, but the extra examples and context justify a 4.

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

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

The description clearly states the tool's purpose: to fact-check, verify, validate, or confirm/refute a factual claim. It specifies the domain (company-financial claims via SEC EDGAR+XBRL) and distinguishes itself from sibling tools by offering a specific verification function not provided by others.

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 when to use the tool: when an agent needs to check whether something a user said is true, with example queries provided. While it does not explicitly state when not to use it or list alternatives, the context makes it clear that it is specialized for financial claims about public US companies.

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