Food Feeds

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details beyond these: the default model (Workers AI Llama-3.3-70b), the free vs. paid billing model for Anthropic calls, and the fact that the API key is passed straight through. This gives agents insight into cost and side-effect implications.

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

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

The description is three sentences, front-loaded with the core action, followed by model options and use cases. Every sentence adds distinct value—purpose, configuration/billing, and output/use cases—with no fluff or repetition.

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 explicitly states the return structure ('per-model {score, confidence, signals, raw_response} + a combined view'). It covers parameter behavior (default model, optional Anthropic key), use cases, and sample entity formats in the schema. For a read-only probe tool, this is complete and leaves no major gaps for an agent to infer.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds context about the default model and the condition for using _apiKey, but this largely mirrors schema text. Thus the description provides only marginal additional meaning beyond the schema, meriting the baseline score of 3.

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

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

The description opens with 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model,' giving a specific verb ('probe'), resource ('LLMs'), and output (visibility score). This clearly distinguishes it from sibling tools like ask_pipeworx (general Q&A) and scan_competitor_ai_presence (competitor-focused analysis).

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

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

The description states concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies when to pass '_apiKey' for Anthropic (BYO key). It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select 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 already provide readOnly/openWorld/idempotent hints, but the description adds valuable behavioral context: it routes to 5,529 tools across 1,455 sources, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier with one fast call. No contradiction with annotations; it enriches the safety profile with operational details.

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

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

The description is long but every sentence earns its place: direct imperative ('PREFER OVER WEB SEARCH'), capability overview, example queries, and escalation paths. It is front-loaded with the most critical usage directive, then details alternatives. No fluff or repetition; structure is effective for quick parsing.

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 (routing to thousands of sources) and lack of output schema, the description is remarkably complete: covers input format, scope of data, examples, output citation mechanism, tier behavior, and when to choose alternatives. It does not need to explain return values further because the citation URIs are mentioned and examples suffice.

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 six parameters documented, including aliases), so the baseline is 3. The description doesn't add any parameter-specific semantics beyond what the schema provides, though it does illustrate acceptable question formats via examples. This is sufficient given the schema's completeness.

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

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

The description clearly states the tool routes questions to authoritative structured data sources and returns answers, using a specific verb ('ask') and resource (Pipeworx). It also distinguishes itself from sibling tools by naming alternatives like ask_pipeworx_grounded and deep_research, and provides concrete examples of use cases.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions,' giving clear when-to-use directives. It also names alternative tools for specific scenarios (hallucination-resistant answers ask_pipeworx_grounded, multi-part deep_research) and notes it handles breaking-news via live news packs. This exceeds basic guidance and effectively differentiates from 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?

The description adds valuable behavioral context beyond annotations: it explains the experimental nature with candidate routing improvements and that behavior may change when a candidate is active. It also confirms current identical behavior to ask_pipeworx. Annotations already cover read-only/idempotent, so this adds useful dynamic behavior info.

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 adding meaningful info: identity, current state, and usage instructions. It is slightly verbose but front-loaded with the key beta identity. No wasted words, yet could be tightened slightly.

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

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

For a beta alias of a known tool, the description covers identity, current state, usage, and behavioral expectations. No output schema exists, but it refers to the same response shape as ask_pipeworx, which is sufficient. Missing a bit of detail on what 'routing' entails, but overall 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 description doesn't need to explain parameters. It mentions 'same arguments' as ask_pipeworx, but that's redundant with the schema. No additional parameter semantics are provided beyond what the schema already offers.

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 beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx sibling, making its purpose and scope 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?

It gives explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the alternative (ask_pipeworx for stable routing) and clarifies that results are compared to decide merges, plus notes it is a full working router with no fallback 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, but the description adds substantial context beyond these: it details the exact success return shape ({answer, evidence, confidence, source, fetched_at}) and enumerates all refusal_reason values. It also discloses that one extra LLM call is incurred, which is not inferable from 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?

Although the description is long, every clause earns its place: it packs purpose, routing, extraction guarantee, exact return structures, refusal taxonomy, use cases, and cost comparison into four sentences. The critical use-case guidance is front-loaded, and the cost comparison is placed at the end as a secondary note.

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

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

The tool has no output schema, but the description fully documents the success and failure response shapes, including the enumerated refusal_reason values. Given the tool's routing complexity and high-stakes use cases, the description covers what the agent needs to decide when to call it and interpret its result, without needing 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 six parameters are documented as aliases for 'question', so the schema already explains everything. The description does not add parameter-level meaning beyond the schema, but it doesn't need to since the schema is fully descriptive. 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 opens with 'Hallucination-resistant answer mode for high-stakes reads' and explicitly contrasts with 'Same routing as ask_pipeworx' while adding a distinct extraction guarantee ('uses ONLY what the tool result contains'). This clearly differentiates it from siblings like ask_pipeworx and ask_pipeworx_beta by scope and safety posture.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups). It also gives a clear alternative: 'prefer ask_pipeworx for casual lookups' and states the cost trade-off.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description goes far beyond them with concrete behavioral details: resolver confidence tiers, status codes (low_confidence_match, market_closed_or_inactive), fan-out behavior, wide-spread flag, news fallback mechanics, and resolution-rule risk. This is exceptional transparency for an agent.

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 dense, with a clear hierarchy: purpose, classifiers, fan-out examples, response shapes, resolver contract, safety, resolution rules. Every section adds actionable detail. It earns its length for a complex tool, though it could be trimmed (e.g., the many fan-out examples) without losing core value.

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

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

