Foodish

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavior: probes multiple models, scores 0-100, returns per-model details and combined view. It also notes that using Anthropic incurs direct costs. No contradiction.

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

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

The description is tightly written with no filler. The core purpose is in the first sentence, and each subsequent sentence adds distinct value (default model, optional Anthropic, return structure, use cases).

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 params, no output schema, good annotations), the description covers what it does, what it returns (per-model and combined view), and usage conditions. No gaps remain 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 adds clarifying examples for the context parameter and explains the _apiKey purpose. This adds moderate value beyond the schema, though the schema already adequately describes each parameter.

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

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

The description states the specific verb 'probe' and the resource 'LLMs for what they know about an entity', producing a visibility score (0-100). It clearly differentiates from sibling tools like ask_pipeworx (single AI query) and scan_competitor_ai_presence (competitor focus).

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: default model is free, optional Anthropic probing requires a BYO key, and it's useful for AI-marketing audits, pre-launch brand checks, and competitive monitoring. It does not explicitly state when not to use, but the context is sufficient.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds valuable context: it routes to 3,745 tools, fills arguments, returns citations (pipeworx:// URIs). No contradictions.

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

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

Description is front-loaded with the key instruction, followed by domains, behavior, and examples. Every sentence adds value, though slightly longer than necessary. Structurally sound.

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, rich annotations, and no output schema, the description fully explains purpose, usage, and output format. Provides sufficient context for an agent to invoke correctly.

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

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

Schema coverage is 100% with clear descriptions for the 'question' parameter and its aliases. The description provides example questions but does not add new semantic details 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 routes questions to a large set of authoritative sources for factual data, with examples. It distinguishes itself from web search and siblings like 'ask_pipeworx_grounded' by specifying its broad coverage and citation output.

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 'PREFER OVER WEB SEARCH' for many domains, lists query types and example phrasings, and gives concrete use cases. No guidance needed beyond this.

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. Description adds major behavioral context: costs one extra LLM call, returns explicit refusals with structured reasons, and describes response format. 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 packed with useful info but somewhat long. Front-loads key purpose. Every sentence adds value, but structure could be tighter (e.g., bullets for refusal reasons). Still efficient.

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

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

Given no output schema, description fully covers return structure ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and all possible refusal reasons. Covers behavior, use cases, and cost trade-offs. Complete for a complex tool.

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

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

Schema has 6 parameters with 100% coverage (all aliases described). Description adds context that the tool automatically fills arguments, but doesn't elaborate on parameter values beyond schema. Schema suffices; description adds marginal value.

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

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

Description clearly states it's a 'hallucination-resistant answer mode for high-stakes reads' with verb+resource+behavior. It distinguishes from sibling ask_pipeworx (casual lookups) and specifies exact use cases like financial verdicts, legal claims.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds substantial behavioral context: low-confidence short-circuits, closed market handling, resolution-rule risk parsing, news fallback mechanisms, and liquidity notes. These go well beyond the structured annotations, fully covering behavioral traits.

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

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

The description is very long and dense, but front-loaded with the core purpose. While every sentence adds value, it could be more structured (e.g., separating fan-out examples into bullets). The length is justified by complexity, but conciseness is slightly compromised.

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, no output schema, and rich behavior, the description covers all necessary aspects: input formats, classifiers with examples, fan-out details, response shapes, safety mechanisms, resolution rules, and news fallback. It is more than sufficient for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra meaning by explaining how inputs are resolved (slug, URL, text), how 'depth' affects fan-out (quick vs thorough), and how 'include_raw' controls response size. This adds value beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text), the process (resolves, classifies, fans out), and the output (evidence packet, comparison). This distinguishes it from siblings like polymarket_edges and validate_claim.

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 use cases are provided: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. While it does not list when not to use, the description is comprehensive enough for an agent to infer appropriate contexts. It lacks direct differentiation from similar siblings but still offers clear 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, and results sorted by primary metric. 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 information-dense but slightly long. However, it is well-structured with front-loaded core purpose and logical detail flow. Every sentence adds value, but minor trimming could improve conciseness.

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

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

