recipes

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds important behavioral details: default model is free, probing multiple models, API key requirement, and return structure. No contradictions.

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

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

The description is concise (3-4 sentences), front-loaded with action and output, and every sentence earns its place. No waste.

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

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

Given no output schema, the description explains the return shape (per-model score, confidence, signals, raw_response + combined view). It covers input, usage, and output completely for the tool's complexity.

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

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

Schema description coverage is 100%, and the description adds value by explaining purpose beyond schema: entity is brand/business/product/person/topic, context helps disambiguate, _apiKey only needed for anthropic. This provides clear semantics.

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

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

The description clearly states it probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. It specifies default model and optional Anthropic with BYO key. This is a specific verb+resource that distinguishes it from siblings like scan_competitor_ai_presence.

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

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

The description lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It implies when to use but does not explicitly state when not to use or compare to alternatives. However, the context signals help differentiate.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already indicate safe behavior. Description adds value by noting stable citation URIs, one fast call, and works on all tiers. 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 informative but lengthy. It is front-loaded with purpose, but could be more concise. Some redundancy in 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?

Given the complexity of routing to over 4,500 tools, description adequately explains behavior (citations, tier compatibility, speed). No output schema, but mentions structured answer with URIs. Sufficiently complete.

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

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

Schema coverage is 100% with aliases documented. Description does not add significant parameter details beyond examples, but baseline is 3 due to high 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 explicitly states the tool's function: answering factual questions with structured data from thousands of sources. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides clear when-to-use guidance ('PREFER OVER WEB SEARCH'), specific query types (e.g., 'what is', 'look up'), and when to step up to alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for multi-part).

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. The description adds behavioral details such as refusal reasons, evidence extraction verbatim, and the extra cost in LLM calls, providing context beyond what annotations offer.

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

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

The description is moderately long but efficiently packs critical information. It front-loads the main purpose and uses bullet-like structure for refusal reasons. A few sentences could be trimmed but overall it earns its length.

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

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

Without an output schema, the description thoroughly explains the return format including both success and failure cases, refusal reasons, and cost implications. It is complete for a complex tool with high stakes.

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

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

The input schema has 100% coverage with parameters, all being aliases for 'question'. The description does not add significant meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and specifies it extracts answers only from tool results. It distinguishes from sibling ask_pipeworx by emphasizing its grounded nature and when it is appropriate to 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?

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on... prefer ask_pipeworx for casual lookups.' This tells the agent when to use this tool versus the alternative.

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

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

The description extensively details behavior: fan-out logic, response shapes, resolver contract, parent event extractor, news fields, safety short-circuits, tradeability notes, and resolution-rule risk. It adds significant context beyond annotations (readOnlyHint, idempotentHint) without contradiction.

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

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

The description is thorough but verbose, spanning multiple paragraphs with detailed sections. While well-structured with headers and examples, it could be more concise. Every sentence adds value, but overall length reduces readability.

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

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

Given tool complexity, the description covers fan-out examples, response fields, error conditions (low confidence, closed markets, wide spreads), and resolution rules. No output schema exists, so the description compensates fully. Edge cases are well-documented.

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

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

Schema description coverage is 100%, but the description adds meaningful context: e.g., 'quick = 2-3 evidence sources, thorough = full fan-out', 'Default thorough', 'keeps responses under ~20KB' for include_raw. It enriches the schema beyond baseline.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types and outputs (evidence packet + comparison), making it highly specific and resource-oriented. While sibling differentiation is implicit, the purpose is unmistakable.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly mention when not to use or compare with siblings, but the guidance is clear and actionable.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. Description adds context: handles off-calendar fiscal years, replaces 8-15 lookups, returns citation URIs. No contradictions.

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

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

Description is slightly verbose but front-loaded with key examples and guidance. Every sentence serves a purpose, providing valuable context without redundancy.

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

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

No output schema, but description mentions 'Returns paired data + pipeworx:// citation URIs per entity.' Sufficient for understanding output. Covers edge cases like off-calendar fiscal years. Complete enough for a comparison tool.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains type values (company vs drug) and what data they pull, and clarifies that values are tickers/CIKs or drug names with min/max constraints.

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 does side-by-side comparison of 2-5 companies or drugs in one call, distinguishing from sequential lookups. It specifies what data is pulled for each type (SEC data for companies, FAERS/FDA/trial counts for drugs).

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also provides example queries and explains 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds critical behavioral context: account requirement, paid plan for thorough depth, parallel tool routing, return format (findings packet with gaps), and expected latency (15-60s). 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 dense but all sentences add value. It fronts critical info (account requirement, alternative). Slightly long but justified given the tool's complexity. Could be more concise, but overall well-structured.

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

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