Given there is no output schema, the description fully compensates by documenting response shapes, resolver contracts, parent-event extraction, news fallback, safety short-circuits, and resolution-rule risk. An agent has enough context to invoke the tool, interpret results, and handle edge cases without additional documentation.

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 documents all three parameters with descriptions. The tool description mostly reinforces the schema by showing examples of market input forms and adding context about what the tool does with the parameters (e.g., fan-out for depth), but it doesn't add substantial new semantics beyond the schema's 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 opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' – a specific verb and resource. It further clarifies scope with classifiers and fan-out examples, making it unmistakable what the tool does and how it differs from sibling tools like polymarket_edges or validate_claim.

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

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

Provides explicit 'Use for' phrases ('should I bet on X', 'what does the data say about Y') and gives rich contextual guidance for low-confidence matches, closed markets, and illiquid spreads. However, it does not name alternative tools for when NOT to use this one, leaving some ambiguity relative to sibling analyzers.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses data sources for each type (SEC EDGAR/XBRL 10-K data; FAERS/FDA/trial counts), mentions correct handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), explains sorting by primary metric, and states the output includes paired data plus citation URIs. This is rich behavioral context.

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

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

The description is dense but well-structured, starting with user intent phrases and then covering operational details. Every sentence adds value, but it is somewhat long and could be slightly tightened. It is still front-loaded and organized effectively.

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

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

For a tool with no output schema, the description covers input semantics, data sources, sorting, and output highlights (paired data + citation URIs). It lacks a precise output format description or error handling details, but it is nearly complete for its complexity.

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

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

The description adds significant meaning to the 'type' parameter by explaining exactly what data each enum value retrieves (10-K metrics vs adverse-event/trial counts). It also clarifies 'values' by distinguishing tickers/CIKs from drug names with examples, enriching the schema's basic 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: side-by-side comparison of 2–5 companies or drugs in one parallel call. It includes specific trigger phrases like 'X vs Y' and 'rank these companies', and explicitly distinguishes it from sequential single-pack lookups.

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

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

Provides explicit usage triggers ('Compare X and Y', 'which is bigger', 'head to head'), states the entity count range (2–5), and gives a strong preference directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This clearly tells when to use this tool over alternatives.

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

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

Despite readOnlyHint and idempotentHint being true, the description adds rich behavioral context: account/paid-tier requirements, 15-60s latency (up to ~90s for thorough), decomposition and parallel routing, gaps[] (never invented), contradictions[], stable pipeworx:// citations with resolvability caveats, and semantic excerpting of large records. No contradiction with annotations.

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

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

The description is long but every sentence carries unique, decision-relevant information. It front-loads the critical caveat (account required) and then builds logically: what it does, when to use alternatives, behavioral details, depth explanation, and performance expectations. No filler 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?

Given the tool's complexity (2 params, no output schema), the description is remarkably complete. It covers the return packet structure, gaps, contradictions, citation resolvability, timing, and examples of appropriate use. The schema and annotations handle the remaining structured context, making it fully sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema: it explains the depth parameter's effect on hop behavior and paid status ('thorough' needs a paid plan) and clarifies that broad/multi-part questions are expected for the question parameter. This elevates it above baseline but does not fully reinvent the parameter docs.

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

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

The description opens with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources.' It explicitly contrasts with open-web search ('this is NOT open-web search') and names the exact deliverable (findings packet with citations and gaps). It clearly distinguishes from sibling tool ask_pipeworx by stating this is for multi-part questions while ask_pipeworx is for single lookups.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even an authentication-based fallback: 'If you are not signed in, use ask_pipeworx instead.' The description also notes account and paid-plan requirements, giving clear prerequisites.

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 this as a safe, idempotent read operation (readOnlyHint=true, destructiveHint=false). The description adds behavioral value by disclosing that results are ready to call directly, include curated examples, and require no second schema lookup. This goes beyond the annotations' basic safety profile.

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

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

The description is front-loaded with the core purpose and structured logically: purpose, use cases, return format, and when-to-call guidance. The cited domain list is long but informative; every sentence adds value, though it could be tightened slightly.

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

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

For a discovery tool with no output schema, the description fully explains what it returns (top-N tools with names, descriptions, schemas, examples) and how results are ready to call. It also covers when to use it ('many tools available', 'not just one answer'), making it self-sufficient for an agent.

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

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

Schema description coverage is 100%, with clear descriptions for query and limit, including aliases and default/max values. The description's references to 'describing the data or task' and 'top-N' add little beyond the schema. Baseline 3 is appropriate because the schema already fully documents parameters.

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

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