Given 2 parameters, no output schema, and rich annotations, the description fully covers what the tool returns (paired data plus citation URIs) and how it works. It addresses edge cases like off-calendar fiscal years and lists specific metrics. No gaps evident.

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 greatly enriches parameter meaning by detailing what each entity type returns (e.g., company: revenue, net income, cash, debt) and specifying value formats (tickers/CIKs for companies, drug names for drugs). It also reinforces the 2–5 item limit.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call. It explicitly distinguishes from sequential single-entity lookups by saying 'ALWAYS PREFER over sequential single-pack lookups', differentiating it well from siblings 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?

The description provides strong usage guidance by insisting on preference over sequential lookups and enumerating example queries such as 'X vs Y' or 'rank these companies'. It also quantifies the efficiency gain by replacing 8–15 lookups, making the tool's advantage 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?

Discloses behavior beyond annotations: expects 15-60s latency, returns a structured findings packet with verbatim evidence, confidence, source, fetched_at, and pipeworx:// citations, includes explicit gaps[] for unanswered facets, and confirms no invented facts. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is well-structured: starts with a strong summary, then details the process, usage guidance, requirements, and constraints. It is longer than minimal but every sentence adds value. Could be slightly more terse, but the structure earns a 4.

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 and the lack of an output schema, the description is remarkably complete. It explains the return format (findings packet with evidence, confidence, source, citation, gaps), the decomposition process, parallel routing, timing, and account requirements. No notable 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?

Both parameters are fully described in the schema (100% coverage). The description adds context: for 'question' it clarifies 'Broad/multi-part is fine — decomposition is the point'; for 'depth' it explains enum values (quick=3, standard=5, thorough=8) and payment requirement. This adds meaningful guidance 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.' It explains the decomposition and parallel routing across 3,745 tools. It also distinguishes from sibling 'ask_pipeworx' by specifying that this 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?

Explicitly states when to use: 'Use for broad or multi-part questions' and when not: 'use ask_pipeworx for single lookups.' Also details requirements: 'Requires a Pipeworx account' and that depth:'thorough' requires a paid plan.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N tools with schemas, which is transparent. No contradictions.

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

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

Description is front-loaded with purpose, then usage, then return details, and a recommendation. Every sentence is informative with no wasted words.

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

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

Tool has 6 parameters (5 aliases) and no output schema. Description explains what is returned but could detail output structure more. Still adequate for a discovery tool.

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

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

Schema description coverage is 100%. Description adds value by showing examples and clarifying that query accepts multiple aliases, which is helpful 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 'Find tools by describing the data or task' and lists specific domains like SEC filings, FDA drugs, etc. It distinguishes from siblings by recommending calling this FIRST to see the option set.

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

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

Explicit guidance: 'Use when you need to browse, search, look up, or discover' and 'Call this FIRST...'. Lacks explicit when-not-to-use or alternatives, but context makes usage clear.

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

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

Discloses fanning across multiple sources, patent API sunset with soft-fail behavior, and return components. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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 query examples; every sentence adds value. Slightly lengthy but justified given complexity. Could be trimmed slightly.

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?

Comprehensive for a high-complexity tool: covers inputs, outputs, limitations, prerequisites, and fallback behavior. No output schema but description sufficiently explains return fields.

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

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

Schema coverage 100% with descriptions for both parameters. Description adds examples (ticker, CIK) and clarifies name unsupported, instructing to use resolve_entity.

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

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

The description clearly states 'full cross-source profile of a US public company in ONE parallel call' with example queries. It distinguishes from chaining single-pack lookups and mentions sibling tool resolve_entity for name resolution.

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

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

Explicitly says use for holistic view, 'ALWAYS PREFER over chaining', and specifies when not to use: names not supported, use resolve_entity first.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description adds context about clearing 'sensitive data' and usage scenarios. It does not contradict annotations and enriches the behavioral understanding.

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: action, usage, related tools. No redundant words, front-loaded with primary purpose. Every sentence serves a distinct 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?

