Business Feeds

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

Annotations already establish readOnly/idempotent/non-destructive, so the description's added value is the cost implication ('you pay Anthropic directly') and default model selection, plus the explicit per-model return shape. This goes beyond the structured annotations without contradicting them.

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 tightly-packed sentences: core action, model/cost caveat, and return format + use cases. Front-loaded with the most important information and zero 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?

Despite lacking an output schema, the description names the exact per-model fields (score, confidence, signals, raw_response) and combined view, plus practical use cases and cost behavior. Together with full schema coverage and read-only annotations, this is complete 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?

With 100% schema coverage, the baseline is 3; the description adds meaningful context by naming the default model (Workers AI Llama-3.3-70b) and explicitly linking _apiKey to cost and the 'anthropic' models option. This gives the agent a better mental model of how the parameters interact.

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 pairing: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx or deep_research, and the inclusion of return format and use cases leaves no ambiguity.

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 usage context via 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring' and explains the model/cost tradeoffs (default free Workers AI vs. BYO-key Anthropic). It does not explicitly state when not to use it or name alternatives, but the context is sufficient for an agent to select it for visibility checks.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, and the description adds significant behavioral context: it routes to sub-tools, fills arguments, returns structured answers with pipeworx:// citation URIs, works on every tier, and is one fast call. It also implies limitations by recommending ask_pipeworx_grounded when hallucination resistance is needed. 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 earns its place: it front-loads the key instruction ('PREFER OVER WEB SEARCH'), gives concrete examples, and provides alternative tool guidance. It is well-structured and avoids repetition 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 complexity (a router over 5,462 tools) and lack of an output schema, the description fully compensates by explaining the return format (structured answer with citation URIs), covering edge cases like breaking news, and specifying when to step up to alternatives. Complete for an agent to use correctly.

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

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

Schema coverage is 100% (all six parameters are aliases for the single question field). The description enriches parameter understanding by listing example questions and categories of factual queries, and clarifies that aliases are accepted. This goes beyond the bare schema description, though the parameter is simple and could rely on schema alone.

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

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

The description clearly states the tool's function: it routes questions to 5,462 tools across 1419 verified sources, fills arguments, and returns structured answers with citation URIs. This is a specific verb+resource description that distinguishes it from sibling tools like ask_pipeworx_grounded and deep_research by positioning it as the default entry point.

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

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

Explicitly says to prefer this over web search for a specific list of domains and trigger phrases. It also gives explicit when-not-to-use guidance by naming alternatives: ask_pipeworx_grounded for hallucination-resistant single answers with verbatim evidence, and deep_research for broad/multi-part questions. This is exactly the kind of clear selection criteria the dimension asks for.

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 the experimental nature, notes that no candidate is currently active so it 'matches ask_pipeworx exactly,' and clarifies it 'Falls back to nothing — this IS a full working router.' This adds meaningful context about live behavior and current equivalence, though it could mention potential future changes more explicitly.

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 dense sentences with no filler. Front-loaded with the beta identity and core function, then quickly covers equivalence, usage, and fallback behavior. Every sentence earns its place.

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

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

For a router tool with no output schema and a complex domain (5,462 tools), the description adequately covers what it is, its current state, how to use it, and what to expect (same response shape). It is self-contained for tool selection and invocation.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question.' The description does not add further parameter meaning beyond noting 'same arguments' as ask_pipeworx, which is redundant with the schema. Baseline 3 is appropriate since the schema fully carries parameter semantics.

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

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

Description clearly states the tool is a 'universal router' with the same 5,462 tools as ask_pipeworx, and distinguishes itself as the 'Beta version' with 'candidate routing improvements enabled live.' This gives a specific function (routing questions) and resource scope, differentiating it from the stable ask_pipeworx sibling.

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 it exactly like ask_pipeworx when you want the newest routing.' It also names the alternative (ask_pipeworx) and clarifies that results are compared against the stable router — defining both when and why to use this beta variant.

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, openWorldHint, destructiveHint:false), the description discloses the exact return contract, including success fields and five explicit refusal reasons. It also reveals the cost tradeoff (one extra LLM call) and the grounding principle ('EXTRACTS the answer using ONLY what the tool result contains'). This richly complements the annotations without contradicting them.

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 longer than typical, every sentence earns its place: it defines the mode, explains routing and extraction, details return and error structures, gives use cases, and states the cost tradeoff. It is front-loaded with the core purpose and uses dashes to structure the flow. 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?

Despite having no output schema, the description fully specifies the return shape and possible refusal reasons. It covers behavioral nuances (one extra call, grounding, alias handling), application context (high-stakes reads), and distinguishes from the sibling. For a tool with a single parameter and strong annotations, this description leaves no critical gaps.

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

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

Schema coverage is 100% because the only required parameter (question) and its aliases are fully described. The description does not add extra semantics about parameter format, values, or constraints beyond what the schema provides. Baseline 3 is appropriate since the schema already carries the parameter documentation burden.

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', using a specific verb ('answer') and resource ('Pipeworx'). It clearly distinguishes from sibling ask_pipeworx by highlighting the grounded extraction process, explicit refusal handling, and additional LLM call cost. This makes the tool's unique role unmistakable.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative and states the preference: 'prefer ask_pipeworx for casual lookups'—a clear exclusion criterion.

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

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