The description clearly identifies the tool as a meta-tool for discovering other tools: 'Find tools by describing the data or task.' It specifies the resource (tools), the action (discover/find), and the scope (returns names, descriptions, schemas), distinguishing it from sibling tools that perform direct searches or analyses.

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context, though it does not name specific alternatives or exclusion 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 discloses significant behavior beyond the annotations: it fans out across multiple sources, mentions the USPTO API sunset and soft-fail behavior, describes GDELT→GNews fallback, and lists exact return fields. Annotations already signal safe read-only idempotent operation, so the description adds valuable context 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 dense but well-structured: example queries, a summary, explicit preference guidance, source list, return fields, and parameter notes. Every sentence serves a purpose, front-loading the core purpose while packing additional context in without wordiness.

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 details the return value structure (CIK, name, filings with URIs, fundamentals fields, patents, news, LEI) and explains fallbacks and limitations. It covers inputs, outputs, and edge cases thoroughly for a complex multi-source 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% for both parameters, but the description adds concrete examples ("AAPL" or "0000320193") and reinforces the zero-padding requirement and the limitation on names. This goes slightly beyond the schema, providing practical usage context, though it partly overlaps with schema text.

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

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

The description opens with concrete user queries and a clear statement: 'full cross-source profile of a US public company in ONE parallel call.' It names the resource (US public company) and verb (profile), and distinguishes from siblings by explicitly saying to prefer this over chaining single-pack lookups.

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

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

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states that names are not supported and directs to use resolve_entity first, covering both when to use and when not to use.

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

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

Annotations already declare readOnly and idempotent hints. The description adds 'CF-robust: fetches directly and falls back to a proxy if the source blocks the gateway', disclosing resilience behavior beyond the annotations. It also mentions normalization but does not detail output structure.

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

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

The description is two concise sentences. The first sentence states the core purpose, and the second adds a key usage tip and behavioral note. Every sentence earns its place with no wasted words.

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

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

For a tool with no output schema, the description covers purpose, usage guidance, and a key behavioral fallback. However, 'normalize' is vague and the return format is not explained, which is a minor gap.

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 descriptions for url, limit, and query. The description does not add any additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'Fetch and normalize any RSS / Atom / RDF feed by URL' with a specific verb and resource. It also distinguishes from sibling tools like list_feeds by explicitly directing users to use list_feeds first for curated sources.

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 to use list_feeds first for curated sources, which is an alternative. It implies general use for fetching any feed URL but does not explicitly mention when not to use this tool or compare with read_feed.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the bar is lower. The description adds minor context ('previously stored', 'clear sensitive data') but doesn't disclose additional behavioral details like irreversibility or error handling. It is consistent 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?

Three sentences, front-loaded with the core action, and every sentence adds value—purpose, usage trigger, and sibling pairing. No 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?

The tool is simple (one required param, no output schema) and annotations cover safety/destructive profile. The description includes purpose, usage guidance, and sibling relationships, making it complete for invocation.

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

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

Schema description coverage is 100% ('Memory key to delete'), so the description doesn't need to compensate. The description's 'by key' is redundant with the schema, adding no extra meaning. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly differentiating from siblings like 'remember' (store) and 'recall' (retrieve). It states exactly what the tool does.

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

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

Explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. Also names complementary tools ('Pair with remember and recall'), providing clear contextual guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining the internal steps: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output shape as 'a single text blob ready to drop at site-root/llms.txt.' This adds value 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?

The description is three sentences, with the first stating the core purpose, the second detailing the process, and the third listing use cases. Every sentence earns its place—no fluff, clear front-loading, and appropriately sized for the tool's complexity.

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

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

The tool is simple (2 params, no output schema), and the description sufficiently covers what it does, how it works, and the expected output format. It does not explain edge cases like unreachable URLs or rate limits, but given the rich annotations and schema, this is not a major gap. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage for both parameters (url and max_links), so the baseline is 3. The description does not add any additional parameter semantics beyond saying 'for any URL,' which is redundant with the schema. It does not describe max_links behavior, but the schema already covers that, so no penalty.

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

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

The description states a specific verb+resource: 'Generate a production-ready llms.txt file for any URL.' It clearly explains the process (fetches page, extracts title/description/key links) and the exact output format. This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on auditing rather than generating a file.

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 'Useful for' list with three concrete scenarios: getting a client's site indexed, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor. This gives clear context on when to use the tool, but it does not explicitly name alternative tools or state when NOT to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly and idempotent hints, and the description adds useful context by noting the feed is curated and listing the exact fields returned. It also hints at the relationship to read_feed. No contradictions with annotations.

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

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

Two tight sentences with no filler. The first sentence states the core function and fields; the second covers filters and the handoff to read_feed. Every word earns its place.

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

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

Given the low complexity (2 optional params, no output schema), the description adequately covers the return fields, filters, and next-step guidance. Minor gaps like pagination or ordering are not critical for a simple listing tool.

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

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

Schema coverage is 100% with descriptions for both query and category. The description's mention of 'filter by category (food) or keyword' directly maps to the schema, adding no new semantic depth beyond what the schema already provides.

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

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

The description clearly states the tool lists curated food & dining feeds with specific fields (id, title, category, source). It distinguishes itself from siblings like read_feed by mentioning the next step, making the purpose unmistakable.

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

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

It provides a clear usage context: list feeds with optional filters, then pass an id to read_feed. However, it doesn't explicitly contrast with other list-type siblings like list_subscriptions or fetch_feed, so the guidance is good but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by disclosing that it returns only active subscriptions by default and includes fields like fire_count, which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the purpose, then lists return fields and use cases. Every sentence adds value, with no fluff 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?