With one fully documented parameter, no output schema, and destructiveHint annotation, the description is complete. It explains the action, when to use, and related tools, covering all necessary 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 the parameter description 'Memory key to delete' is already clear. The description does not add additional semantic value beyond restating the key parameter. 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's purpose: 'Delete a previously stored memory by key.' It uses a specific verb (delete) and specific resource (memory by key), and distinguishes from siblings like 'remember' and 'recall' by explicitly naming 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?

Provides explicit usage guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also mentions pairing with alternative tools remember and recall.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context: fetches the page, extracts title/description/key links, and outputs standard markdown. It complements the annotations without contradiction, though it could mention that no changes are made to the target site.

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: purpose, process, and use cases. It is front-loaded with the main action, no redundant words, and every sentence serves a clear function.

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

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

Given no output schema, the description explains the output format (text blob ready to drop at site-root/llms.txt). Parameters are fully documented in schema, and annotations cover safety. The description is sufficient for the tool's simplicity and 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%, so the description does not need to add much. The description implies the 'url' parameter is used for fetching, but does not elaborate on 'max_links' beyond the schema. Hence, it adds minimal new meaning beyond the structured input.

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

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

The description clearly states the tool's function: generate an llms.txt file for a given URL. It specifies the verb 'generate' and the resource 'llms.txt', but does not explicitly differentiate it from sibling tools like 'scan_competitor_ai_presence', which might overlap in use.

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 explicit use cases: indexing a client's site, drafting for own project, or auditing a competitor. However, it does not mention when not to use the tool or provide alternatives, slightly reducing clarity for an AI agent deciding between tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it is safe. The description adds value by specifying the return schema fields and clarifying that it lists active subscriptions (with option to include inactive via parameter). 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 two sentences, front-loaded with the action and return fields. Every sentence is necessary and concise, with 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?

For a simple list tool with one parameter, robust annotations, and no output schema, the description fully covers what it returns and when to use it. No missing aspects for operational context.

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

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

The input schema has 100% coverage describing the optional boolean parameter 'include_inactive'. The description does not add new meaning beyond the schema; it only implicitly reinforces that 'active' is the default. Baseline 3 is appropriate given schema coverage.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count). It implicitly distinguishes from sibling tools subscribe and unsubscribe by suggesting usage before adding more subscriptions or to find an id to cancel.

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

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

The description explicitly advises when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context relative to the sibling tools subscribe and unsubscribe.

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

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

Annotations provide generic safety hints (all false), but the description adds specific behavioral details: rate-limited to 5 per identifier per day, free (no quota impact). This goes beyond the annotations and gives the agent useful operational 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 three sentences, each carrying essential information: purpose, usage guidelines, and behavioral notes. No wasted words, front-loaded with key action.

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 params, no output schema), the description covers all important aspects: what, when, how, and limitations. It could mention what happens after submission (e.g., acknowledgment), but it's adequate for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by instructing the user to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts, which is not evident from 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 specifies the verb 'Tell' and the resource 'Pipeworx team', and distinguishes from sibling tools by enumerating specific use cases (bug, feature/data_gap, praise). It leaves no ambiguity about what the tool does.

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

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

The description explicitly states when to use the tool (for bugs, missing features, praise) and what to avoid (pasting end-user prompts). It also provides guidance on describing issues in terms of Pipeworx tools/packs, making it clear how to use it effectively.

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

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

Annotations already cover readOnly, idempotent, not destructive. Description adds source (CF analytics-engine), privacy (no PII), and caching (5min-1h). 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?

Three compact sentences: purpose, usage context, technical detail. Front-loaded with key 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?

For a simple read-only tool with one optional param and no output schema, description covers return value, use cases, caching, and data source comprehensively.

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 enum description. Description mentions windows but doesn't add new semantics beyond schema's note on hot vs steady-state. Adequate but not additive.

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

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