For a complex research tool, the description covers prerequisites, use cases, limitations (not open-web, not for breaking news), expected output (findings packet with gaps), and timing. No output schema, but the description sufficiently explains return value.

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. The description adds semantic value explaining that 'question' should be natural language and broad, and 'depth' levels correspond to facet counts (quick=3, standard=5, thorough=8) with a paid plan note. This enriches the schema information.

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

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

The description clearly states the tool does 'grounded multi-source research across Pipeworx's 1160 structured data sources' and distinguishes it from siblings like ask_pipeworx. It specifies it decomposes questions into facets and routes to tools in parallel, making its purpose distinct and unambiguous.

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

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

Explicitly tells when to use this tool vs. alternatives: for single lookup use ask_pipeworx, for breaking news prefer ask_pipeworx, and mentions account requirements (free tier, thorough needs paid plan). This provides clear guidance for an AI agent.

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

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

Annotations indicate read-only and idempotent. Description adds that it returns top-N relevant tools with full schemas and examples, and that no second lookup is needed. 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?

Front-loaded with purpose, but the list of domains is verbose. Could be more concise while retaining necessary information.

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

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

Given no output schema, description explains the return value (names, descriptions, schemas) adequately. Covers all necessary information for a discover tool.

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

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

Schema coverage is 100%, and description merely states aliases already documented in schema. Does not add significant meaning beyond parameter descriptions.

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

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

The description clearly states it's for discovering tools by describing data or task, listing many domains. It distinguishes itself from sibling tools by being a general discovery 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 advises to call this FIRST when many tools are available and you want to see options, not just one answer. Could be more explicit about alternatives, but 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 indicate safe, read-only, idempotent behavior. Description adds valuable context: potential USPTO API sunset leading to soft-fail, fallback mechanisms (GDELT→GNews), and specific data sources. 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?

Well-structured with examples first, then functionality, inputs, and return fields. Slightly verbose due to detailing all return fields, but front-loaded and clear. Earns its length.

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

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

No output schema, so description must detail return format. It does so comprehensively: fields, sources, limits (e.g., up to 5 filings), and special notes (USPTO sunset). Complete for a complex tool.

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

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

Schema coverage is 100% and descriptions in schema are thorough. Description adds no new parameter semantics beyond restating schema info (e.g., type enum, value format). 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 provides a full cross-source profile of a US public company in one parallel call, with concrete examples. It differentiates from sibling tools like resolve_entity by specifying that names are not supported and that this tool should be preferred over chaining individual lookups.

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

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

Explicitly advises when to use: 'ALWAYS PREFER over chaining single-pack ... when the user asks for a holistic view.' Also provides clear input constraints: only ticker or CIK, not names, directing users to resolve_entity first if needed.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is useful but doesn't disclose further behavioral traits beyond what annotations provide.

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

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

Two sentences with zero waste. First sentence states the action, second sentence provides usage context and related tools.

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 delete tool with no output schema, the description covers what the tool does, when to use it, and related tools. Complete enough for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the schema already describes the 'key' parameter. The description mentions 'by key', matching the parameter, but does not add additional meaning beyond the schema.

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

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

The description starts with 'Delete a previously stored memory by key', which is a specific verb+resource combination. It distinguishes from sibling tools 'remember' and 'recall' by mentioning them.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Does not explicitly state when not to use, but the guidance is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds process details: fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown. This goes beyond the annotations by explaining the internal steps.

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: purpose, process, use cases. Front-loaded and no wasted words. Every sentence contributes value.

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

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

No output schema, but description explains the output is 'a single text blob ready to drop at site-root/llms.txt'. It covers the main behavior and use cases. Could mention error handling for invalid URLs, but overall adequate for a simple 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 both parameters described. The description mentions 'extracts title/description/key links', hinting at the role of max_links, but does not add substantive new 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 starts with a clear verb-resource pair: 'Generate a production-ready llms.txt file for any URL'. It specifies the purpose (AI crawlers) and distinguishes itself from sibling tools like 'ai_visibility_check' by focusing on the specific llms.txt output format.

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

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