Annotations already convey read-only/open-world/idempotent behavior, but the description adds extensive context: resolver contract with market_match_confidence/score/alternatives, low-confidence short-circuiting, closed-market handling, wide-spread illiquidity warnings, parent_event extraction, news fallback behavior, and resolution-rule risk (including flat-50¢ void settlements). It also details blocking routes and suppressed fields, going far beyond the safety profile implied by annotations.

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

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

The description is long but well-structured, using clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) and front-loading the core purpose. Most sentences add operational value, though some redundancy exists (e.g., repeated explanation of blocking routes for closed markets) that could be trimmed for 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?

With no output schema, the description carries full responsibility for explaining return values and edge cases. It thoroughly documents response shapes (result.market, result.analysis, result.evidence), status codes (low_confidence_match, market_closed_or_inactive), the resolver contract (match confidence, score, alternatives), parent_event extractor, news fallback fields, and cancellation-rule risk. It covers both normal and failure modes, making it operationally complete for an agent.

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

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

Schema description coverage is 100%, so all parameters (market, depth, include_raw) are already fully documented with descriptions and defaults. The tool description reinforces the market parameter's accepted formats and mentions depth-related fan-out, but it does not add substantial new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the action ('Research a Polymarket bet'), the resource (a specific market), and the mechanism ('pulling the relevant Pipeworx data... in one call'). It distinguishes this tool from siblings like polymarket_edges by focusing on a single bet and providing category-specific data packs, with concrete input examples (slug, URL, question text).

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 when-to-use guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives detailed fan-out examples. However, it does not explicitly name alternative tools or state when not to use it (e.g., for multi-market scanning), so it stops 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 this as read-only and idempotent, but the description adds substantial behavioral context: off-calendar fiscal years are handled correctly, results are sorted by primary metric, and output includes paired data plus citation URIs. This goes beyond the safe-profile hints and gives valuable operational detail.

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 delivers value: examples, preference rule, data sources, sorting, and output format. It is front-loaded with the core capability and avoids filler or repetition. The length is justified by the breadth of behavior it must convey.

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 the essential context: what it does, when to use it, what data it retrieves per type, how results are sorted, and what the response includes (paired data + citation URIs). It leaves little to guess about the tool's operation and output.

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

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

Schema coverage is 100% with clear param descriptions, but the tool description adds even more: examples of valid values (['AAPL','MSFT'], ['ozempic','mounjaro']), what each type pulls, and constraints like max 5 min 2. This significantly enhances the bare schema and directly guides usage.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, and lists concrete user query examples. It distinguishes itself from siblings like entity_profile or resolve_entity by emphasizing parallel comparison vs. sequential lookups, and names specific data sources (SEC EDGAR, FAERS).

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', establishing a strong usage directive. It also differentiates behavior by type ('company' vs 'drug') and notes it replaces 8–15 sequential lookups, giving clear when-to-use context.

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

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

The description goes far beyond the annotations, disclosing the parallel decomposition strategy, the return packet (verbatim evidence, confidence, source, citations, gaps[], contradictions[]), the hop field, fetchable citation_uri, semantic excerpting (not head-truncated), and expected latency (15-90s). It also clarifies that it is NOT open-web search, which is a critical behavioral constraint not captured by annotations. No contradictions with annotations found.

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

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

Despite being long, the description is densely packed with useful information and front-loaded with the critical account requirement. Each sentence serves a distinct purpose: prerequisites, core capability, differentiation, execution model, output format, depth semantics, and performance expectations. No 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 complex research tool with no output schema, the description covers all necessary operational details: what it returns, how citations work, when gaps will appear, what depth modes do, latency, and when to choose an alternative. The presence of rich annotations plus this highly detailed description makes the tool fully self-contained for agent selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra context beyond the schema by explaining the implications of depth levels (e.g., 'standard' re-angles unanswered gaps, 'thorough' adds follow-up and contradictions scan) and the paid requirement for 'thorough.' This enriches parameter understanding beyond the enum 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 a specific verb+resource combination: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call.' It explicitly distinguishes itself from siblings by noting 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' This is a precise, unambiguous purpose statement.

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: 'Best for broad/multi-part questions over structured data' while explicitly excluding single lookups and breaking-news scenarios and naming the alternative tool (ask_pipeworx). Also notes the account prerequisite and paid-tier requirement for 'thorough' depth, which are useful context for selecting the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context beyond this: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states 'no second schema lookup needed.' This tells the agent what to expect from the response and saves an extra call. No contradictions with annotations.

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

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

Description is four sentences, each earning its place: purpose, usage, return behavior, and ordering cue. The domain list is long but informative. No redundant phrases or irrelevant details. Properly front-loaded with the core verb.

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 discovery tool with rich annotations and full schema, the description is complete enough. It explains what the tool returns (top-N tools with schemas and examples), which is the main missing piece without an output schema. It does not cover error handling or pagination, but those are not critical here. The overall context is sufficient 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 description coverage is 100%, so the schema already documents all parameters (query, aliases, limit) in detail. The description adds minimal extra meaning beyond mentioning 'top-N' which maps to the limit parameter. This aligns with the baseline for high schema coverage.

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

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

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and enumerates many domains (SEC filings, FDA drugs, etc.), which distinguishes it from siblings like deep_research or validate_claim. The action 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?

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' The phrase 'not just one answer' implies a when-not, but no specific alternative tool is named. This is strong, though not perfectly explicit about 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 strong annotations (readOnly, openWorld, idempotent, non-destructive), the description adds critical behavioral detail: USPTO API sunset soft-fail, GDELT→GNews fallback, data source fan-out, and URL formats. This goes well beyond the annotations, enriching the agent's understanding of what happens when invoked.

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

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