Description clearly states it returns top tools, top packs, and call volume over a window. Unique among sibling tools, providing a specific verb (returns) and resource (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?

Explicitly lists three use cases: discovering hot data sources, confirming canonical tool, and aligning use case. Lacks explicit when-not-to-use or sibling comparisons, but context is strong.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: internal logic (monotonicity checks, partition checks), semantic anchor for similarity (≥0.30 Jaccard), partition filter for placeholder slugs, fill check against live CLOB depth with warning not to trade if realizable_edge_pp ≤ 0. 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 relatively long but well-structured. It front-loads the key requirement (must provide event or topic) and then systematically explains both modes, then details about semantic anchor, partition filter, and fill check. Every sentence adds necessary detail for a complex tool. Could be slightly more concise, but still effective.

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

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

Given the tool's complexity and no output schema, the description comprehensively explains return values: opportunities[] with fields (gap_pp, suggested_trade, reasoning, monotonicity violation context), partition_check object with fields, and fill check details. It also covers edge cases like skipped_low_similarity and placeholders_filtered. Very complete.

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

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

Schema description coverage is 100% (both parameters described), so baseline is 3. The description adds significant value beyond the schema: it explains the modes in depth, provides example values, and clarifies behavior (e.g., event mode walks child markets, topic mode searches related events). This substantial additional information justifies 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between single-event mode (event parameter) and cross-event mode (topic parameter), providing specific examples. This is a specific verb+resource with clear differentiation.

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 'REQUIRES one of `event` or `topic` — call with no args fails.' It recommends event for specific markets and topic for cross-event scanning, explaining that cross-event mode catches patterns single-event misses. It also provides error/edge case handling (e.g., skipped_low_similarity, partition filter).

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 confirm read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: caching (1h KV-level), response structure including diagnostics, edge computation methods, and conditions for emptiness. No contradiction with annotations.

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

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

The description is lengthy but well-structured with clear sections (model families, response fields, knobs). It is front-loaded with core purpose. Some redundancy exists (e.g., repeated explanation of segments), but 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?

With 9 parameters and no output schema, the description compensates fully: explains response top-level structure, diagnostics for empty segments, and edge cases like Fed bets. Provides sufficient context for an agent to understand inputs and outputs.

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

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

Schema coverage is 100% with parameter descriptions. The description adds significant value beyond schema by explaining tradeable-edge knobs, providing concrete examples (e.g., min_liquidity=5000), and detailing the role of each parameter in filtering opportunities.

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 to find edges where Pipeworx data disagrees with market price, with explicit use case 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage by focusing on Pipeworx-driven mispricing rather than cross-exchange 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?

Provides explicit context for when to use (finding betting opportunities) and details adjustable knobs. However, lacks direct comparison to sibling tools or explicit when-not-to-use guidance, though the description is self-contained enough for effective 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?

The description provides extensive behavioral context beyond annotations: explains snapshot generation on cache-miss, gaps in data, limitations like 60-day TTL, and that decay is based on daily closes not intraday. This adds significant value over the readOnlyHint and idempotentHint annotations.

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

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

The description is front-loaded with the core question and purpose. It is detailed but well-structured with 'Args:' and 'RESPONSE:' sections. Could be slightly more concise, but every sentence serves a 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 and lack of output schema, the description comprehensively explains the response structure (tracked, expired, snapshot_dates) and all relevant details including field meanings and limitations. No gaps in understanding what the tool 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% with clear descriptions for both parameters. The description adds defaults and clarifies the response based on parameters, but does not add substantially new meaning beyond what the schema already provides.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge longevity. It distinguishes itself from siblings like polymarket_edges by focusing on historical tracking rather than current edge data.

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

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

Explicitly guides when to use this tool by contrasting a fresh wide edge vs a 3-week-old wide edge, implying that this tool is for historical persistence analysis. It does not explicitly name alternatives but contextually differentiates from polymarket_edges.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds context: it walks the order book ladder, returns detailed fields like top_of_book, vwap_fill_price, slippage_pp, verdict, etc. 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 and front-loaded with purpose and mode distinction. While somewhat lengthy, every sentence contributes value given the tool's complexity. Could be slightly more concise but justified.

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, many return fields, integration with other tools), the description covers all needed aspects: mode differentiation, parameter interpretation, return values, usage context, and risk warnings. Complete 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%, but the description adds significant meaning: clarifies size_usd semantics per mode, default values, clamping range, and explains side auto-detection in basket mode. Goes well beyond what the schema provides.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live order-book depth, explicitly distinguishes between single-market and basket modes, and lists specific return values. It differentiates itself from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises to use before acting on polymarket_arbitrage signals or trades above ~$500. Warns about thin books and partial basket fills converting arbs into unhedged directional positions, providing clear when-to-use and when-not-to-use guidance.

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

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