The description explicitly lists three practical use cases: getting a client's site indexed, drafting for own project, or auditing competitor site. It does not provide explicit exclusion criteria or alternatives, but the context is clear enough for an agent to decide when to use this tool over siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds value by detailing the return content (ingredients, measurements, instructions), which complements annotations without contradiction.

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

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

Two sentences with no waste. First sentence states purpose and content, second gives required usage context. Efficiently front-loaded.

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

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

Given the low complexity, single parameter, and presence of output schema, the description fully covers what the agent needs: what the tool does, what parameter to provide, and what the response contains.

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

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

Schema already covers the single parameter 'id' with description and examples. The tool description adds the insight that the ID should come from search_meals or random_meal, providing meaningful context beyond the schema.

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

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

The description uses a specific verb ('Get') and resource ('recipe details'), and specifies included content ('ingredients with measurements' and 'step-by-step cooking instructions'). It also distinguishes from sibling tools by referencing search_meals and random_meal as sources for the ID.

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 tells the agent to 'Pass a meal ID from search_meals or random_meal', providing clear context for when to use this tool. It does not specify exclusions or alternatives, but the guidance is sufficient for proper usage.

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

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

Annotations already cover readOnlyHint, idempotentHint, destructiveHint. Description adds value by specifying return fields and default scope (active subscriptions only), which is helpful beyond the structured 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 only, no fluff. Purpose and usage are front-loaded. Every sentence is necessary and succinct.

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 rich annotations and full schema coverage, description covers what it returns and when to use. Lacks details on pagination or error handling, but is complete enough for a simple list tool with no required parameters.

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

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

Schema coverage is 100% with full description for the one parameter 'include_inactive'. Description adds minimal extra meaning beyond stating default behavior implied by 'active'. Baseline 3 is appropriate.

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

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

Clearly states it lists the caller's active subscriptions, returning specific fields. Distinguishes from siblings like subscribe/unsubscribe by mentioning usage for review before adding 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?

Explicitly says when to use: 'to review what you're monitoring before adding more' or 'to find an id to cancel'. Could be improved by explicitly stating when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds value by specifying the return behavior (meal names and IDs) and the intended follow-up tool ('get_meal'), which is beyond what annotations provide. No contradictions exist.

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 short sentences covering purpose, examples, return value, and usage. Every word earns its place; no redundancy or fluff.

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

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

With an output schema present, the description doesn't need to detail return structure, but it briefly mentions 'meal names and IDs' which aligns. OpenWorldHint covers unknown result volume. The description could mention that the result set may be large, but overall it is sufficient for a simple filtering 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 a parameter description 'Ingredient name to filter by'. The tool description adds concrete examples ('chicken', 'garlic', 'pasta') and implies expected ingredient formats, enhancing the schema. Baseline 3 is elevated to 4 due to these extra 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 uses a specific verb 'Find', identifies the resource 'recipes using a specific ingredient', provides clear examples ('chicken', 'garlic', 'pasta'), and distinguishes the tool by explicitly tying its output to the sibling 'get_meal'. This makes the purpose unambiguous and differentiates it from other search tools like 'search_meals' or 'random_meal'.

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 the tool returns meal names and IDs to pass to 'get_meal', implying a clear workflow. However, it does not explicitly state when NOT to use this tool (e.g., for general keyword search, use 'search_meals'). The context from sibling tools partially fills this gap, but the description itself lacks exclusion criteria.

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

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

The description discloses key behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free usage not counting against tool-call quota, and that feedback is reviewed daily. No contradictions with annotations (all false).

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. The first sentence clearly states the purpose, and subsequent sentences efficiently cover usage guidelines, constraints, and context. No unnecessary information.

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

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

For a feedback tool with no output schema, the description is complete. It covers purpose, when to use, how to phrase feedback, rate limits, and cost. The tool's simplicity does not require additional details.

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

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

The description adds significant meaning beyond the input schema by instructing users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts. With 100% schema coverage, it still provides valuable behavioral context for parameter 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's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies specific use cases (bug, feature, data_gap, praise) and distinguishes this feedback tool from sibling tools, which are primarily research and retrieval tools.

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

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