The tool is simple (one optional parameter), and although there is no output schema, the description explicitly lists all return fields. It also explains practical use cases. Minor gaps like pagination or limits are not critical for this straightforward read-only list 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 includes a description for include_inactive. The description does not add new meaning for the parameter beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions.' It specifies the verb (list), resource (subscriptions), and scope (caller's active). It also enumerates the returned fields, distinguishing it from sibling subscribe/unsubscribe 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 clear context for when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies using it before subscribing or unsubscribing, but it does not explicitly state when not to use it or name alternatives directly.

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 are all false (readOnly, openWorld, idempotent, destructive), so the description carries full behavioral burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota behavior ('doesn't count against your tool-call quota'), the claim_token flow ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), and reading cadence ('team reads digests daily'). This adds significant context beyond 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?

The description is longer than average but every sentence earns its place. It is front-loaded with the core purpose, followed by usage categories, exclusions, token behavior, rate limits, and cost. No filler or redundancy; the structure flows logically from what → when → how → constraints.

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

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

Despite having no output schema, the description fully covers the tool's return behavior (claim_token and later status), input parameters (type, context, message, claim_token), exclusions, rate limits, and operational cadence. It is self-contained and leaves no major ambiguity for an agent selecting or invoking the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema: it explains claim_token usage with a concrete example, instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' for the message/context fields, and clarifies acceptable message length ('1-2 sentences typical'). This goes beyond the schema descriptions, though the schema already documents each parameter effectively.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the tool as a feedback submission mechanism and distinguishes it from sibling tools like ask_pipeworx or discover_tools by explicitly limiting scope to Pipeworx-served tools and contrasting with other MCP servers.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead,' naming the alternative action and preventing misuse.

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?

Even though annotations already declare this a safe read-only operation, the description adds substantive behavioral context: data source ('derived from CF analytics-engine'), privacy ('no PII'), output shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). These details meaningfully go beyond the annotations and help the agent anticipate results.

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: the main statement is front-loaded, followed by a bulleted 'Useful for' section and a final note on data provenance. It's slightly long but every sentence contributes value. No fluff or filler.

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

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

Given the tool's simplicity (one optional parameter, no output schema, no nested objects), the description is thorough. It explains what the tool returns, the window options, use cases, and even the data source and caching. Since there is no output schema, the description successfully conveys the return shape ('top tools, top packs, total call volume') and the tuple structure.

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

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

The schema already documents the window parameter with its enum and explanatory description ('shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description repeats this in the opening line but adds no new meaning. Schema coverage is 100%, so the baseline of 3 is appropriate.

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

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

The description opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now.' It then explicitly states the return value ('top tools, top packs, and total call volume') and the time window options. This distinguishes it from siblings like discover_tools (which likely enumerates available tools) and ask_pipeworx (a Q&A 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?

The 'Useful for' list provides three concrete scenarios: discovering hot data sources, confirming canonical tools, and checking alignment with other agents. This gives clear context for when to use the tool. However, it does not explicitly mention alternatives or when not to use it, so it stops short of a full 5.

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

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

Goes far beyond the annotations (readOnlyHint, idempotentHint) by disclosing internal checks: partition filter with placeholder fraction threshold, semantic anchor with Jaccard similarity, fill-check logic that prices against live CLOB depth and warns against trading when realizable edge ≤ 0, and behavior when partition signal fires. This is rich behavioral context that helps an agent anticipate results and avoid false signals.

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 substantial but well-structured with clear section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and concise, information-dense sentences. Every paragraph adds necessary operational detail without redundancy, and key mode guidance is front-loaded.

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

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

For a tool with three modes, multiple filters, and a fill-check step, the description covers usage nuances, edge cases (placeholder slugs, low similarity, thin legs), response fields, and safety warnings. With no output schema, the description provides the necessary details about return structure and interpretation, making it complete for an agent to call and understand results.

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

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

Although the schema already describes both parameters (100% coverage), the description adds deeper meaning: explains the difference between event and topic modes, what kind of input each expects, the type of analysis each performs, and the exact scenarios for using them. It also clarifies that both are optional and what happens when neither is passed.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It also distinguishes between the three modes (trending_scan, event, topic) and references the alternative tool polymarket_fill_risk for custom sizing, making it clear what this tool uniquely does.

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

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

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also gives concrete examples (event slugs, seed questions), explains what cross-event mode catches that single-event misses, and directs users to polymarket_fill_risk for custom sizing.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description goes far beyond by detailing caching behavior ('Cached 1h at the KV level keyed on all knobs'), the edge calculation methodology per segment (lognormal barrier, GDELT ratio, overround with per-sport α), the 24h-move warning, and the diagnostics structure for empty segments. 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 heavily structured and front-loaded with purpose before diving into segments. It uses clear visual grouping (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS) and is technically dense. However, it is very long; while most sentences carry useful information, a shorter summary of model families could have preserved clarity for agent consumption.

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 covers the return structure: top-level by_segment with three segments, fed_candidates/fed_note, and _diagnostics explaining why segments are empty. It also explains caching and the per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread). This is complete for a complex, 9-parameter tool with no 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 already covers 100% of parameters with descriptions, establishing a baseline of 3. The description adds valuable cross-parameter semantics: min_partition_leg_kelly is explained as necessary because partition arbs always return kelly_fraction_half=0 at the parent level, and slippage_pp is contextualized with Polymarket fee/liquidity assumptions. This elevates it to 4, though not 5 because the schema already handles basic 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 states a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also frames it as 'what should I bet on today,' clearly distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by describing its three response segments and model families.

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

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