The description goes well beyond annotations (readOnlyHint, etc.) by detailing compatibility_warning triggers, temporal alignment, skipped_cross_type/subtype counters, and the fact that most pre-mapped topics are not tradeable. 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 somewhat lengthy but well-structured with clear sections (intro, modes, response, safety fields). Every sentence adds useful information, though it could be slightly more terse without losing meaning.

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

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

Despite lacking an output schema, the description provides a thorough account of the response structure: each venue's prices, spread list, compatibility_warning, temporal_alignment, and skipped counters. This is fully adequate for an agent to understand what to expect.

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

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

All three parameters are described in the input schema with 100% coverage. The description adds value by explaining the two modes, providing examples, and clarifying that explicit parameters override topic-mapped sides. Schema examples reinforce usage.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with two modes (topic shortcuts and explicit tickers). It differentiates from sibling tools like polymarket_arbitrage by focusing on specific venue pairs and compatibility checks.

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 real cross-venue spreads) and provides cautionary notes that most pre-mapped topics return compatibility warnings. However, it lacks explicit guidance on when not to use or direct alternatives, though context implies using explicit mode for custom pairs.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds that it returns a URL, but this is likely evident from output schema. Minimal additional behavioral context.

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

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

Single sentence, no fluff, directly conveys functionality.

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

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

With no parameters, comprehensive annotations, and an output schema, the description is complete for an agent to use correctly.

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

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

No parameters defined; baseline score of 4 applies. Description is sufficient given zero parameters.

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

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

Description states it returns a random food image URL, which is clear and specific. The sibling 'random_by_category' suggests category-based randomness, distinguishing this tool as unconstrained.

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

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

No explicit guidance on when to use this tool versus alternatives like 'random_by_category'. The context implies general random image retrieval, but lacks exclusionary 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds no additional behavioral details (e.g., response format, size limits, caching behavior) beyond stating it returns a 'random image'.

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, concise sentence. It lacks structure (e.g., bullet points) but is appropriately short for a simple tool. However, it sacrifices substance for brevity.

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

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

Given the tool's simplicity, the description is barely adequate. The output schema likely details the return format, but the description does not set expectations about image URLs, file types, or randomness behavior. Annotations compensate for safety but not for usage context.

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

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

The parameter 'category' is documented only by its enum values in the schema (0% schema description coverage). The description says 'Random image for category' but does not explain that the categories represent food dishes or how the image is selected. The meaning is inferred from the enum but insufficiently clarified.

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 'Random image for category' combined with the tool name and input schema (which includes a 'category' parameter with food-related enum values) clearly indicates the tool returns a random image for a given food category. However, it does not explicitly differentiate from the sibling 'random' tool or specify the image type.

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

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

No guidance is provided on when to use this tool versus siblings like 'random' (which likely returns a random image without category filtering) or other tools. The description lacks context on suitable use cases, prerequisites, 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 indicate readOnlyHint=true and idempotentHint=true, so the description adds value by explaining scoping to user identifier and the dual behavior (single key retrieval vs. listing all keys). 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 with two sentences, front-loaded with the primary purpose, followed by usage guidance and pairing with sibling tools. 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?