The description provides explicit when-to-use guidance: for bugs, missing features, data gaps, or praise. It also advises against pasting end-user prompts and specifies that feedback should reference Pipeworx tools/packs. Additionally, it mentions rate limits and that the tool is free, aiding correct invocation.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that data is self-aggregating, derived from CF analytics-engine, contains no PII, and cached 5min-1h. This provides context beyond the annotations without contradiction.

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

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

Two short paragraphs, front-loaded with the main action. 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?

No output schema, but description explains the return structure (top tools, top packs, total call volume) and caching behavior. For a simple read-only tool with one optional parameter, this is fully 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 covers 100% and includes descriptions for the one parameter (window). Description further explains semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds value beyond the enum list.

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 what the tool does: returns top tools, top packs, and total call volume over a recent window. It uses specific verb ('returns') and resource ('top tools, top packs, and total call volume'), differentiating it from sibling tools that answer questions or retrieve entity profiles.

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, aligning use case) and explains when to use (e.g., for current events). Distinct from siblings like ask_pipeworx and discover_tools by focusing on trending signals rather than direct Q&A or tool discovery.

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 true, and destructiveHint false. The description adds deep behavioral context: it explains the Jaccard similarity anchor, placeholder filter, fill check against live order book, and conditions for viable trades. 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 well-structured with front-loaded purpose and mode details. It is relatively long but every sentence adds value, explaining filters, response format, and edge cases. Could be slightly more concise but effectively communicates complexity.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities[] with fields, partition_check context, fill_check logic). It covers edge cases (placeholder filter, low similarity skip) and provides enough detail for an agent to use the tool correctly.

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

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

Schema covers both parameters (event, topic) with descriptions. The description adds significant meaning: explains each mode's behavior, provides example slugs, notes that full URLs are accepted, and clarifies the cross-event mode's similarity logic. This goes well beyond schema definitions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes modes (trending, event, topic) and explicitly mentions sibling tools (e.g., polymarket_fill_risk) for custom sizing, differentiating its function.

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

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

The description provides explicit guidance on when to use each mode (no args for trending, event for specific market, topic for cross-event scanning) and when not to trade (if realizable_edge_pp ≤ 0). It also suggests polymarket_fill_risk for custom sizing, offering 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?

The description extensively details model families (crypto_price, news_momentum, etc.), caching behavior (KV-level, 1h, keyed on all knobs), output structure (by_segment, _diagnostics), and edge-case handling (Fed bets excluded). Annotations already declare readOnlyHint=true, but the description adds significant context about internal logic and data sources.

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

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

The description is long but well-structured with capital-letter section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, TRADEABLE-EDGE KNOBS) and technical details that warrant the length. Every sentence adds value, though minor trimming could improve readability without losing substance.

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

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

Given the tool's complexity (9 parameters, 3 segments, no output schema), the description covers all aspects thoroughly: purpose, usage, parameter semantics, output format (by_segment with _diagnostics), caching, and edge cases (Fed bets). It fully compensates for the lack of an output schema.

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

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

Schema coverage is 100% (all parameters documented). The description adds meaningful context beyond schema for several parameters, such as explaining min_kelly ('Skips opportunities too small to bet sensibly') and min_partition_leg_kelly (applies to per-leg Kelly inside partitions). Some parameters like limit and window are already well-described in the schema, but the description enhances overall understanding.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly mentions the use case 'what should I bet on today'. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage, which have overlapping scopes.

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

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

The description provides guidance on when to use the tool (opportunity discovery) and details tradeable-edge knobs (min_liquidity, max_spread_pp) to filter opportunities. It also mentions that Fed bets are excluded from ranking. However, it lacks explicit when-not-to-use instructions or alternatives, such as pointing to polymarket_arbitrage for pure arbitrage.

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 safety and idempotency. The description adds significant behavioral detail: explains decay is computed on |edge_pp_net| (signed by direction), snapshot_dates are cache-miss dependent, and limits like 60-day TTL. 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 front-loaded with the key purpose question and structured into clear sections: purpose, response fields, limits. It is slightly detailed but each sentence earns its place; could be trimmed slightly without losing value.

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

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