The description is somewhat long but front-loaded with trigger phrases and a clear purpose statement. Each sentence conveys unique info (return fields, limits, fallbacks, prerequisites), so the length is justified for a complex tool. Minor redundancy in the example list prevents a 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 enumerates all key return components (cik, recent_filings with URIs, fundamentals fields, patents, news, LEI). It also notes limitations and data source nuances. Small gaps like exact counts for news/patents keep it from a 5, but it's largely complete for the agent to set expectations.

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 good descriptions, and the description adds further value by giving concrete examples (ticker 'AAPL', zero-padded CIK '0000320193'), reinforcing the 'names not supported' constraint, and linking to resolve_entity. This exceeds the baseline for full schema coverage.

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

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

The description uses a clear verb phrase ('full cross-source profile') and lists specific return fields, distinguishing it from siblings like resolve_entity and compare_entities. It also includes trigger examples that make the tool's function immediately identifiable.

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 prefer this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to (names not supported, use resolve_entity first). This provides clear alternatives and contextual triggers.

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, so the safety profile is covered. The description adds meaningful behavioral context: 'CF-robust: fetches directly and falls back to a proxy if the source blocks the gateway.' This explains network resilience behavior and normalization, which are not inferable from annotations. It stops short of describing return structure or error handling, but given annotation coverage, this is sufficient.

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

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

The description is two sentences: the first states purpose and scope, the second adds usage guidance and a resilience behavior. Every word earns its place, with no filler or repetition of schema/annotation content. The front-loaded verb 'Fetch' immediately signals the tool's action.

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

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

For a tool with only three parameters (all documented) and strong annotations, the description provides sufficient context: what it fetches, how it handles network failures, and a recommended workflow. It does not mention the return format, but there is no output schema, and the behavior of 'normalize' hints at content processing. The only notable gap is not addressing the sibling read_feed, which might be a natural alternative for already-listed feeds, but the guidance to use list_feeds first partially mitigates this.

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 three parameters (url, limit, query) have descriptions in the schema. The description itself adds no parameter-specific information beyond the schema; it only mentions normalization and proxy fallback, which are tool-level behaviors. Therefore, the baseline of 3 is appropriate; the description does not need to compensate for schema gaps.

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 verb-object pair: 'Fetch and normalize any RSS / Atom / RDF feed by URL.' It immediately conveys the tool's scope (any feed format) and its core action (fetching and normalizing). The phrase 'any RSS / Atom / RDF feed' distinguishes it from sibling tools like list_feeds, which is explicitly referenced, and read_feed, which likely has a narrower purpose.

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

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

The description provides a concrete workflow hint: 'Use list_feeds first for curated sources.' This tells the agent when to call list_feeds before fetch_feed, implying that fetch_feed is for arbitrary or unsourced URLs. However, it does not explicitly mention when to prefer read_feed or other alternatives, and the exclusion is implicit rather than stated as a hard rule.

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

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

Annotations already convey destructive and idempotent hints. The description adds that the deletion targets a 'previously stored memory' and is useful for clearing sensitive data, which provides useful context about the operation's effect 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 two sentences, front-loaded with the core action, and every sentence contributes either the operation, usage context, or related-tool guidance. 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?

For a simple single-parameter delete tool with strong annotations (destructive, idempotent), the description plus schema fully cover the tool's purpose, usage, and behavioral context. No output schema is necessary for such an operation.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete.' The description adds minimal semantic value beyond the schema, only reiterating that deletion is by key. 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 a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember and recall, which store and retrieve memories 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 explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names the complementary tools (remember and recall) to provide context on the workflow.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description goes further by detailing the process (fetches the page, extracts content, emits markdown) and output format. This adds behavioral context without contradicting annotations, though rate limits or failure modes are not mentioned.

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 uses four sentences to convey the primary action, process, output format, and use cases. It is front-loaded with the key purpose, every sentence provides value, and there is no unnecessary verbosity.

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

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

With no output schema, the description explicitly states the return value is a single text blob ready to drop at site-root/llms.txt. It also covers the workflow and use cases, making it fully complete for a simple two-parameter tool.

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

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

Schema description coverage is 100% for both parameters (url and max_links), each with clear descriptions. The tool description itself adds no additional parameter-level detail, so the baseline of 3 applies.

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: generating a production-ready llms.txt file for any URL, with specific process details (fetches, extracts title/description/key links, emits standard markdown). It distinguishes itself from sibling tools by focusing on producing the llms.txt format, despite potential overlap in competitor auditing.

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

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