Given the tool's low complexity (one optional parameter, no output schema, clear annotations), the description covers the essential aspects: purpose, usage context, parameter behavior, and scoping. However, it does not describe the return format, which could be helpful 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% for the single parameter 'key'. The description adds meaning by explaining that omitting the key lists all saved keys, which goes beyond the schema description. This enhances the agent's understanding of parameter 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?

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb (retrieve/list) and resource (saved values/keys), and distinguishes from sibling tools 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?

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions scoping and pairing with remember/forget, providing clear context for usage, though it does not explicitly state when not to use it.

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

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

Beyond annotations (readOnly, idempotent, not destructive), the description discloses that mark_read:true flags events as read, affecting subsequent calls, and that polls are safe. It also details the output fields (source, citation_uri, raw payload). 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 4 sentences, front-loaded with the main purpose, then progressively details output, filtering, side effects, and alternatives. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description covers expected return fields (source, citation_uri, raw payload). It addresses polling behavior and provides an equivalent REST endpoint. Minor gaps: no mention of pagination or error handling, but adequate for a simple read-only feed tool.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds value by giving an example for type ('sec_8k') and explaining the effect of mark_read ('so the next call only shows newer ones'). It does not significantly expand on limit or unread_only 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 'Pull fired events from your subscription feed', specifying the verb (Pull), resource (fired events from subscription feed), and output details (source, citation_uri, raw payload). It distinguishes itself from sibling tools like list_subscriptions and subscribe/unsubscribe by focusing on reading fired alerts, not managing 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?

The description provides usage context: filtering by type and since, setting mark_read to control read state, and notes that polling works fine. It also offers an alternative access method (GET endpoint). However, it does not explicitly state when to avoid this tool in favor of a sibling, leaving some judgment to the 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?

The description details the tool's behavior: fanning out to multiple APIs, fallback logic (GDELT to GNews), and soft-failure for patents. This goes beyond the annotations which only declare idempotent, read-only, and non-destructive hints.

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 usage patterns first, then functional details. It is moderately long but every sentence provides value, though slightly verbose with repeated examples.

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

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

For a tool with three required parameters, no output schema, and moderate complexity (multiple data sources, date parsing), the description covers all key aspects: input formats, data sources, fallback behavior, and return structure. It 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?

All three parameters are described in the schema. The description adds value by explaining the 'since' parameter with examples ('7d', '30d', '3m', '1y') and ISO dates, and confirms that 'type' only supports 'company'.

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

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

The description clearly states the tool provides a change feed for a company, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO). It uses specific verbs and distinguishes from the 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?

The description provides explicit usage examples like 'What's new with X' and 'updates on Acme'. It directs users to 'entity_profile' for static profiles, effectively guiding when to use this tool vs 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 provide idempotentHint=true and destructiveHint=false. The description adds meaningful context: key-value scoping by identifier, persistence differences for authenticated vs. anonymous, and 24-hour retention. 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 appropriately sized, front-loading the main purpose, and structured with use case and pairing information. Some redundancy could be trimmed but overall efficient.

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

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

Given the tool's simplicity and rich schema, the description covers key aspects: purpose, when to use, retention behavior, and pairing. No output schema needed, and context signals complete the picture.

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

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

Schema coverage is 100% with well-described properties. The description adds context about the key-value pattern and example usage, enhancing 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 saves data for later reuse, using specific verbs like 'Save' and naming the resource as data for later use. It distinguishes from sibling tools by mentioning pairing with recall and forget.

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

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

The description provides clear when-to-use guidance (discover something worth carrying forward) and explicitly names alternatives (recall, forget). It lacks explicit when-not-to-use but is otherwise strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds that each call cascades through several lookup endpoints, replacing 2-3 manual lookups, which provides useful internal behavior 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 front-loaded with examples and usage guidance. Every sentence adds value, though it is slightly lengthy. Well-structured and informative.

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

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