With no output schema, the description fully details the return format (tracked[], expired[], snapshot_dates[]), including field explanations and computation logic. It also covers limits and data gaps, making it complete for a complex time-series tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reiterates default and clamp for 'days' and adds 'snapshot family' context for 'window', but adds minimal new 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 provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' It distinguishes from sibling tool polymarket_edges by focusing on time-series analysis. The verb 'answers' and specific output fields make the purpose unambiguous.

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

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

The description implies usage context by contrasting fresh edges vs. 3-week-old edges, and details what the tool returns, guiding when to use it. However, it does not explicitly state when not to use it or name alternative tools for other needs, which would strengthen guidance.

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

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

Discloses detailed behavioral traits: walks the order book ladder, returns verdict (clean|degraded|cannot_fill), and warns about forced directional risk from partial fills. No contradiction with annotations (readOnlyHint, idempotentHint, etc.). Adds significant context beyond annotations.

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

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

Description is lengthy but well-structured with clear sections (mode distinctions, required parameters, return values, warnings). Every sentence serves a purpose; slight verbosity is justified by tool complexity.

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

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

Given no output schema, the description enumerates all return fields (top_of_book, vwap_fill_price, slippage_pp, verdict etc.) and explains behavior in both modes. Fully addresses the needs of an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but description adds extra meaning by explaining default values, mode-specific interpretations of size_usd (spend vs. target proceeds vs. settlement notional), and automatic side selection in basket mode. Provides clarity 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?

Description clearly states it is a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with distinct single-market and basket modes. It differentiates from siblings by explicitly referring to polymarket_arbitrage and polymarket_edges signals.

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 instructs when to use ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and provides rationale for exclusion (theoretical overround on thin books, partial basket fills leading to unhedged positions).

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

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

The description comprehensively discloses behavior beyond annotations: it explains the compatibility_warning field's two cases, temporal_alignment, skipped_cross_type/subtype counters, and the rarity of real spreads. This adds critical context that annotations (readOnlyHint, idempotentHint) do not cover. 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 verbose but well-structured with clear mode demarcation, response format, and safety field explanations. It uses parentheses and bolded terms effectively. Slightly longer than necessary 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 complexity of cross-venue spread computation, the description covers inputs (3 params with examples), response shape (leg prices, spread array, safety fields), and edge cases (temporal alignment, skipped comparisons). No output schema exists, but the description compensates with detailed behavioral clauses.

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 have schema descriptions, but the tool description adds valuable usage context: it lists the 10 topic shortcuts with examples for kalshi_event_ticker and polymarket_event_slug. While schema coverage is 100%, the description enhances understanding of parameter interactions and mode switching.

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

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

The description clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools (like polymarket_arbitrage or polymarket_edges) by focusing on this specific pair of venues and providing two modes of operation.

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 each mode: topic shortcuts for common macros, or explicit tickers for custom pairings. It also warns that most pre-mapped topics currently return compatibility warnings, setting proper expectations. It advises when spreads are meaningless (e.g., temporal misalignment or incompatible bet shapes).

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds no additional behavioral context, but does not contradict annotations.

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

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

Two sentences, front-loaded with core purpose, no superfluous 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 zero parameters, rich annotations, and presence of output schema, the description is sufficiently complete. It hints at output content (ingredients, instructions).

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

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

No parameters exist, so schema coverage is 100%. Description does not need to add parameter info; baseline is 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?

Description clearly states the tool returns a random meal recipe with full ingredients and cooking instructions. It distinguishes from sibling tools like get_meal (specific meal) and search_meals (search-based).

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?

States use case: 'when you need recipe inspiration without a specific search.' Implicitly suggests avoiding when a specific meal is desired, but does not explicitly list alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds scoping details (anonymous IP, BYO key hash, account ID) and explains it retrieves previously saved data. No contradictions. Adds useful context beyond annotations.

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

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

Three sentences, each purposeful. Front-loaded with the primary action. No unnecessary words. Efficient and clear.

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

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

Given the single optional parameter, no output schema, and informative annotations, the description fully covers the tool's purpose, usage, scoping, and relationship to siblings. No gaps.

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

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