The description gives clear usage context: it's built for opportunity discovery without paging hundreds of markets, and it explains tradeable-edge knobs like min_liquidity/max_spread_pp and the fed_candidates exclusion. However, it doesn't explicitly name when-not-to-use or compare with sibling tools, so there's no strong exclusion 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?

Even with strong annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds significant behavioral detail: 60-day TTL, cache-miss snapshot writing, daily closes not intraday, and the signed edge_pp_net semantics (negative = SELL YES). No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and uses clear ARGS, RESPONSE, and LIMITS sections. It is dense but every section provides operational value; the 'wide for a reason' analogy is illustrative but slightly extraneous, keeping it from a perfect 5.

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 documents the return structure (tracked[], expired[], snapshot_dates[]) including field meanings, edge-case semantics, and limitations. It also covers parameter defaults and data availability gaps, making the tool self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats defaults for days and window but does not add new semantic meaning beyond the schema. It omits the minimum clamp value for days that the schema includes, though this does not harm usability.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and explicitly answers the question 'how long has this edge existed and is it shrinking?'. It differentiates itself from the sibling polymarket_edges tool by being built from its daily snapshots and focusing on historical persistence rather than current edges.

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

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

The description gives clear context for when to use the tool ('Answers how long has this edge existed and is it shrinking?') and contrasts it with fresh vs stale edges. It references the relationship to polymarket_edges snapshots, but does not explicitly name alternatives or provide when-not-to-use guidance, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral detail beyond those: it walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), names 'thin_legs' and 'forced_directional_risk' in basket mode, and explains how size_usd is interpreted differently in each mode. This is substantial contextual disclosure.

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 information-dense, with mode-specific details, return fields, and risk rationale all earning their place. It is front-loaded with purpose and requirements before elaborating on each mode. It could be slightly tightened, but every sentence adds meaningful guidance.

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

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

This is a complex tool with no output schema, yet the description thoroughly enumerates what the caller receives: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, and forced_directional_risk. It also explains failure modes and the danger of partial fills, making it complete for an AI agent to invoke correctly.

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

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

The schema already covers 100% of parameters with descriptions, so baseline is 3. The description adds meaning by clarifying conditional requirements (market or event), mode-dependent side defaults (auto in basket), and the dual interpretation of size_usd (max spend on buys vs target proceeds on sells, settlement notional in basket). This exceeds the 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 opens with a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the tool from sibling tools by naming polymarket_arbitrage and polymarket_edges as consumers of the output, and it separates single-market vs basket modes with concrete semantics.

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?

Usage is explicit: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when each mode applies (single-market vs basket), how defaults are chosen, and why using it is important (theoretical overround not capturable on thin books, partial fills convert arb to directional risk).

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

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

Despite annotations already declaring readOnly/idempotent/non-destructive, the description adds substantial behavioral disclosure: it reveals two compatibility_warning scenarios, explains temporal_alignment and its impact on mathematical meaning, and describes skipped_cross_type/subtype counters. This goes far beyond the annotations and is exceptionally transparent about edge cases and limitations.

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

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

The description is long but well-structured: it starts with a clear definition, then MODES, RESPONSE, SAFETY FIELDS, and a final caution. Every sentence provides useful information without redundancy. It is not as tight as a two-sentence description could be, but given the tool's complexity, the length is justified and front-loaded with the core purpose.

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

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

With no output schema, the description compensates by detailing the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It also covers edge cases and practical limitations, making the description nearly self-sufficient for an agent to understand tool behavior. This is a highly complete tool description for its complexity.

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

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

Schema coverage is 100% for the three parameters, giving baseline 3. The description adds extra meaning by explaining the topic parameter's 10 pre-mapped shortcuts and clarifying that kalshi_event_ticker and polymarket_event_slug override the topic-mapped values. This relationship is not in the schema and improves parameter 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 opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from siblings by focusing on cross-venue spread, and the two MODES (topic vs explicit ticker/slug) further clarify its exact function. The response format is also explicitly stated, leaving no ambiguity about what the tool does.

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

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

The description gives explicit guidance on when to use topic shortcuts vs explicit ticker/slug pairings, and warns about when spreads are not meaningful (compatibility_warning, temporal_alignment). It also cautions that 'pre-mapped ≠ tradeable.' However, it does not explicitly name sibling tools as alternatives, so it stops short of full when-to-use vs alternatives guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that the tool returns normalized items with specific fields (title, link, published, summary) and supports optional keyword filtering—information not present in the annotations and useful for downstream processing.

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 exactly two sentences, with the primary action stated upfront. Every clause carries information: the id source, the return format, and the optional filter. No wasted words or repetition of schema details.

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?

This is a simple, low-complexity read tool with all parameters documented in the schema. The description covers the resource identity, return type, and an optional behavior. There is no output schema, so the explicitly listed return fields (title, link, published, summary) fill that gap 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?