Given 2 params, no output schema, and comprehensive annotations, the description fully covers tool behavior: examples, supported types, return values, and usage context. 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%, baseline 3. Description adds significant meaning: for 'company' type it lists returned fields and auto-disambiguation, for 'drug' type it lists returned fields and accepts brand/generic. Goes well 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 uses specific verbs ('resolve', 'look up') and resources ('name to canonical identifier') with clear examples for each supported type. It distinguishes from siblings by being the primary name-to-ID 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 'Use FIRST whenever you have a name but need an ID', providing strong when-to-use guidance. Lacks explicit when-not-to-use or alternatives, but the directive is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and not destructive. The description adds context: it probes each entity with ai_visibility_check, ranks results, and outputs a list with score, confidence, signal density. No contradictions found.

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, front-loaded with the main action, and every sentence adds value. No wasted words.

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

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

Given the complexity (multi-entity, ranking, calling another tool) and no output schema, the description adequately explains the process and output format. It could mention performance considerations or limits, but overall sufficient.

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

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

Schema coverage is 100% and already describes each parameter, including the special role of the first entity. The description reinforces this but doesn't add new semantic meaning 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's function: 'Compare AI visibility across multiple entities side-by-side.' It uses a specific verb+resource (compare/scan AI presence). It distinguishes itself from the sibling tool 'ai_visibility_check' by focusing on multi-entity 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 explicitly says 'Useful for competitive AI-marketing audits' and provides an example question. It implies this tool is for comparing multiple entities, distinguishing it from single-entity checks. It could be improved by explicitly stating when not to use, but it's 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 readOnlyHint, idempotentHint, and non-destructive. Description adds significant behavioral context: fans out to two external services, graceful degradation on partial failure, bundlephobia timeouts (5-30s), and sources_failed field. Provides transparency 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?

Single paragraph is dense but non-redundant. Front-loads composite purpose and key use. Every sentence adds information. Could be more structured, but effective 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?

No output schema, yet description thoroughly explains return fields (summary block, advisories, links, alternative versions) and failure behavior (sources_failed). Covers all necessary context for agent to use tool correctly.

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

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

Schema coverage is 100% with full descriptions. Description adds minor value (e.g., scoped packages accepted), but does not substantially improve parameter understanding beyond schema. Baseline 3 with no significant addition.

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

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

Description starts with a clear composite purpose: checking if an npm package is safe/popular/small by aggregating data from deps.dev and bundlephobia. It explicitly states the NPM ecosystem scope and contrasts with broader deps.dev usage, distinguishing from sibling 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?

Provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also states ecosystem limitation and fallback for other ecosystems, giving clear context for tool selection.

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

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

The description goes beyond annotations by detailing the underlying embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), and character limit (200K chars with truncation flag). Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, and the description adds valuable behavioral context.

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

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

The description is concise and well-structured. It front-loads the main action, then provides technical details. Every sentence adds value without redundancy, and the length is appropriate for the complexity of the tool.

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

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

Given the absence of an output schema, the description adequately explains the return types (passages with character offsets and similarity scores). It also covers edge cases like truncation. With only three parameters and straightforward behavior, the description provides complete contextual information.

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 context like example queries and truncation behavior, but does not significantly enhance meaning beyond the schema's parameter descriptions. It reinforces the purpose but does not introduce new semantic detail.

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 semantic search inside a fetched record, specifying the input (text and query) and output (passages with offsets and scores). It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining its role as a preliminary step for grounding.

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 this tool: when the record is too large for the prompt, to save context. It also mentions pairing with ask_pipeworx_grounded, providing clear context. However, it does not explicitly state when not to use or list alternatives beyond the paired tool.

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

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

Annotations already indicate readOnlyHint=false and openWorldHint=true, so the description need not restate that. It adds value by detailing auth requirements, delivery channel caps (10/day for SMS), and webhook auto-disable after 10 failures. Idempotency is hinted but not clarified; 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 fairly concise given the complexity, with good front-loading of purpose. Some redundancy exists with schema descriptions, but overall structure is logical and efficient for an agent.

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

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

For a tool with 3 params, nested objects, 5 enum types, and no output schema, the description covers all critical aspects: subscription types, their parameters, delivery options, and limitations. It is sufficient 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%, baseline 3. The description adds meaning by explaining the delivery object in detail, including webhook signing secret and auto-disable behavior, and provides concrete examples for each subscription type's params, which exceeds schema documentation.

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 creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It uses specific verbs and resources, and distinguishes from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