Schema coverage is 100% with one optional 'key' parameter described. The description adds the dual behavior: omitting key lists all keys, which matches the schema description. Provides additional clarity 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 retrieves a value saved via 'remember' or lists all keys when omitted. It uses specific verbs and resources, and distinguishes from siblings like 'remember' and 'forget' by specifying the opposite operation.

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 use cases (e.g., retrieving user's target ticker, address, research notes) and mentions scoping. It suggests pairing with 'remember' and 'forget' but does not explicitly state when not to use it. Still clear overall.

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. The description adds behavioral context: polling is fine, mark_read affects subsequent calls, and it mentions the return fields. This supplements the annotations well, with no contradictions.

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

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

The description is a single concise paragraph that front-loads the main purpose. Every sentence adds meaningful information without redundancy. It efficiently covers purpose, usage, parameters, and alternative access.

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 5 optional parameters, no required ones, no output schema, and clear annotations, the description provides good context: what is returned, how to filter, mark_read behavior, and polling. It mentions an alternative access URL. Minor omission: no explicit handling of limit or pagination beyond the 'polling' note, but overall complete for agent use.

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

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

Schema coverage is 100% with descriptions, but the description adds value by providing an example for type ('sec_8k'), clarifying mark_read's effect ('flag returned events read'), and explaining the behavior of since. This goes beyond the schema alone.

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

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

The description starts with 'Pull fired events from your subscription feed', clearly stating the action and resource. It specifies what the tool returns (source, citation_uri, raw payload) and distinguishes itself from other access methods, giving a clear purpose.

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 how to filter by type and since, and how to use mark_read. However, it does not provide guidance on when to use this tool vs. alternatives like list_subscriptions or when not to use it. The usage context is clear but lacks explicit exclusion or comparison.

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 fallback behavior (GDELT to GNews), soft-failure for USPTO, parameter formats (ISO date vs relative shorthand), and return structure (changes grouped by source with URIs). No contradiction with readOnly, idempotent, etc. 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?

Well-structured with front-loaded purpose and examples, but slightly lengthy. Every sentence adds value, but could be tightened slightly without loss.

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

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

Given the complexity (multiple sources, fallback, potential failures) and no output schema, the description fully explains behavior, parameters, and return format. 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%, so baseline is 3. Description adds value by explaining relative shorthand for 'since' with examples and clarifies 'type' only supports 'company'. Could be slightly more detailed for 'value' but schema already covers ticker/CIK.

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, GDELT/GNews, USPTO) and distinguishing from the static profile tool 'entity_profile'. It answers questions like 'what's new with X' and 'news on Tesla recently'.

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

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

Explicitly mentions when to use the alternative tool 'entity_profile' for static data, and provides example queries and parameter guidance (e.g., 'Use "30d" or "1m" for typical monitoring').

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 idempotentHint=true and destructiveHint=false. The description adds behavioral context: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours', which goes beyond the annotations. No contradiction with annotations.

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

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

The description is concise with about 4 sentences, front-loading the purpose and usage, then adding details on persistence and complementary tools. Every sentence adds value without redundancy.

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

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

For a simple key-value store without output schema, the description adequately explains persistence semantics and scoping. It mentions cross-session and within-session usage. It could mention what happens on key collision, but the idempotentHint suggests safe re-saving.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples of keys and values ('subject_property', 'target_ticker', 'findings, addresses'), enhancing understanding beyond the schema parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It uses specific verbs ('Save', 'store') and identifies the resource ('data', 'key-value pair'). It distinguishes from sibling tools (recall, forget) by mentioning 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?

The description provides explicit guidance on when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again'. It also mentions pairing with recall and forget, but does not explicitly state when not to use the 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 declare readOnlyHint, idempotentHint, and destructiveHint as safe and non-destructive. The description adds value by disclosing internal cascading through lookup endpoints, auto-disambiguation, and specific return details (ticker, CIK, RxCUI, citation URIs), which go beyond annotations.

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

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

The description is slightly lengthy but front-loaded with example queries. Every sentence adds value, breaking down supported types and return format. Could be tightened, 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?

Without an output schema, the description fully explains return values for both company and drug types, including citation URIs. It covers input formats, internal behavior, and the fact that it replaces manual lookups, making it contextually complete.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds examples of accepted formats (ticker, CIK, name; brand/generic) and mentions auto-disambiguation, providing meaning beyond the enum and string 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 begins with concrete query examples, then clearly states it resolves names to canonical identifiers. It distinguishes between company (ticker, CIK) and drug (RxCUI) types, and advises using it 'FIRST whenever you have a name but need an ID.' This makes the purpose specific and actionable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and mentions it replaces manual lookups. While it doesn't explicitly exclude alternatives among siblings, the context is clear enough for most use cases.

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

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