The input schema already provides descriptions for all three parameters (100% coverage), including the fact that 'feed' comes from list_feeds. The description adds minimal extra semantics beyond a general 'keyword filter' phrase, so it does not elevate above the schema-driven 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 opens with a specific verb ('Read') and a specific resource ('curated food & dining feed'), and clarifies the identifier source ('from list_feeds'). This distinguishes it from siblings like fetch_feed by domain and by the fact that it reads a managed feed rather than fetching arbitrary URLs.

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 a workflow: first call list_feeds to obtain the id, then read_feed. It does not explicitly name alternatives or state when not to use it, but the clear prerequisite ('from list_feeds') gives the agent enough contextual guidance for typical selection.

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

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

Beyond the annotations (readOnly, idempotent, destructive=false), the description adds critical behavioral details: the 'omit key' listing behavior and the scoping to an identifier (anonymous IP, BYO key hash, or account ID). This explains privacy and namespacing, which annotations do not convey.

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

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

The description is three sentences, each with a distinct purpose: function, use case, and scoping/companion tools. It is front-loaded with the primary action and free of filler or repetition.

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 retrieval tool with one optional parameter and strong annotations, the description covers the essential behaviors (retrieve, list, scope, pairing). It lacks explicit error/return value details, but the absence of an output schema and the tool's simplicity make the description adequate.

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

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

The schema fully describes the 'key' parameter (including 'omit to list all keys'), so the description doesn't add new parameter semantics. The examples of key contents are helpful but redundant to the schema's coverage.

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

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

The description clearly states the tool's function with specific verbs: 'Retrieve a value previously saved via remember' and 'list all saved keys'. It distinguishes itself from sibling tools by explicitly naming remember (save) and forget (delete), making the tool's niche 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 provides clear usage context: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes) and contrasts with re-deriving data. It implies the when-not-to-use by mentioning the companion tools (remember/forget), though it doesn't explicitly list exclusion 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context beyond annotations, such as the effect of mark_read on subsequent calls (only newer events shown) and the fact that the feed is also available via an HTTP endpoint for external use. This enriches the agent's understanding without contradicting the annotations.

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

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

The description is five sentences, each earning its place: purpose, return contents, filtering, mark_read behavior, and polling/alternative access. The key action is front-loaded in the first sentence. There is no redundant language or fluff, making it highly 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?

With no output schema, the description compensates by specifying that each alert carries source, citation_uri, and the raw event payload. It also covers filtering and mark_read semantics, which are critical for use. It does not explicitly mention the unread_only parameter, but the schema covers that, so it's not a gap. The description is complete enough 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 coverage is 100%, so each parameter is documented in the schema. The description adds extra meaning by explaining the interaction between mark_read and future calls, which is not obvious from the schema alone. It also gives a concrete example for the type parameter ('sec_8k'). This goes beyond the schema's baseline value.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It further clarifies the exact nature of the tool by explaining it returns the most recent alerts written by the evaluator, which distinguishes it from generic feed readers like fetch_feed or read_feed.

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

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

The description provides clear context for use: filtering by type and since, marking events read, and polling. It explicitly states 'Polls work fine,' giving a direct usage recommendation. However, it does not explicitly mention when to use this tool over sibling tools like fetch_feed or read_feed, so it stops short of full exclusionary 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses significant behavioral traits: it fans out to SEC EDGAR, GDELT/GNews, and USPTO in parallel; details the fallback order and failure mode (PatentsView API sunset soft-fails); and notes the source grouping in results. This adds substantial transparency beyond what annotations provide.

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

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

The description is dense but every sentence adds value. It opens with relatable query examples, then concisely explains data sources, parameter formats, return structure, and the alternative tool. The use of punctuation (dashes, parentheses) packages information efficiently without being verbose.

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

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

Given the tool's complexity (fans out to multiple sources, no output schema), the description adequately explains the high-level return structure: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. However, it does not detail the shape of individual change objects, which would be useful given the lack of an output schema. Still, the description covers the core behavior and limitations.

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

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

The schema covers all parameters 100%, but the description adds practical detail: 'since' accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y'), 'value' can be ticker or CIK, and 'type' is restricted to 'company'. This enhances usability over raw schema descriptions.

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

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

The description clearly defines the tool as a change feed for a company over a time window, using specific verbs like 'What's new' and 'latest on'. It explicitly distinguishes itself from the sibling tool entity_profile by stating when to use that instead, making the purpose unambiguous.

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

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