The description provides clear context for when to use the tool, including prerequisite account requirements and limitations for anonymous/BYO users. It lists supported subscription types and their parameters, but does not explicitly state when not to use or compare with 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?

Description adds significant context beyond annotations: it specifies the output format (category-bucketed questions with tool+argument shape), the data source (live catalog), and the non-destructive, idempotent nature. 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 longer than typical but every sentence adds value, covering purpose, usage, and output. It is front-loaded with the core purpose. Minor redundancy ('what can you do?' and 'getting started' could be combined).

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 single optional parameter and no output schema, the description fully explains what the tool returns, how to use it, and when to use it. No gaps remain.

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

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

Schema coverage is 100%, and the description adds value by explaining the behavior with no arguments (full spread) vs. with a topic (focused), and provides concrete topic examples.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with exact tool arguments. It distinguishes itself from sibling tools by being the first tool to use and by contrasting with meta-tools like ask_pipeworx.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass a topic vs. omit. It does not explicitly list exclusions or alternatives, but the context is clear enough.

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

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

Annotations indicate the tool is mutating (readOnlyHint=false), idempotent (idempotentHint=true), and not destructive (destructiveHint=false). The description adds critical behavioral context: ownership enforcement and soft-deletion (deactivated not deleted), explaining that historical events remain available. 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?

Two sentences, each serving a distinct purpose: the first states the action and ownership constraint, the second explains the soft-delete behavior and link to historical data. No redundant or irrelevant 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 one parameter and no output schema; the description covers the action, constraints, and side effects. It mentions ownership and soft-deletion, addressing the key context. A brief note on return values (e.g., success confirmation) would improve completeness but is not essential given the simplicity.

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 parameter 'id' is described as 'Subscription id (uuid) returned by subscribe.' The description mentions 'by id' but adds no further semantic detail. The baseline is 3 due to high schema coverage, and the description provides minimal 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?

The description clearly states the action ('Cancel a subscription by id'), specifies the resource (subscription), and highlights key constraints (ownership enforced). It effectively distinguishes the tool from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly states that ownership is enforced, guiding when and by whom the tool should be used. It also mentions that the row is deactivated, not deleted, and historical events remain via 'recent_alerts', providing context for alternative actions. However, it lacks explicit statements about when not to use it (e.g., for permanent deletion).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds significant behavioral context: returns a verdict (confirmed/approximately_correct/refuted/inconclusive/unsupported), structured form, actual value with citation, and percent delta. Also notes it replaces 4–6 sequential calls. No contradictions with annotations.

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

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

Description is well-structured with trigger phrases first, then a detailed explanation of what the tool does and returns. It is somewhat lengthy but every sentence adds value. Could be slightly more concise, but front-loading and organized structure earn a high score.

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

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

Given the tool has only one parameter and no output schema, the description provides complete context: the types of claims supported (company-financial), data sources (SEC EDGAR + XBRL), return values (verdict, structured form, citation, delta), and efficiency benefit (replaces multiple calls). No missing information 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% (only one parameter 'claim'). Description adds rich meaning beyond schema: provides examples ('Apple's FY2024 revenue was $400 billion'), specifies the natural-language format, and implies the claim should be factual and precise. The schema description is already good, but the description reinforces usage.

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

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

Description clearly states it verifies natural-language factual claims against authoritative sources, with specific examples like 'Apple's FY2024 revenue was $400 billion'. It explicitly lists relevant trigger phrases ('fact check', 'verify the claim', etc.) and distinguishes from sibling tools by specifying domain (company-financial claims) and sources (SEC EDGAR + XBRL).

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 states 'Use whenever the agent needs to check whether something a user said is factually correct.' It does not provide explicit cases when not to use or alternatives, but the context of sibling tools and the specific domain coverage implies appropriate usage. A clear exclusion statement would elevate this to 5.

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