The description adds significant behavioral context beyond annotations: it explains the probing mechanism (using ai_visibility_check), ranking logic, and return fields (score, confidence, signal density). Annotations already indicate read-only, idempotent, non-destructive behavior, and the description reinforces and expands on this.

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 starts with the core purpose, then explains the mechanism, use case, and return values. Every sentence adds necessary information without redundancy.

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

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

Given the tool's complexity (comparing multiple entities, multiple models, ranked list), the description covers all essential aspects: what it does, how it works, when to use it, and what it returns. No output schema is present, so the description adequately explains return values.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the entities array's first entry is treated as the subject and that models like 'workers-ai' and 'anthropic' are supported. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side, ranking them by score. It distinguishes itself from sibling tools like ai_visibility_check by focusing on comparison rather than single-entity 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 provides a concrete use case ('competitive AI-marketing audits') and implies that for single entities one should use ai_visibility_check. However, it does not explicitly state when not to use this tool or list alternative tools for different scenarios.

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

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

Annotations already provide safety hints, but the description adds crucial behavioral details: partial failures degrade gracefully, bundlephobia measurement can take 5-30s, and sources_failed will list timeouts. This goes beyond annotations to describe real-world behavior.

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

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

Every sentence adds value: composite purpose, inner services, use cases, fallback behavior, version defaults, and return structure. Front-loaded with core purpose, no redundant or wasteful phrasing.

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

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

Despite no output schema, the description thoroughly enumerates return fields (summary block, advisory detail, links, alternatives). Also covers error handling (partial failures). For a complex composite tool, this is remarkably complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description reiterates the default version behavior but adds minimal new semantic value beyond the schema. No additional context on parameter constraints or formatting.

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 composite check for evaluating npm packages, specifying the verb 'check' and resource 'npm package'. It distinguishes from siblings by aggregating multiple services (deps.dev, bundlephobia) into a single call, which is unique among the listed 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?

Explicitly states when to use: 'Use whenever an agent asks...' and provides exclusion guidance: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This clearly differentiates from sibling 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?

The description adds useful context beyond annotations: it specifies the full return payload (category, cuisine area, ingredients with measurements, instructions, tags, URLs). Annotations already indicate read-only, idempotent, non-destructive behavior, so the description complements this with detailed output content.

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

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

Two sentences, front-loading the purpose. Every sentence adds value: first states what it does, second describes the rich return data. 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?

The description covers the tool's input (query) and output (full recipe details) sufficiently. Given an output schema exists, the description does not need to list return fields in full detail. It is complete for a search-by-name tool with strong annotations.

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 'query' parameter, so baseline is 3. The description says 'by meal name', which matches the schema's 'meal name or partial name'. It does not add additional semantics like valid formats or constraints 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 the verb 'Search', the resource 'TheMealDB for recipes', and the scope 'by meal name'. It distinguishes from sibling tools like 'get_meal' (likely by ID) and 'meals_by_ingredient' (different search criteria).

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

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

The description implies usage for searching by meal name but does not explicitly state when to use this tool versus alternatives like 'meals_by_ingredient' or 'random_meal'. No exclusions or when-not-to-use guidance is provided.

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

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

Beyond annotations (readOnlyHint, etc.), the description reveals specific behavioral traits: 'BGE-base-en embeddings + cosine over 500-char overlapping windows', 'cap is 200K chars (longer inputs are truncated and flagged)', and that 'every passage carries an offset'. No contradiction with annotations.

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

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

The description is concise (3-4 sentences) and front-loaded with the core purpose. Every sentence adds value—examples, use case, behavioral details, and truncation warning. No redundant or filler text.

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

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

Despite lacking an output schema, the description explains return values ('top-N passages with character offsets and similarity scores'), covers truncation behavior, and provides pairing context. It is sufficiently complete for an agent to use the tool effectively.

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

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

Schema description coverage is 100% with detailed parameter descriptions (e.g., text max ~200K chars, query with examples). The free-text description adds usage examples but does not introduce new parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource, and distinguishes from sibling 'ask_pipeworx_grounded' by explaining the pairing and use case. It avoids tautology and provides concrete examples (e.g., SEC 10-K body).

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 'Use when the record is too big to cram into the prompt' and mentions pairing with 'ask_pipeworx_grounded'. It provides clear context but does not exhaustively list all alternative tools or exclusions.

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

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