The description provides explicit usage context with example queries ('What's new with X', 'updates on Acme') and directly names the alternative tool: 'Use entity_profile instead when you want the static profile'. It also explains the internal fallback logic (GDELT preferred, GNews when rate-limited), which guides appropriate usage.

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

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

Annotations already declare idempotentHint=true and readOnlyHint=false. The description adds key behavioral context beyond annotations: 'Stored as a key-value pair scoped by your identifier' and 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This explains persistence and auth-dependence, which the agent needs to know.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value: purpose, usage conditions, and storage behavior with sibling references. 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 tool has no output schema, but the description covers the key behavioral aspects: scoping, persistence, and related tools. It does not mention return values or error conditions, but for a simple save operation these are not heavily needed. The description is sufficiently complete for an agent to invoke 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?

Schema coverage is 100%, with both 'key' and 'value' already described with examples in the input schema. The description only says 'key-value pair' and does not add further parameter-specific details, so it does not exceed the baseline 3.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It gives concrete examples (resolved ticker, target address, user preference) and explicitly distinguishes from sibling tools by referencing 'recall' and 'forget' for retrieval and deletion, respectively.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward...' and names alternatives with 'Pair with recall to retrieve later, forget to delete.' This tells the agent exactly when to use this tool and when to use 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 read-only/idempotent, but the description adds significant behavior not in schema: cascades through multiple endpoints, graceful degradation for LEI/FIGI, explicit listing of unresolved identifiers, source labels, and ownership data. No contradiction with annotations.

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

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

The description is dense and well-structured, with examples and supported-type details. It is longer than strictly necessary and repeats some schema info, but each section earns its place for a complex tool.

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

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

For a tool with no output schema, the description explicitly enumerates returned identifiers (CIK, ticker, LEI, FIGI, RxCUI), explains edge cases (unresolved fields, graceful degradation), and mentions ownership data and source labels. This is comprehensive for an entity resolution 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?

Input schema already provides 100% coverage with examples for both parameters. The description repeats some examples (e.g., 'AAPL', 'ozempic') but does not add new semantic meaning beyond schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool resolves user-spoken names to official identifiers, with specific query examples and a clear verb ('resolve'). It explicitly positions it as the first step when an ID is needed, distinguishing it from sibling tools like entity_profile.

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

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

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' Also details input formats for company and drug types. Does not explicitly name alternatives or exclusions, but the context is very 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 cover read-only/idempotent safety, and the description adds meaningful behavioral context: it internally probes each entity with ai_visibility_check and ranks results. It does not discuss rate limits or potential external API costs, but the disclosed delegation and scoring logic 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?

Three sentences with no fluff: the first states the core function, the second explains the method and output, and the third provides a real-world use case. Every sentence earns its place and key details are 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?

Even without an output schema, the description discloses the return format (ranked list with score, confidence, signal density per entity). It also explains the internal process and gives a practical scenario. Combined with full schema parameter documentation, it provides sufficient context for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add much beyond schema; it confirms entities are brand + competitors, but the schema already documents each parameter clearly. No extra meaning is provided for models, _apiKey, or context.

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

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

The description clearly states a specific action ('Compare AI visibility across multiple entities side-by-side') with a defined resource and scope. It distinguishes itself from sibling ai_visibility_check by emphasizing multi-entity comparison, ranking, and surfacing most/least recognized entities.

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

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

Provides clear context with a concrete example ('does Claude know about us as well as our competitors?') and frames it as a competitive AI-marketing audit. However, it does not explicitly mention when not to use this tool or name alternative tools like compare_entities, so it lacks exclusion 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses latency behavior ('first measurement on a new version can take 5-30s'), failure/degradation semantics ('sources_failed will list it if it times out, the rest still returns'), and the exact structure of the return value. No annotation contradiction exists.

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 every sentence carries useful information: core purpose, fan-out sources, use cases, ecosystem scope, return fields, and failure behavior. It is front-loaded with the primary action and remains efficient for the complexity of the tool.

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

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

Given there's no output schema, the description comprehensively lists return fields (summary block, advisory detail, links, alternative versions) and edge cases (new-version latency, partial failures). The ecosystem limitation and fallback guidance round out the contextual picture for an agent.

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

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

The schema already fully describes both parameters: 'package' is the npm package name and 'version' defaults to latest when omitted. The description does not significantly add new parameter semantics beyond what the schema covers, leaving the baseline of 3 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 opens with a specific verb+resource phrase: a composite check for whether to add an npm package, and explicitly names the data sources (deps.dev, bundlephobia) and the question it answers. It clearly distinguishes itself from sibling tools by focusing on npm dependency vetting rather than competitive scans or market 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?

It explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing direct when-to-use guidance. It also gives an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', pointing to an alternative path.

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 implementation details beyond the read-only annotation: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K character cap with truncation flagging, and the presence of offsets for verification. These details help the agent predict performance and failure modes, adding significant value over the annotation's mere read-only hint.

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

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

The description is front-loaded with the core purpose and is dense with useful information: use case, pairing, mechanism, and limits. Every sentence earns its place, though the density and length make it slightly less concise than the two-sentence gold standard. It remains highly readable and well-structured.

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

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

For a tool with no output schema, the description fully discloses the return format (top-N passages with character offsets and similarity scores) and the edge case of input truncation with a flag. It also explains how it integrates with the broader tool ecosystem (fetch with gateway, ground with ask_pipeworx_grounded). This is complete for effective selection and invocation.

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

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

The schema already covers all three parameters with examples, so the baseline is 3. The description adds contextual meaning by explaining the 'text' parameter as a previously fetched record (e.g., SEC 10-K, article) and clarifies the 'query' with concrete examples. It also mentions the truncation flag, which elaborates on the 'text' cap. Thus it exceeds the baseline slightly.

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

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

The description opens with a specific verb+resource: "Semantic search INSIDE a fetched record." It clearly distinguishes from siblings by explaining the use case (searching inside an already-fetched record) and explicitly pairs with ask_pipeworx_grounded as the complementary tool. This prevents confusion with other query-based 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?

It states when to use the tool: "when the record is too big to cram into the prompt." It also names the alternative workflow with ask_pipeworx_grounded, explaining the distinction between fetching and grounding. This gives the agent explicit decision criteria and compares against a sibling 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?

Description discloses auth prerequisites, delivery constraints (phone verification, 10/day cap), webhook signature details, auto-disable after consecutive failures, and one-time secret. It is consistent with annotations and adds significant context beyond readOnly/idempotent/destructive hints.

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

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

The description is dense but purposeful, with a clear topic sentence followed by type catalog and delivery details. It is longer than necessary for a simple tool, but here complexity justifies the compact format; no filler sentences.

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?

Description covers purpose, return value, auth requirements, subscription types with embedded parameter examples, delivery channels, and edge-case behavior (webhook disable, one-time secret). With no output schema, this provides a complete picture for an agent to invoke correctly.

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

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

Though input schema already documents all parameters, description enriches semantics with real examples (items:['5.02']=officer change), nested param shapes for each subscription type, and delivery caveats like 'must match verified phone' and 'auto-disabled after 10 consecutive failing runs'. This adds meaning beyond the schema's generic descriptions.

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

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

The description uses the strong action verb 'Create' with the resource 'proactive monitoring subscription' and states the return value (subscription id). It clearly distinguishes from siblings like list_subscriptions, unsubscribe, and read_feed by focusing on creation.

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

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

It explains when subscriptions can be created (requires Pipeworx OAuth account, excludes anonymous/BYO) and what types are supported with examples, but does not explicitly name sibling tools as alternatives. The guidance is clear enough for an agent to select this over list_subscriptions or unsubscribe.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: returns live-catalog-derived content with exact tool/argument shapes, and the parameter behavior. 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 fairly long but front-loaded with example queries and key info. Each sentence adds important detail, though some trimming of example enumeration could improve efficiency.

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 covers return values ('Returns category-bucketed example questions...'). Also covers parameter behavior and when to use. Complete for onboarding tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples ('finance', 'pharma', 'betting') and clarifies the effect of topic, adding value beyond the schema.

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

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

The description clearly states the tool's function with specific verbs: 'the onboarding entry point... Returns category-bucketed example questions... each with the exact tool + argument shape that answers it.' It distinguishes from siblings by focusing on question suggestions and learning meta-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?

Explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...' Also specifies when to pass topic vs no arguments.

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 substantial behavioral context beyond the annotations: it reveals ownership enforcement, that the row is deactivated rather than deleted, and that historical events remain available. These are non-obvious traits not captured by the annotations (readOnlyHint, destructiveHint, idempotentHint). The description is consistent with the annotations, 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?

Two sentences, front-loaded with the core action, followed by essential transaction details. No redundant words, no repetition of annotations, and every clause adds meaningful information. Excellent conciseness.

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

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

For a simple single-parameter mutation tool, the description covers the action, authorization boundary, and side effects (soft delete, historical data retention). With annotations providing safety and idempotency hints, and no output schema required, the description is sufficiently complete for an agent to invoke 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?

The input schema already fully documents the single parameter 'id' with a clear description ('Subscription id (uuid) returned by subscribe.'). The tool description merely restates 'by id' without adding new format, constraints, or behavioral details. Since schema coverage is 100%, the baseline of 3 applies, and there is no added value from the description.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It specifies the resource (subscription) and the operation (cancel), and the ownership enforcement distinguishes it from other subscription-related tools like subscribe or list_subscriptions. The purpose is 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: this is the tool to cancel a subscription you own. It explicitly notes ownership enforcement, which tells users they cannot cancel others' subscriptions. It also clarifies that cancellation is a soft delete, so historical events remain accessible via recent_alerts. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses crucial behavior: the fallback from structured SEC/XBRL to a grounded pipeline, and the precise meaning of ambiguous verdicts like could_not_verify (check didn't happen) vs unsupported (no source found). This is exactly the kind of practical behavioral context an agent needs to correctly interpret results, and it does not contradict the annotations.

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

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

The description is longer than average but well-structured: it opens with recognizable trigger phrases, states the use case, explains the two processing paths, lists the verdicts, and clarifies error semantics. Each section earns its place, though the prose could be tightened to reduce redundancy (e.g., the grounded pipeline explanation is repeated).

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

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

For a tool with no output schema, the description covers everything needed: the decision logic (which path is taken), the complete set of verdicts, what the return value carries (actual value with citation, reasoning), and how to treat failure cases. It also notes the tool's composability by replacing multiple calls, so the agent understands the full scope and side effects. No significant informational 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?

The input schema already describes both parameters fully (100% coverage), but the description goes further by explaining the semantics of tolerance_pct in use: how it overrides the claim-wording default, is capped at 5, and should be set to 1–2 for hallucination detection. This adds meaningful guidance beyond the schema's field 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 identifies the tool as a claim-verification utility, with specific verb+resource ('validate claim') and a host of natural-language trigger phrases. It also differentiates from generic research tools by noting it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison), making its scope 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?

It explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the two internal paths (SEC fast path for company financials, grounded pipeline for anything else), giving clear context. However, it never mentions when not to use it or names alternative sibling tools, so it lacks explicit exclusion/alternative guidance.

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