Provides explicit use-case scenarios ('getting a client's site indexed by AI, drafting for own project, auditing how an AI crawler would see a competitor'), which imply when to use it. However, it does not explicitly mention alternatives or when-not-to-use, so it stops 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations by specifying the return fields, the curated nature of feeds, and the intended workflow of passing ids to read_feed. It doesn't mention pagination or rate limits, but it's not a gap given the simple read-only nature.

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

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

The description is extremely concise—two sentences—with the core purpose front-loaded. The second sentence efficiently covers optional filters and the next-step pointer to read_feed. Every word earns its place, with no redundancy or fluff.

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

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

For a simple list tool with rich annotations and no output schema, the description is complete: it states the resource (curated feeds), the returned fields, the two filters, and what to do with results. It lacks pagination or ordering details, but those are not essential for a basic list operation.

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 only restates the category values and keyword filter, adding no new parameter-level meaning beyond what the schema already provides. It does mention returned fields, but that's not parameter semantics.

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

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

The description clearly states the tool lists curated business/industry feeds and specifies the returned fields (id, title, category, source), making its purpose unambiguous. It also distinguishes from siblings by explicitly pointing to read_feed for a single 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 gives direct usage guidance: optionally filter by category or keyword, and then pass an id to read_feed for full content. It doesn't explicitly contrast with sibling tools like list_subscriptions or fetch_feed, but the read_feed pointer provides a clear next step and a basis for choosing this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds the return field names (id, type, params, created_at, last_fired_at, fire_count) and clarifies the scope to the caller's subscriptions, providing context beyond the annotations.

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

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

Two sentences, front-loaded with the verb and resource, followed by return fields and usage guidance. No redundant information.

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

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

Given a simple read-only list tool with no output schema, the description covers the return format and typical use cases, and the annotations cover safety. This is sufficient for agent 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 describes the single parameter include_inactive with 100% coverage, so the description need not elaborate. The description's mention of 'active subscriptions' indirectly relates to the parameter, but the schema fully carries the semantic weight.

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 specific verb 'List' with a clearly defined resource ('the caller's active subscriptions') and explicitly states the returned fields, distinguishing it from sibling tools like subscribe/unsubscribe and list_feeds.

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 explicit use cases: 'before adding more' subscriptions and 'to find an id to cancel', telling the agent when to invoke it. However, it doesn't name alternative tools directly, so it's slightly less explicit than ideal.

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

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

All annotations are false/neutral, so the description carries full responsibility. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota behavior ('doesn't count against your tool-call quota'), and operational context ('team reads digests daily and signal directly affects roadmap'). 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 ~150 words, longer than minimal, but every sentence earns its place: purpose, when-to-use, exclusions, message guidance, and operational facts. It is front-loaded with the core purpose and logically structured, though it could be tightened.

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 3-param tool with a nested optional context object and no output schema, the description covers all essential invocation context: acceptable categories, scope boundaries, message content constraints, rate limits, and quota treatment. Nothing critical is missing.

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

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

Schema already provides 100% coverage with enum descriptions for type and field descriptions. The description adds non-schema guidance: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' (informs message content) and the 'Not sure' heuristic for identifying scope. This meaningfully elevates 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 verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the feedback categories (bug, feature/data_gap, praise), clearly distinguishing this from sibling research/feed/subscription 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 triggers are stated: '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 for tools from other MCP servers, directing users to 'file it with that server instead,' plus a disambiguation rule for identifying Pipeworx tools.

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

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

Annotations already declare the tool read-only, open-world, and idempotent. The description adds valuable behavioral context beyond these: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This discloses data origin, privacy guarantees, and caching behavior, which are important for an agent to understand the freshness and trustworthiness of the data. No contradictions with annotations.

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

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

The description is three sentences long, front-loaded with the core purpose. The second sentence presents clear, bullet-like use cases. The final sentence provides technical caveats (data source, PII, caching) without fluff. Every sentence contributes meaning and there is no redundant information.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains what is returned, the time windows, additional use cases, data provenance, and caching behavior. An agent can confidently decide when to invoke this tool and what to expect from the 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?

The input schema already covers the 'window' parameter with an enum and a description (100% coverage). The description adds meaningful interpretation: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema's literal enum values and helps the agent choose the right window for its context. Since schema coverage is high, this extra semantics elevates the score above 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 opens with a specific, informative statement about what the tool does: 'What other AI agents are calling on Pipeworx right now.' It clearly states the outputs ('top tools, top packs, and total call volume') and the timeframe ('24h, 7d, or 30d'). This clearly distinguishes it from sibling tools like discover_tools, which likely focuses on listing available tools rather than aggregated usage trends.

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

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

The description provides explicit use cases: 'discovering what data sources are hot for current events,' 'confirming a popular tool is the canonical choice before asking your own question,' and 'seeing whether your use case aligns with what most agents need.' While it doesn't name alternative tools for when not to use it, the use cases give clear situational guidance. Lacks explicit exclusionary guidance, thus not a 5.

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

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

Annotations only indicate read-only, open-world, idempotent, non-destructive. The description goes far beyond: it explains the default top-200 market scan, the Jaccard similarity threshold (0.30), placeholder slug filtering behavior, and the fill-check mechanism against live CLOB depth. It also discloses edge cases like thin_legs and when a signal is not tradeable.

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 extremely well-structured: purpose and mode guidance upfront, then labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence contributes technical or behavioral value, but the density and length make it slightly less concise than a minimal description would be.

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?

There is no output schema, yet the description fully explains the response shape (`opportunities[]` with fields, `partition_check` in event mode) and the fill-check result fields. It also covers semantic filtering, placeholder edge cases, and actionable guidance on when not to trade, making it completely 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?

The schema already covers `event` and `topic` with clear descriptions (100% coverage), so the baseline is 3. The description adds the crucial no-args default and elaborates on the operational behavior of each mode (walks child markets, computes partition_check, etc.), which justifies a score above baseline but not 5 since the schema does a lot of the work.

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 first sentence states the exact purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It uses a specific verb, resource, and method, and distinguishes three modes (trending_scan, event, topic), clearly separating it from siblings like polymarket_edges and polymarket_fill_risk.

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 instructions: call with NO args for trending_scan, pass `event` for a specific market, or `topic` for cross-event scanning. It also names an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk') and warns against trading when realizable_edge_pp ≤ 0.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, establishing safety. The description adds substantial behavioral context: output structure (by_segment, diagnostics), edge calculations (net of slippage, Kelly caps), caching (1h KV keyed on knobs), and caveats (e.g., Fed signal unreliability, rare-by-design concentrated longshots). This goes well 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 long but information-dense, with clear section markers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Every sentence adds value and avoids fluff. It could be more scannable with bullet points, but the structure is effective 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?

With no output schema, the description thoroughly specifies return format: by_segment segments, fed_candidates/fed_note, _diagnostics with funnel counters and filter_skips. It also covers empty-segment explanations, edge cases (placeholder-slug filters, partitions with >20% placeholder), and the 24h-move warning. Complete for a complex tool with 9 params.

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 semantic value by grouping parameters (TRADEABLE-EDGE KNOBS) and explaining subtle behavior: e.g., min_partition_leg_kelly applies to per-leg Kelly not parent, and partition arbs always return kelly_fraction_half=0, so min_kelly doesn't filter them. This enriches understanding beyond the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and distinguishes it from siblings by focusing on current opportunities and Pipeworx disagreement, not generic market data or arbitrage.

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

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

The description explicitly states the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides guidance on knobs (e.g., min_liquidity, max_spread_pp) to filter tradable edges. However, it does not explicitly mention alternative tools or when not to use it, though the context of siblings is clear.

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

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

Beyond the annotations (readOnly, idempotent, not destructive), the description discloses significant behavioral details: the 60-day snapshot TTL, that snapshots are written on cache-miss and gaps mean no scan, that decay is based on daily closes rather than intraday, and that edge_pp_net is signed (negative = SELL YES). This is exactly the kind of context an agent needs.

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

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

The description is long but well-structured with clear sections (purpose, args, response, limits). Every sentence carries operational value, but it could be tightened slightly without losing information. Still, the structure compensates for length.

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

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

With no output schema, the description fully documents the response object: tracked[] with time-series and trend/decay fields, expired[] with lifespan_days, and snapshot_dates[] with gap semantics. It also covers data limitations and the meaning of derived metrics, making it highly complete for a tool of this complexity.

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

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

Both parameters are already fully described in the input schema (days lookback with clamp 2-30, window family enumeration). The description's Args section simply repeats these defaults and meanings, adding no new semantic value. Since schema coverage is 100%, 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 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly answers 'how long has this edge existed and is it shrinking?', clearly distinguishing it from the sibling polymarket_edges tool. It names the specific resource (snapshot history) and the analytical operation (tracking edge persistence/decay).

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

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

The description provides a clear use case: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)' and explains that it reads historical snapshots. However, it does not explicitly name alternative tools or state when NOT to use it, so it lacks 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds substantial behavioral context beyond annotations: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), identifies forced_directional_risk, and explains that basket fills can strand the user unhedged. This is rich, non-obvious behavior that is essential for safe invocation.

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

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

The description is long but well-structured with labeled modes (SINGLE-MARKET, BASKET), a clear first-sentence purpose, and a final usage warning. Every section adds value, but the length is substantial and could potentially be trimmed by removing some output-field enumeration, especially since no output schema exists to cover it. Still, the structure is excellent and front-loaded.

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

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

The tool is highly complex (two modes, no output schema, safety-critical usage). The description fully covers return values for both modes, parameter semantics, mode selection prerequisites ('REQUIRES one of market or event'), and risk context. Given the absence of an output schema, the description carries the burden of explaining outputs, and it does so thoroughly. It is 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?

Schema description coverage is 100%, so baseline is 3. However, the description adds significant mode-dependent meaning: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode but 'settlement notional S (shares per leg)' in basket mode. It also explains the default side behavior in basket mode ('auto — sell if partition sum > 1, buy if < 1'). This goes well beyond the schema's generic parameter descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly defines both single-market and basket modes, and distinguishes itself from siblings by explicitly naming polymarket_arbitrage and polymarket_edges as tools that should be preceded by this check.

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 explicitly prescribed: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides a rationale (theoretical overround on thin books is not capturable) and warns about the dominant loss mode (partial fills convert an arb into a directional position), giving clear when and when-not 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, idempotentHint, and destructiveHint:false, and the description adds substantial behavioral detail: compatibility_warning firing conditions (matched_pairs:0 with skipped_cross_type>0 vs both venues >5 legs), temporal_alignment semantics, and skipped_cross_type/subtype counters. It also states that aligned:false makes spreads mathematically meaningless, giving the agent a clear model of tool behavior.

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

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

The description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. It is dense with parenthetical clarifications but every sentence adds value; it could be tightened but the length is justified by the tool's complexity.

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

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

There is no output schema, so the description must explain the return values, and it does: leg-by-leg prices, matched spread top_spreads_pp, compatibility_warning logic, temporal_alignment, and skip counters. For a read-only tool with 3 optional parameters and no required fields, this is complete and actionable.

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% parameter description coverage, so the baseline is 3. The description adds meaning beyond the schema by listing the exact topic enum values, explaining that explicit ticker/slug override the topic-mapped side, and providing concrete examples like 'KXFED-26OCT' and 'fed-decision-in-june-825'.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly identifying the tool computes the price difference between two venues for the same event. It further clarifies the two modes (topic shortcuts vs explicit ticker/slug), making the tool's purpose distinct from siblings like polymarket_arbitrage.

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

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

The description gives explicit guidance on when to use topic shortcuts versus explicit kalshi_event_ticker and polymarket_event_slug, including override behavior. It also warns that most pre-mapped topics return compatibility_warning and 'pre-mapped ≠ tradeable', setting expectations, though it does not name alternative tools or explicitly say when NOT to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that it returns normalized items (title, link, published, summary) and supports optional keyword filtering, which is useful context. However, it doesn't disclose more nuanced behavior like pagination or error handling, so it matches the baseline for annotation-covered safety.

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 main action, and every clause adds value. It states the input requirement, output format, and an optional behavior without any 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?

For a simple read tool with 3 params and no output schema, the description adequately covers the return format and basic functionality. The limit parameter is detailed in the schema, so the description doesn't need to repeat it. It is nearly complete, though it could mention that the feed id must come from list_feeds (which it does) and perhaps clarify that the tool is safe to call multiple times (but that's in annotations).

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds only marginal meaning by saying 'by its id (from list_feeds)' for the feed parameter, but it doesn't add detail beyond what the schema provides. The schema's description of query ('Keyword filter over item title/summary') is actually more specific than the tool description's 'filter items by keyword', so no extra value.

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

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

The description clearly states the tool's purpose: 'Read a curated business & industry feed by its id'. It uses a specific verb ('Read') and names the resource (feed) and context (curated). However, it does not explicitly differentiate from sibling tools like fetch_feed, so it doesn't fully earn a 5.

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 by referencing list_feeds as the source of the id, which is a prerequisite. It does not explicitly state when to use this tool vs alternatives or provide exclusions. This is implied usage rather than clear guidance, so it falls short of a 4.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond those: scoping to the user's identifier ('anonymous IP, BYO key hash, or account ID') and the behavior of omitting the key to list all saved keys. 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 three sentences, each earning its place: the first states the core action, the second gives concrete use cases, and the third covers scope and pairing with sibling tools. No wasted words and the main purpose 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?

This is a simple tool with one optional parameter. The description covers purpose, behavior (list vs retrieve), scope, and sibling relationships. With annotations covering safety, and no output schema needed for such a straightforward lookup, the description is fully adequate.

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

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

The input schema already covers the single 'key' parameter with a description that includes the omit-to-list behavior, giving 100% schema coverage. The description reinforces this with examples and clarifies the parameter's role, but adds no syntax or format details beyond the schema, so baseline 3 is appropriate.

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

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

The description begins with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes itself from sibling tools like remember and forget by stating the read/lookup role and even names its counterpart 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 states when to use it: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also references sibling tools ('Pair with remember to save, forget to delete') to guide selection among alternatives, though it does not explicitly state when not to use it.

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

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

The description discloses important behavioral details beyond annotations, such as the mark_read:true side effect (flags events as read) and the feed's persistence. Annotations already cover read-only/idempotence, and the description adds nuance 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 concise, front-loaded with the core action, and packs useful detail into just three sentences. It includes return payload info, filtering options, mark_read behavior, and an alternative endpoint, with zero waste.

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

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

For a read-oriented tool with complete schema annotations, the description covers purpose, behavior, output fields, filtering, and alternative access. No output schema exists, but the description adequately describes the return content. It is complete.

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

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

Schema coverage is 100%, with all five parameters clearly described. The description mentions filtering by type and since but adds no extra semantic depth beyond the schema, 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 clearly states the tool 'Pull fired events from your subscription feed' and specifies it returns 'the most recent alerts' with details like source and citation_uri. It distinguishes from siblings by focusing on persistent feed alerts written by the evaluator, not generic feed reads.

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 clear context for when to use this tool ('Polls work fine') and mentions an alternative HTTP endpoint for scripts/dashboards. It doesn't explicitly exclude sibling tools like read_feed, but the usage context is strong enough for an agent to choose appropriately.

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

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

The description discloses rich behavioral detail beyond the annotations: fan-out to multiple sources (SEC EDGAR, GDELT/GNews with fallback logic), soft-fail behavior for USPTO due to PatentsView sunset, and parallel execution. It also describes the return structure (changes[] grouped by source, total_changes count, citation URIs).

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, front-loaded with query examples. Every sentence adds value (sources, fallback, return format, alternative). It is slightly long but appropriate 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?

For a tool with no output schema, the description thoroughly explains return values, source integration, edge cases (rate limiting, soft-fail), and temporal parameter syntax. It 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?

Schema coverage is 100%, so the baseline is 3. The description adds some context about the 'since' parameter (ISO or relative shorthand) but this largely duplicates the schema's own description. No significant new parameter semantics are introduced.

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, with explicit query examples ("What's new with X", "updates on Acme"). It distinguishes itself from the sibling entity_profile tool by explicitly naming the alternative for static profiles.

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

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

The description provides explicit when-to-use guidance through user-intent examples and states when NOT to use it: 'Use entity_profile instead when you want the static profile...'. This is a clear alternative, fulfilling the usage guidelines criterion.

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 idempotentHint and destructiveHint annotations, the description adds meaningful behavioral context: key-value pairing, scoping by identifier, persistence differences between authenticated and anonymous sessions, and retention window (24h).

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 efficiently pack purpose, usage, storage model, retention, and sibling relationships—no wasted words.

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

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

For a simple write operation, the description is complete: it specifies when to use, how data is stored, how long it persists, and related tools, covering everything an agent needs 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 covers both parameters fully (key, value) with examples. The description doesn't add significantly to parameter semantics, so baseline 3 applies.

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 action ('Save data the agent will need to reuse later'), clearly defines the resource (data across conversations/sessions), and differentiates from siblings by explicitly referencing recall and forget.

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

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

It explicitly tells when to use ('Use when you discover something worth carrying forward') and names complementary/alternative tools ('Pair with recall to retrieve later, forget to delete').

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds substantial context: internal cascading through multiple endpoints, auto-disambiguation, exact return fields for each type, and citation URIs. This gives the agent a clear behavioral model 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 well-structured with a front-loaded purpose, 'Use FIRST' instruction, and SUPPORTED TYPES breakdown. It is slightly long and repeats some input-form details already in the schema, but every section provides useful 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?

With no output schema, the description compensates by specifying return payloads for both company and drug types, including fields and citation URIs. It also covers both parameter variants and type-specific behavior, making the tool fully usable from the description alone.

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 both parameters, and the description adds rich semantic detail: per-type accepted input forms (ticker, CIK, or name; brand or generic), concrete examples, and distinct returned fields. This fully instructs the agent on how to fill and interpret each parameter.

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

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

The description opens with concrete user-phrased queries and explicitly states the core function: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' This clearly distinguishes resolve_entity from sibling tools like entity_profile or compare_entities by positioning it as the prerequisite lookup 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 description says 'Use FIRST whenever you have a name but need an ID,' giving explicit guidance on when to invoke it. It also justifies usage by noting the tool replaces 2-3 manual lookups, but it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds meaningful behavioral detail: it probes each entity via ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond structured annotations without contradicting them.

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 earning its place: main action, process detail, and use case. No redundant phrasing. The description is 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 annotations covering safety and schema covering all parameters, the description fills the remaining gap by explaining the output format (ranked list with score, confidence, signal density) and the sub-tool used. This is complete for a read-only comparison tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'your brand + N competitors' which aligns with the entities parameter, and 'per probe' hints at models/_apiKey usage, but it doesn't add significant meaning beyond what the schema already documents. The schema carries the parameter-semantics burden.

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: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes itself from the sibling ai_visibility_check by explaining that it probes each entity with that underlying tool and then ranks results. This makes the tool's 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?

The description provides a clear use case: competitive AI-marketing audits, with an example query. It implies this is the multi-entity comparison variant of ai_visibility_check, but does not explicitly name alternatives or state when not to use it. Still, the usage context is clear enough.

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

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

Annotations already indicate read-only/idempotent behavior. The description adds substantial context beyond that: it fans out to two external services, may take 5-30s on first bundlephobia measurement, degrades gracefully on partial failures, and lists sources_failed behavior. This is rich behavioral 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?

Although longer than average, every segment earns its place: purpose, trigger cases, return fields, ecosystem limitation, and failure behavior. It is front-loaded with the core purpose and flows logically, 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?

Given the absence of an output schema and the tool's composite nature, the description fully covers inputs, outputs, external dependencies, latency, failure modes, and ecosystem constraints. An agent has enough information to invoke it appropriately and interpret results.

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

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

Schema coverage is 100% for both parameters, and the schema already describes package names, scoped support, and version defaulting. The description does not add meaningful parameter semantics beyond the schema, 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 specific verb and outcome: a composite 'should I add this npm package to my project' check in ONE call. It clearly distinguishes itself from sibling tools by naming its data sources (deps.dev and bundlephobia) and the exact metrics returned.

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 explicit trigger phrases ('is X safe / popular / small', 'what does adding lodash cost me') and explicit exclusions ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This answers when to use it and when not to.

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

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

Discloses return format (passages with offsets and similarity scores), embedding model (BGE-base-en), chunking (500-char overlapping windows), and the 200K char cap with truncation flagging. All of this exceeds the readOnly/idempotent hints and adds valuable behavioral context.

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

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

Three focused sentences, each earning its place. The first sentence captures the core action, the second adds usage context, and the third gives technical details. 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?

For a tool with 3 params and no output schema, the description fully covers the return format, edge cases (truncation), and integration with a sibling. The agent can confidently select and invoke the tool without ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the truncation behavior for the text parameter and the nature of the query with practical examples, plus the offset-based verification benefit.

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

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

The description clearly states the tool performs semantic search inside an already-fetched record, distinguishing it from sibling tools like ask_pipeworx_grounded. It gives concrete examples (SEC 10-K, article, tool result) and emphasizes 'INSIDE' to signal scope.

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 to use when the record is too big to cram into the prompt, and pairs with ask_pipeworx_grounded for a fetch-then-ground workflow. This provides clear when-to-use and alternative guidance.

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

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

The description adds extensive behavioral detail beyond the annotations: requires a Pipeworx OAuth account (anonymous cannot persist), returns subscription id, delivery channels with phone verification and daily cap, webhook auto-disable after 10 failures, and one-time signing secret. This exceeds the baseline provided by readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and contradicts none.

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 then details types and delivery. It is dense but each sentence provides necessary operational detail. However, it is a bit long and could benefit from bullet points, but it does not waste words. The omission of two supported types (patent_grant, clinical_trial) from the list is a minor structural issue.

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

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

For a complex tool with nested objects and multiple types, the description covers most aspects: authentication, return value, delivery options, and specific examples. However, it claims 'Supported types' but lists only three of the five enumerated in the schema, omitting patent_grant and clinical_trial. This is a completeness gap, though the schema fills it. Overall, the description is rich but not fully exhaustive.

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 goes far beyond by providing concrete examples for each subscription type (e.g., items:["5.02"] = officer change for sec_8k), delivery channel requirements (phone must be verified, webhook restrictions, signing secret), and constraints. This adds significant meaning beyond the schema.

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

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

The description clearly states the action: 'Create a proactive monitoring subscription to a live-data event stream' and specifies it returns the new subscription id. This distinguishes it from siblings like list_subscriptions and unsubscribe, and provides a specific resource (live-data event stream subscription).

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: proactive monitoring with specific subscription types. It also includes prerequisites (OAuth account, phone verification for SMS) and delivery channels. However, it does not explicitly compare to alternatives like recent_alerts or fetch_feed, so it lacks an explicit 'when vs. not' statement, but the context is strong.

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

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

Annotations already declare read-only, idempotent, and open-world behavior. The description adds that the suggestions are drawn from a live catalog and include tool+argument shapes, which explains why the output can change. 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 a bit long but every clause adds useful information—intuitive user queries, what it returns, usage options, and timing. It is front-loaded with the question patterns and ends with actionable guidance, so the length is justified.

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

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

With only one optional parameter and no output schema, the description adequately explains the return content, the customization via 'topic', and the appropriate time to use the tool. The lack of output schema is mitigated by describing the nature of the 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?

The schema already provides 100% coverage for the 'topic' parameter with full value list. The description adds a few examples and clarifies that omitting the parameter gives a cross-category spread, but this is marginal beyond what the schema 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 identifies the tool as the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It also distinguishes itself from siblings like discover_tools by focusing on 'what to ask' rather than just discovering 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 explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call meta-tools, giving direct when-to-use instructions. It also differentiates between no-argument and topic-filtered 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?

The description reveals important behavioral details beyond the annotations: ownership enforcement, soft-delete behavior (deactivation vs deletion), and that historical events remain accessible. The annotations already indicate idempotency and non-destructiveness, and the description adds complementary 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?

Two concise, front-loaded sentences. The first sentence states the core action, and the second explains the key behavioral nuance (deactivation and historical availability). Every word adds value; 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?

For a simple single-parameter mutation tool with strong annotations, the description is quite complete. It addresses ownership, the soft-delete behavior, and the impact on historical data. It does not mention return values or error cases, but these are not essential given the tool's simplicity.

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

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

The input schema fully documents the single parameter 'id' with its type and source ('Subscription id (uuid) returned by subscribe'). The description adds minimal new information ('by id'), but since schema coverage is 100%, the baseline 3 is appropriate.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It uses a specific verb and resource, and explicitly distinguishes this from deletion by noting the row is deactivated. This also sets it apart from sibling tools like subscribe and list_subscriptions.

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

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

The description provides useful context about ownership ('you can only cancel your own subscriptions') and hints at an alternative path for historical events via recent_alerts. While it doesn't explicitly list when-not-to-use scenarios, the ownership constraint and reference to recent_alerts give clear usage direction.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds rich behavioral context far beyond annotations: the dual-path routing (SEC EDGAR vs grounded pipeline), the judgment step with verbatim evidence, citation format, and the exact verdict types returned. 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 and contains a list of natural-language patterns, but every part contributes to selection or invocation. It is front-loaded with use-case phrases and includes the critical replacement-of-sequential-calls benefit. Slightly verbose, but effective.

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

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

With no output schema, the description fully compensates by explaining return values (verdict, actual value, citation, reasoning), the two processing paths, and the behavior for both financial and non-financial claims. This is complete enough 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 description coverage is 100% for the 2 parameters, so baseline is 3. The description adds some context about percent-delta math and tolerance, but it does not meaningfully extend beyond the schema's own 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 natural-language claim verification against authoritative sources, with a specific verb and resource. It distinguishes itself from siblings by explicitly stating it replaces 4–6 sequential calls and handles both structured SEC/XBRL financial claims and grounded fallback for other claims.

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

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

Provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims and other factual claims, explaining the routing. However, 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.