Disclosures go well beyond annotations: requires OAuth, returns ID, delivery limits (SMS cap 10/day, webhook auto-disable after 10 failures), signing secret returned once for webhook. All behavioral traits are transparently documented.

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

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

Well-structured with newlines and bullet-like enumeration, front-loading the core purpose. Slightly verbose but each sentence adds necessary context. A minor trim could improve conciseness without losing information.

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

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

Given the tool is a creation endpoint with 3 parameters and no output schema, the description fully covers what the agent needs: returns subscription ID, all parameter variants, delivery details, and persistent feed. Complete for decision-making alongside sibling tools.

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?

Despite 100% schema coverage, the description adds significant meaning: explains type-specific parameters (e.g., sec_8k items mapping to officer change), constraint on clinical_trial (sponsor or condition required), and webhook signing details. No repetition without 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 creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It enumerates supported types and delivery channels, distinguishing from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Explicitly requires a Pipeworx OAuth account and explains that anonymous/BYO cannot persist subscriptions. Provides details on each subscription type and delivery method, but does not explicitly compare to alternatives like polling via recent_alerts or when to prefer one delivery channel over another.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it returns live catalog data with tool+argument shapes, but this is minor additional context. The description does not contradict annotations.

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

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

The description is front-loaded with common user queries and clearly structures the purpose, return content, and usage. It is slightly verbose but each 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 that the tool has no output schema and only one parameter with full coverage, the description sufficiently explains what the tool returns (category-bucketed examples with tool+argument shapes) and when to use it. It covers the essential information for an AI agent to use it 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?

There is one optional parameter 'topic' with full schema description coverage. The description repeats the purpose of the parameter (focus on a category) but does not add significant new semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it's an onboarding entry point that returns category-bucketed example questions to help users understand what Pipeworx can do. It uses specific verbs ('returns', 'suggest') and distinguishes itself from sibling tools like 'ask_pipeworx' by being the first stop for exploration.

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

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

The description explicitly advises to 'use this FIRST when you do not yet know what Pipeworx can do for you', providing clear context for when to invoke. It also explains the optional 'topic' parameter to narrow focus. While it doesn't explicitly state when not to use, 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?

Adds context beyond annotations: explains ownership enforcement and that the row is deactivated (not deleted), keeping historical events available. 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?

Two sentences, front-loaded with purpose, no unnecessary words or 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?

Complete for a simple mutation tool with one parameter, full schema coverage, annotations, and no output schema. Explains effect and access control adequately.

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% for the single parameter. The description adds minimal extra meaning beyond the schema's field description.

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

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

Description clearly states 'Cancel a subscription by id', using a specific verb and resource. It distinguishes 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?

States ownership enforcement ('you can only cancel your own subscriptions'), providing a clear when-not condition. Does not mention alternative tools for other use cases.

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

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

The description adds significant behavioral context beyond annotations: it explains the tool uses SEC EDGAR + XBRL, returns a specific set of verdict types, and replaces 4-6 sequential calls. Annotations already indicate readOnlyHint, idempotentHint, and non-destructive, and the description complements these perfectly without contradiction.

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

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

The description is a single paragraph with multiple sentences, but each sentence earns its place: it lists use-case examples, states usage context, specifies version limitations, and describes output format. It is efficient without being overly terse.

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 no output schema, the description provides enough detail about the output (verdict types, structured form, citation, delta) to understand what the tool returns. It also covers limitations (v1, company-financial only). It could be more complete with an example response, but overall it is 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?

With 100% schema description coverage, the baseline is 3. The description adds value by explaining the type of claims the tool handles (company-financial for public US companies), providing natural-language examples, and clarifying that the input can be phrased in various ways. This goes beyond the schema's generic description.

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

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

The description clearly identifies the tool's purpose as natural-language claim verification against authoritative sources, with specific examples of user intents. It distinguishes itself from sibling tools by describing its domain (company-financial claims) and stating it replaces multiple sequential calls, which differentiates it from other research tools.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides examples. It also mentions the current version supports only company-financial claims, implicitly setting boundaries. However, it does not give explicit when-not-to-use guidance or alternative tools for non-financial claims, which would warrant a 5.

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