Finance Feeds

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds meaningful context beyond those: it performs external API calls with a BYO key that incurs direct Anthropic costs, and defaults to a free Workers AI model. This helps an agent anticipate side effects and cost.

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

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

Four sentences, front-loaded with the core action, then cost, return shape, and use cases. Every sentence earns its place with no fluff or redundancy against the schema.

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

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

No output schema exists, but the description compensates by listing the per-model fields (score, confidence, signals, raw_response) and the combined view. It also covers cost, default model, and typical applications. It lacks explicit failure/edge-case behavior, but for a relatively simple probe tool that's acceptable.

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 reinforces that `_apiKey` enables Anthropic probing and that omitting `models` uses the default, but it doesn't add substantive syntax or format details beyond the schema. It earns the baseline without extra credit.

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 'Probe' and clearly identifies what it queries (one or more LLMs), the scored output (0-100 per model), and the intended domain (business/brand visibility). It distinguishes itself from sibling tools like ask_pipeworx and scan_competitor_ai_presence by focusing on scoring model knowledge rather than Q&A or competitor scanning.

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 contexts: AI-marketing audits, pre-launch brand checks, competitive monitoring. Also explains the default free model and the optional Anthropic key progression. Doesn't explicitly state when not to use it or point to alternative tools, 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond that: it routes to 5,462 tools, fills arguments, and returns stable pipeworx:// citation URIs, which are non-obvious behaviors. It does not contradict annotations, though it could mention what happens when no source matches.

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 structured as a priority directive followed by scope, triggers, examples, and escalation guidance. Though lengthy, every sentence serves a purpose—e.g., 'START HERE for most questions' and the explicit alternatives—making it dense but not bloated.

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

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

This is a complex router tool with no output schema, but the description covers the core invocation contract: input (a natural-language question), behavior (routing/filling args), output (structured answer with citations), and context (default entry, tiers, alternatives). A minor gap is the lack of explicit failure-mode language, but overall it enables confident 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 input schema has 100% description coverage, explicitly documenting the `question` parameter and the aliases `q`, `prompt`, `text`, `input`, and `query`. The tool description itself adds no additional parameter-level detail, but the schema is sufficient, 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 explicitly states the tool's role as a router for factual questions to thousands of verified sources and returns cited structured answers. It distinguishes itself from siblings by name (ask_pipeworx_grounded, deep_research) and explains when each should be used instead. The verb 'routes' and resource '5,462 tools' make the purpose unmistakable.

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

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

The description gives clear usage triggers: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and provides concrete examples. It also includes when-not-to-use guidance, recommending ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for multi-part fan-out, while noting breaking news is already covered. This is exemplary 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, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: the beta nature, that candidates are enabled live only when under test, that no candidate is currently active (retired 2026-07-26), and that results are compared to decide merges. This goes beyond the annotations and clarifies the experimental state and fallback 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 four sentences and somewhat dense, but each sentence conveys essential information: what it is, current state, usage, and fallback clarification. No sentence is wasted, though it could be trimmed slightly without losing key points.

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

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

For a beta variant of an existing tool, the description sufficiently explains purpose, current operational status, and relation to the stable version. It references the response shape as identical to ask_pipeworx, but does not explicitly describe what the router does (e.g., answering questions by selecting the best tool). However, the title and 'universal router' make this inferable, and there is no output schema to require more detail.

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 (question plus five aliases). The description only says 'same arguments' as ask_pipeworx, which adds marginal context but does not meaningfully enhance the existing schema descriptions. Baseline 3 is appropriate given the high schema coverage.

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

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

The description clearly states it is a 'universal router' with 'same 5,462 tools, same arguments, same response shape' as ask_pipeworx, and explicitly positions it as a beta variant. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing experimental 'candidate routing improvements' and the current no-active-candidate state.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts with the stable router for comparison purposes. It denotes this as the experimental edge and clarifies it is not a fallback ("Falls back to nothing"), providing clear when-to-use guidance versus alternatives.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that it extracts answers only from tool results, returns verbatim evidence, and can refuse with specific reasons (not_in_source, no_tool_match, etc.). It also notes the extra LLM call cost, a behavioral trait not covered 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 dense but efficient: it packs purpose, mechanism, output format, usage guidance, and cost trade-off into a single paragraph without redundancy. The key phrase is front-loaded, and each sentence adds new 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?

With no output schema, the description compensates by enumerating the success and refusal response structures, including exact refusal reasons. It covers all important aspects: behavior, use cases, alternatives, and cost, making it complete for a single-question tool.

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

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

The schema already documents all 6 parameters with 100% coverage, describing them as natural-language question aliases. The description doesn't add parameter-specific syntax but does explain how the question is used ('fills arguments, fetches the data'), so it is consistent with 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 'Hallucination-resistant answer mode for high-stakes reads,' naming a specific mode and its intent. It clearly differentiates from sibling ask_pipeworx by describing the same routing but adding grounded extraction, making the purpose distinct.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides a clear alternative: 'prefer ask_pipeworx for casual lookups,' giving both inclusion and exclusion criteria.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses numerous behavioral traits: low-confidence matches short-circuit and suppress analysis fields, closed markets return a specific status and skip fan-out, wide-spread markets carry a tradeability flag, and potential GDELT 429s trigger fallback attempts with retry fields. It also documents the resolver contract and resolution-rule risk (e.g., refund_50_50) which are critical for safe usage. This goes well beyond the annotation safety profile.

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

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

The description is long but well-structured into logical segments (classifiers, fan-out examples, response shapes, resolver contract, safety, resolution-rule risk). Every sentence contributes meaningful detail for a complex tool. It is not as tight as the two-sentence ideal, but the verbosity is justified given the tool's sophistication; trimming 10-20% could improve conciseness without losing value.

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

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

With no output schema, the description carries the full burden of explaining return values. It thoroughly covers response shapes (result.market, result.analysis, result.evidence), resolver contract (market_match_confidence, alternatives, suggestions), parent-event extraction, news fallback fields, safety statuses, and resolution-rule risk scenarios. It even explains the blocking behavior for low-confidence and closed markets, making it complete for an agent to invoke 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?

The input schema already describes all three parameters with 100% coverage, including the accepted formats for `market`, the default for `depth`, and the impact of `include_raw`. The description reiterates some of this (e.g., slack, URL, or question text) but adds no new parameter-level semantics beyond what the schema provides. The schema does the heavy lifting, so a 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 states a specific verb and resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It clearly distinguishes itself from siblings by focusing on bet research with data fan-out and a market-vs-model comparison, rather than pure edges or arbitrage. The concrete use cases ("should I bet on X", "what does the data say about Y", "is there edge in Z") reinforce the 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 explicit use cases with "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It also gives many fan-out examples for various bet types, implying when to use it. However, it does not explicitly state when NOT to use it or name alternative sibling tools (e.g., polymarket_arbitrage) as exclusions, so it falls short of a 5.

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

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

Annotations cover read-only/idempotent/non-destructive, and description adds extra behavioral details: parallel execution, sorting by primary metric, paired data + citation URIs, off-calendar fiscal year handling. No contradiction.

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

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

Dense but fully purposeful; front-loaded with trigger phrases, then preference rule, domain details, sorting/output, and efficiency claim. Every clause adds operative guidance without fluff.

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

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

With no output schema, description compensates by explaining return content (paired data, citation URIs) and metrics per type. Covers key edge case (off-calendar fiscal years) and scope limits (2–5 entities), making it sufficient for agent 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?

Even though schema describes parameters at 100% coverage, the description enriches semantics by mapping type='company' to 10-K financial fields and type='drug' to FAERS/FDA/trial counts, plus concrete value examples. This is meaningful value beyond schema.

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

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

Description uses specific verbs and resources: 'side-by-side comparison of 2–5 companies or drugs', names data sources for company/drug, and explicitly contrasts with 'sequential single-pack lookups'. It clearly distinguishes from entity_profile-style single-entity 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?

Lists exact trigger phrasings ('Compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies') and states 'ALWAYS PREFER over sequential single-pack lookups'. Gives guidance on choosing company vs drug via the type parameter.

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

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

Annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true) are supplemented with extensive behavioral context: account/auth requirements, paid tier for 'thorough,' timing (15-60s), gap[] behavior ('never invented'), contradictions[], hop field, citation_uri fetchability, and semantic excerpting. 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 dense single paragraph with high information density; every sentence adds value. However, it could be improved by breaking into logical sections (usage, behavior, timing) for readability, though the compactness is justified given 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?

Despite no output schema, the description fully specifies the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop field. It also covers account prerequisites, depth behavior, and timing, making it complete for an agent to decide when to invoke 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 description coverage is 100%, but the description adds meaningful nuance beyond it: for question, 'Broad/multi-part is fine — decomposition is the point'; for depth, it explains quick/standard/thorough facet counts, gap-recovery hop, contradictions scan, and paid requirement for thorough. These details enhance what the schema headers alone provide.

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

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

The description clearly states a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' and 'Decomposes your question into focused facets, routes each to the right one of 5,462 tools IN PARALLEL.' It distinguishes itself from sibling tools like ask_pipeworx ('For a single lookup use ask_pipeworx').

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

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

Provides explicit when/when-not usage with named alternatives: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also handles the not-signed-in case: 'If you are not signed in, use ask_pipeworx instead.'

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, covering safety. The description adds value by explaining the return format (names, descriptions, full input schemas with examples) and the 'no second schema lookup needed' detail, which is non-obvious behavior beyond the annotations. It doesn't contradict annotations.

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

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

The description is three sentences that each earn their place: purpose, domain list plus return specifics, and usage ordering. It is front-loaded with the primary verb and remains concise without fluff. This is well-structured and appropriately sized.

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

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

Given the tool's simplicity (6 params, 1 required, no output schema), the description is complete: it states what the tool does, when to use it, what it returns, and how to invoke it first. The annotations cover safety. No significant gaps exist.

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

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

Schema description coverage is 100%, with clear descriptions for query and aliases, and limit's default/max. The description's mention of 'top-N' is redundant with the limit schema. It adds no new parameter-level meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states a specific verb-resource pair: 'Find tools by describing the data or task.' It distinguishes itself from siblings by specifying it's a discovery/search tool for other tools, listing many data domains, and contrasting with 'not just one answer' tools like deep_research. This leaves no ambiguity about what the tool does.

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

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

Explicit guidance is given: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This tells the agent when to invoke it, and the 'not just one answer' phrase implies when alternative tools might be better. This is strong 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?

The description goes beyond the readOnlyHint/idempotentHint annotations by detailing the parallel fan-out across sources, specific return structure, patent API sunset with soft-fail, GDELT→GNews fallback, and the input format constraints. This provides substantial operational insight.

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-loading example queries and the core value proposition. Every sentence contributes useful info: input formats, output components, fallback behaviors, and limitations. 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?

With no output schema, the description fully covers what the tool returns: CIK, company_name, recent_filings with URIs, fundamentals details, patents status, news fallback, and LEI. It also covers input restrictions, making it self-sufficient for an agent.

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

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

Schema description coverage is 100% with both parameters (type and value) well documented, including example values and the name-not-supported caveat. The description largely repeats schema information, so it adds little beyond baseline, but no gap exists.

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: creating a full cross-source profile of a US public company in one parallel call. It provides concrete example queries and enumerates the data sources and returned fields, distinguishing it from single-purpose lookups and siblings like resolve_entity.

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 recommends this tool over chaining single-pack SEC/XBRL/news lookups for holistic questions, and directs users to resolve_entity when only a name is available. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context: 'CF-robust: fetches directly and falls back to a proxy if the source blocks the gateway' and the normalization aspect, which go beyond annotation data.

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 and front-loaded with the core purpose. Every sentence adds value: the first states functionality, the second provides robustness and guidance. No redundant or excessive wording.

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

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

The description covers purpose, feed types, fallback behavior, and mentions a sibling tool. However, it does not explicitly differentiate from read_feed or describe the return format, which could be useful given there is no output schema.

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

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

Schema coverage is 100%, so all parameters (url, limit, query) are already described in the schema. The description does not add additional parameter-specific meaning beyond the schema, so it meets the baseline for high 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 specific verb and resource: 'Fetch and normalize any RSS / Atom / RDF feed by URL.' It clearly identifies the tool's function and distinguishes it from siblings like list_feeds (curated sources) and read_feed (likely reading stored 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?

The description states 'Use list_feeds first for curated sources,' providing explicit context for when to use an alternative tool. It implies this tool is for arbitrary URLs and live fetching, but it does not explicitly contrast with read_feed or mention when to avoid 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 destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds context about 'previously stored' and 'sensitive data' but does not reveal additional behavioral traits such as error handling or irreversibility beyond what annotations imply.

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 long, front-loaded with the core action, and every sentence contributes value without redundancy.

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

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

For a simple one-parameter delete tool with strong annotations covering destructive and idempotent behavior, the description sufficiently covers purpose, usage, and sibling relationships. No output schema exists, but the low complexity doesn't require return-value details.

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

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

Schema coverage is 100% with a clear description for the only parameter ('key': 'Memory key to delete') and an example provided. The description adds no further meaning, so a 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 action ('Delete') and resource ('previously stored memory') with a specific key. It also distinguishes itself from sibling tools by referencing 'remember' and 'recall'.

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 provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names complementary tools, offering clear guidance on usage and alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses that it fetches the page, extracts certain elements, and emits a text blob—key behavioral traits. It doesn't mention rate limits or error handling, but the annotations already cover safety, so this is adequate.

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: main function, process, and use cases. It is front-loaded and every sentence adds value without excessive 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?

For a tool with two simple parameters and no output schema, the description sufficiently explains what it does and what the output looks like (a text blob). It could mention edge cases like non-HTML pages, but overall it is complete for its complexity.

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

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

Schema coverage is 100% for both parameters, so the description adds no extra parameter-level detail. The baseline of 3 is appropriate; the description's mention of 'key links' and output format does not compensate meaningfully beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with specific actions (fetches, extracts, emits) and output format. It distinguishes itself from siblings by focusing on creating the actual llms.txt artifact, not just analyzing AI visibility.

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 'Useful for:' scenarios (client indexing, personal drafts, competitor auditing), which conveys when to use it. It does not name alternative tools or give exclusion criteria, but the context is sufficiently clear for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful context about the curated scope and the return fields, but does not disclose additional behavioral traits like pagination or rate limits. This is above baseline given the annotation coverage.

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

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

The description is two concise sentences with the action front-loaded. Every word earns its place, mentioning the output fields, optional filters, and the related read_feed tool in a compact, readable manner.

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

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

For a simple list tool with two optional parameters and no output schema, the description is complete. It states what the tool returns, how to filter, and where to go for single-feed reads. There are no significant gaps given the tool's simplicity and annotation coverage.

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 (query and category), so the structured data fully documents them. The description only restates that filtering is optional without adding format, constraints, or usage details beyond the schema, matching 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?

The description clearly states the tool lists curated finance & markets feeds with specified fields (id, title, category, source). It distinguishes itself from sibling read_feed by explicitly directing the user to pass an id to read_feed for individual feed access.

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 guidance: use list_feeds to list feeds, optionally filter by category or keyword, and use read_feed when you have a specific id. This names an alternative tool and indicates when to use it, fulfilling the dimension's requirement.

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, covering the safety profile. Description adds return field details and default active-only behavior implicitly via the existence of include_inactive. No contradictions, but no extra behavioral traits like pagination or error handling beyond the schema.

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: first states purpose and return fields, second gives usage guidance. Front-loaded with the core action, zero filler. 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 simple list tool with one optional parameter and no output schema, the description is complete: it explains what is listed, the return fields, and when to use it. Minor omissions like pagination or error behavior are not critical for this complexity.

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

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

Schema coverage is 100%, with the single parameter include_inactive fully described in the schema. The description does not directly mention this parameter but implies it by stating 'active subscriptions'. Baseline 3 is appropriate as the schema carries the parameter meaning.

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 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing, and further clarifies the scope (caller's active) and return fields.

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

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

Provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use the tool, though it doesn't mention alternatives or when not to use it. Clear context without exclusions.

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

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

Annotations are all false, offering no behavioral signal, so the description carries the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), and processing ('The team reads digests daily and signal directly affects roadmap'). It even warns against pasting end-user prompts, adding important context beyond annotations.

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

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

The description is a single dense paragraph but every sentence serves a purpose: scope, use cases, exclusions, message formatting, team impact, rate limits, and quota. It is longer than ideal but not wasteful; a bulleted format could improve scannability, yet the content justifies its length.

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

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

Given there is no output schema, the description covers all critical context: what the tool does, when to use it, what not to report, how to format feedback, limitations, and consequences. No meaningful gaps remain for an agent to misuse the tool.

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

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

The schema documents all parameters at 100% coverage, including enum meanings and nested context fields, which earns a baseline of 3. The description adds extra value by advising 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies expected content for the message and context parameters 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the action (feedback submission), the target (Pipeworx team), and the scope (issues with Pipeworx tools). This distinguishes the tool from sibling research/data tools like ask_pipeworx or pipeworx_trending, which serve different purposes.

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 criteria: '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 gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is exemplary usage guidance.

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

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

Beyond the annotations (readOnly, idempotent), the description adds valuable behavioral context: it is self-aggregating, derived from the CF analytics engine, contains no PII, returns only (pack, tool, count), and is cached 5min-1h depending on window. This discloses data source, privacy, and caching 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 compact but includes four sentences, each adding value: core function, use cases, data source/PII, caching. The use case list is slightly verbose but informative, and the overall structure is front-loaded with the most important 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?

With no output schema, the description gives a reasonable summary of the return contents (top tools, top packs, call volume; pack, tool, count). It also covers privacy, caching, and the analytical nature of the signal. Minor omissions like exact response format or pagination are acceptable given the simplicity and 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?

The schema already documents the single parameter 'window' with enum values and a clear description of the trade-off between short and long windows. The tool description simply repeats the window options without adding new meaning, so schema coverage (100%) carries the burden and 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 returns top tools, top packs, and total call volume over selectable windows, with a specific focus on what other AI agents are calling. This distinguishes it from sibling tools like discover_tools by emphasizing aggregated usage trends rather than generic discovery.

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 three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment of one's use case. This gives clear context for when to use the tool, though it does not explicitly exclude alternatives or mention 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, openWorldHint, idempotentHint, and non-destructive. The description adds critical behavioral context: the Jaccard similarity threshold (≥0.30), placeholder fraction filter (>20% returns null), and the fill-check warning that realizable_edge_pp ≤ 0 means the edge is not tradeable. These go beyond the annotations and materially affect how the agent interprets results.

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

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

The description is lengthy but well-structured with capitalized section headers for SEMANTIC ANCHOR, PARTITION FILTER, and FILL CHECK. It front-loads the core purpose and usage, and every paragraph adds needed detail for a complex two-mode tool. Slightly verbose but justified.

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

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

The tool has no output schema, so the description must explain return values. It does: `opportunities[]` with specific fields, `partition_check` object, and the fill_check behavior. It also covers edge cases like placeholder slugs and low-similarity skips, making it comprehensive for an agent to invoke 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?

Both `event` and `topic` are fully described in the schema with usage guidance. The description reinforces these with concrete slug examples, notes that full URLs are accepted for `event`, and explains the behavior each mode triggers. While the schema already covers meaning, the examples and mode-specific behavior add value beyond the schema.

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

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

The description opens with a specific verb 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' clearly stating the tool's function and mechanism. It distinguishes from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection and referencing the fill check separately.

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 specifies three invocation modes: no args for trending_scan, `event` for single-event partition checks, and `topic` for cross-event scans. It recommends `event` for specific markets and notes that cross-event mode catches patterns single-event misses. It also directs custom sizing to `polymarket_fill_risk`, providing an alternative 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial behavioral detail: caching ('Cached 1h at the KV level'), diagnostics for empty segments ('_diagnostics...funnel counters'), and the 24h-move warning. It also explains that edge is net of slippage and that partition arbs return parent-level Kelly=0 by design. 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 dense, but it is structured into clear sections (model families, opportunity fields, knobs, response top-level) and front-loads the core purpose. Every sentence carries information about behavior or usage, though some internal model-family details (e.g., per-sport α values) could be seen as overly granular for tool selection. Overall, it is appropriately sized for the 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 carries the full burden of explaining the return structure. It covers by_segment, fed_candidates/fed_note, and _diagnostics, plus per-opportunity fields like edge_pp_net, kelly_fraction, and the 24h-move warning. It also explains why segments might be empty and how knobs affect the output, making the tool's behavior fully predictable to 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?

Although the schema already provides 100% parameter coverage, the description adds meaningful semantic context beyond the schema. It explains the tradeable-edge knobs, clarifies the min_partition_leg_kelly behavior (parent-level Kelly is always 0, so it applies to per-leg Kelly), and describes the impact of slippage_pp on edge and Kelly. This extra explanation helps agents choose and set parameters correctly.

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 ('Scan') and resource ('top Polymarket markets'), and clearly states the goal ('return opportunities where Pipeworx data disagrees with market price'). It further distinguishes itself from sibling tools by detailing three model families and the response structure, making the tool's scope unmistakable.

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

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

The description explicitly frames the tool for 'what should I bet on today' and explains how the tradeable-edge knobs filter opportunities. It does not explicitly name alternative sibling tools or provide when-not-to-use guidance, but the 'Built for' phrasing and the detailed caveats (e.g., Fed bets excluded, min_kelly nuance) give clear context for appropriate use.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds substantial behavioral detail: snapshots are written only on cache-miss (creating gaps), history is bounded by a 60-day TTL, decay is computed from daily closes (not intraday), and expired opportunities are included. This far exceeds the baseline set by 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?

Though lengthy, the description is efficiently front-loaded with purpose, then covers arguments, response structure, and limitations in a logical order. Every sentence carries useful information, justifying the length given the absence of an output schema.

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?

Because there is no output schema, the description fully documents the response: tracked[], expired[], and snapshot_dates[], including field semantics and limitations. This makes the tool fully understandable without needing to inspect data or other sources.

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 restates days (default 14, max 30) and window (default '1wk') similarly to the schema, adding only the term 'snapshot family.' It does not meaningfully enhance parameter understanding beyond already well-described schema fields.

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

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

The description uses a specific verb-resource pair ('edge persistence and decay telemetry') and directly states the question it answers: 'how long has this edge existed and is it shrinking?' This clearly differentiates it from siblings like polymarket_edges (current edges) and polymarket_arbitrage (cross-market spreads).

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 strong contextual usage guidance ('a fresh wide edge and a 3-week-old wide edge are different trades') and states the tool answers persistence/decay questions. However, it does not explicitly name alternative tools or state when not to use it, slightly below the highest clarity bar.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description adds rich behavioral context: it walks the order-book ladder, returns verdicts like clean|degraded|cannot_fill, and warns that partial basket fills convert an arb into an unhedged directional position. No contradiction with annotations.

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

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

The description is front-loaded with a clear definition and every sentence carries useful information, but it is a dense single paragraph with heavy use of ALL-CAPS and parentheses. Adding line breaks or structured sections would improve scannability.

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

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

Given the absence of an output schema, the description thoroughly enumerates return fields for both modes, including top-of-book, VWAP fill price, slippage, shares filled, verdicts, capture ratio, profit, per-leg details, and risk legs. It also explains the two modes, defaults, clamps, and the failure mode of partial fills — complete for a complex tool.

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

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

Schema coverage is 100% with each parameter documented, so the baseline is 3. The description adds value by explaining mode-dependent semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode, plus the default/clamp behavior.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource phrase that clearly defines the tool's function. It also distinguishes from sibling tools by explicitly stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.'

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

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

The description gives explicit when-to-use guidance with a dollar threshold and identifies the exact signals that should precede this tool. It separates single-market and basket modes, but does not explicitly name alternative tools or state a clear 'when not to use' beyond the implied sub-$500 threshold.

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, but the description adds substantial behavioral context: two modes, compatibility_warning triggers, temporal_alignment semantics, skipped_cross_type/subtype counters, and caveats about pre-mapped topics. It clarifies when spreads are meaningless (e.g., event types mismatch or temporal misalignment), going far 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 and dense, but well-structured with clear sections (modes, response, safety fields, warnings) and front-loaded purpose. Every sentence adds substantive information, and the formatting aids scanning. It could be slightly more concise, but the complexity of the tool justifies the length.

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

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

There is no output schema, so the description must fully explain return values. It does: 'leg-by-leg prices', 'matched spread[]', compatibility_warning, temporal_alignment, and skip counters. It also explains edge cases (e.g., matched_pairs:0 with skipped_cross_type>0) and the broader limitation of pre-mapped topics. The description is near-exhaustive for a tool with 3 optional parameters.

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

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

Schema coverage is 100% (all 3 parameters have descriptions), so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining the interaction between parameters (explicit tickers override topic-mapped sides), listing the predefined topic shortcuts, and illustrating with examples. It clarifies the conceptual relationship between the parameters.

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

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

The first sentence clearly states the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names specific resources (Kalshi, Polymarket) and the action (computing spread), and the description distinguishes it from sibling tools by emphasizing cross-venue comparison rather than single-venue analysis.

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

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

The description provides clear when-to-use context for two modes: 'topic' shortcuts for pre-mapped macro events and explicit 'kalshi_event_ticker' + 'polymarket_event_slug' for custom pairings. It also warns that most pre-mapped topics return compatibility_warning today, implying these may not be tradeable. However, it does not explicitly mention alternative sibling tools (e.g., polymarket_arbitrage) or state when to use those instead.

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 value beyond the annotations by disclosing the output format ('normalized items (title, link, published, summary)') and the filtering capability. This complements the readOnlyHint/idempotentHint annotations, which already cover safe, read-only behavior. However, it does not mention potential error conditions or rate limits, so it stops short of a perfect score.

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 only two sentences, with the core action front-loaded and every clause earning its place. It efficiently conveys the purpose, required input, return format, and an optional filter without unnecessary words.

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

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

Given the tool's simplicity, the description is fairly complete. It covers the prerequisite (list_feeds), return fields, and optional filter. It does not explicitly mention limit behavior (though the schema documents it) or detail what 'normalized' means, but for a read-only feed tool with solid annotations, the context is sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema: it clarifies the feed is 'curated finance & markets' and that query filters over title/summary, but these are mostly echoed in the schema property descriptions. It does not significantly enhance parameter understanding.

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

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

The description clearly states the tool reads a curated finance & markets feed by id and returns normalized items, with a specific verb and resource. It references list_feeds for id lookup, but does not explicitly distinguish itself from the sibling tool fetch_feed, so it misses the top mark for sibling differentiation.

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

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

The description provides clear context on how to use the tool: it requires a feed id from list_feeds, and mentions optional keyword filtering. It does not explicitly state when not to use it or name alternatives, but the prerequisite from list_feeds gives sufficient usage guidance.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds behavioral context: it is scoped to the agent's identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all keys. This enriches the annotation data without contradiction.

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

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

The description is three sentences with no redundancy. It front-loads the primary action (retrieve/list), then justifies usage, scoping, and related tools. Every sentence conveys essential 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, no output schema, and rich annotations, the description is fully complete: it explains the action, the dual-mode behavior, the use case, the scoping, and pairs with related tools. No significant gaps remain.

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

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

The input schema already provides 100% coverage with a clear description for the single parameter ('Memory key to retrieve (omit to list all keys)'). The tool description reinforces this but adds no new semantic detail beyond what the schema states, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys when the key argument is omitted. It distinguishes itself from siblings by explicitly naming remember and forget as paired tools and providing concrete examples of stored context (target ticker, address, research notes).

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 usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives (remember, forget) and implies when not to use it (when re-deriving is needed). This meets the explicit when/alternatives guideline.

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 annotation readOnlyHint=true contradicts the description's statement that setting mark_read:true flags events as read and affects future calls. This is a clear state-changing behavior, conflicting with the read-only hint. The description also does not disclose other behavioral aspects like rate limits or auth, but the contradiction itself drops the score to 1.

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 composed of four sentences, each providing useful information: core action, return payload, filtering options, and mark_read behavior plus an alternative endpoint. It is front-loaded and structured, though the mention of the HTTP URL could be seen as slightly tangential.

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

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

Given there is no output schema, the description compensates by explaining the return payload (source, citation_uri, raw event). It covers filtering, read-state semantics, and alternative access. It lacks details on edge cases like empty feed or pagination behavior, but is otherwise thorough for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds a concrete type example ('sec_8k') and reiterates the mark_read semantics, but these are marginal additions beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts, with specific resource and verb. It also distinguishes itself by describing the mark_read/read-state mechanics and mentions an alternative HTTP endpoint, setting it apart from sibling fetch/read feed tools.

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

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

The description provides clear context on when to use the tool (polling, reading alerts) and notes an alternative for scripts/dashboards (HTTP endpoint). However, it does not explicitly mention when not to use it or contrast with sibling tools like read_feed or fetch_feed.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations by disclosing fan-out to multiple APIs, GDELT-to-GNews fallback on rate-limit/5xx, USPTO soft-fail due to PatentsView sunset, return shape (changes[] grouped by source, total_changes, citation URIs), and the meaning of 'ONE parallel 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?

Dense yet well-organized: begins with user-intent phrasing, then states core function, enumerates sources/fallbacks, parameter semantics, return format, and closes with an alternative—all in four sentences. Every clause earns its place, 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 multi-source tool with no output schema, the description fully covers inputs, behavior, source fallbacks, failure modes, return fields, and usage boundaries. It also addresses the sibling entity_profile to prevent misuse. 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 covers all three parameters at 100%, so baseline is 3. The description adds value by detailing `since` formats with examples and a practical default ('30d' or '1m'), and explains `value` as ticker or CIK with examples (though the schema already had similar text). This elevates it to a 4.

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

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

The description opens with concrete natural-language triggers ("What's new with X" / "latest on Y") and defines the tool as a 'change feed for a company in the last N days/weeks/months'. It explicitly lists the data sources (SEC, GDELT/GNews, USPTO) and contrasts with sibling entity_profile, making the purpose unmistakable and sibling-differentiated.

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 abundant when-to-use guidance: example queries, window formats (ISO or relative), typical monitoring recommendation ('30d' or '1m'), and an explicit alternative ('Use entity_profile instead when you want the static profile...'). Also explains fallback behavior for rate limits, which helps the agent 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?

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds valuable context: persistence lifetime (24 hours for anonymous, persistent for authenticated), scoping by identifier, and the intended pairing with recall/forget. This goes beyond 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?

The description is four sentences, each serving a distinct purpose: core function, when to use, storage behavior, and related tools. It is concise, front-loaded, and every sentence adds value without redundancy.

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

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

For a simple 2-parameter tool with no output schema, the description covers all needed context: purpose, usage triggers, persistence semantics, and sibling relationships. Combined with strong annotations, this is fully complete for an agent to select and invoke the tool correctly.

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

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

The input schema provides 100% coverage with clear descriptions and examples for both key and value. The description merely calls them "key-value pair" without adding extra semantics, which matches the baseline for high schema coverage. No additional parameter details are needed.

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: "Save data the agent will need to reuse later." It specifies both the verb (save) and the resource (key-value pairs scoped by identifier), and distinguishes it from sibling tools by naming recall and forget as complementary operations.

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

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

Explicit usage guidance is provided: "Use when you discover something worth carrying forward... so you don't have to look it up again." It also names alternatives, saying "Pair with recall to retrieve later, forget to delete," giving the agent clear direction on when to use this tool versus its siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds significant context: it details the return fields (ticker, CIK, company_name, RxCUI, ingredient, brand), citation URIs, and the fact that each call "cascades through several lookup endpoints internally." This goes well beyond the annotations and gives the agent a realistic expectation of behavior and side effects (none destructive).

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 more verbose than strictly necessary, but it is well-structured and front-loaded with natural language examples. Every sentence conveys useful information: usage trigger, supported types, return details, and internal behavior. The slight redundancy with schema descriptions (e.g., ticker/CIK/name) prevents a 5, but overall it is tightly written without 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?

Given the moderate complexity (two types, several input forms, multiple return fields), the description is remarkably complete. It explains the exact output for each type, including citation URIs, and clarifies the tool's internal cascading behavior. Since there is no output schema, the description's detailed return information fills that gap. Annotations provide the safety profile, making this tool fully understandable to an agent.

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

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

The input schema already provides 100% coverage with descriptions for both parameters, so the baseline is 3. The tool description adds value by explicitly explaining how the `value` parameter maps to different input forms per type (ticker, CIK, name vs. brand/generic) and enriches with examples like "ozempic". It also clarifies that input is "auto-disambiguated," which is not in the schema. This warrants a 4 but not a 5 because the core parameter semantics are already well-documented in the schema.

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

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

The description clearly states the tool's purpose: "resolve a user-spoken NAME to the canonical/official identifier other tools require as input." It uses specific verbs like "resolve" and "look up the ID," and distinguishes from siblings by listing supported types (company, drug) and the exact identifiers returned (ticker, CIK, RxCUI).

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

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

The description explicitly says "Use FIRST whenever you have a name but need an ID," providing clear guidance on when to invoke the tool. It also mentions that "using resolve_entity replaces 2-3 manual lookups," implying an alternative approach. However, it does not explicitly state when not to use it or name alternative sibling tools, so it falls slightly 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 value beyond annotations by explaining that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This is useful behavioral context and does not contradict the annotations.

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

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

The description is three sentences long, front-loaded with the main action ('Compare AI visibility...'). Each sentence earns its place: the first states the core function, the second describes the method and output, and the third gives a concrete use case. 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?

Despite having no output schema, the description clearly specifies the return format ('ranked list with score, confidence, signal density per entity'). It also explains the competitive comparison use case and the fact that it calls ai_visibility_check. Combined with full parameter documentation in the schema, this provides complete context for an agent to 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 description coverage is 100% — all four parameters (models, _apiKey, context, entities) are individually documented. The description adds no additional parameter-level semantics beyond the schema, so it correctly receives the baseline of 3. It does minimally reinforce the role of entities as 'your brand + N competitors', but that is already in 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 'Compare AI visibility across multiple entities side-by-side' with a specific verb and resource. It distinguishes from the sibling ai_visibility_check by emphasizing multiple entities and ranking, and it names the underlying probe tool and output format. This leaves no ambiguity about what the tool does.

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

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

The description gives clear context, positioning the tool for competitive AI-marketing audits with an example question ('does Claude know about us as well as our competitors?'). It implicitly distinguishes from a single-entity check by mentioning 'multiple entities', but it does not explicitly state when not to use this tool versus alternatives like compare_entities.

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

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

Annotations already signal read-only, non-destructive, open-world, and idempotent behavior. The description adds valuable behavioral context beyond annotations: partial failure handling (sources_failed), potentially slow first bundlephobia measurement (5-30s), and ecosystem restriction (NPM only). No contradictions with annotations.

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

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

The description is dense but every sentence earns its place: purpose, fan-out sources, when-to-use, return summary fields, ecosystem scope, and failure behavior. The key phrase 'in ONE call' is front-loaded, and no fluff or repetition exists.

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 sufficiently enumerates return contents (summary block fields, advisory details, links, alternative versions), clearly defines ecosystem scope, and explains partial failure behavior. This is complete for the complexity of a composite tool.

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

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

Schema coverage is 100% and both parameters have descriptions, so the baseline is 3. The description adds little beyond the schema: it confirms package is an npm package and version defaults to latest, both already stated in the schema. No additional format constraints or edge-case guidance is provided.

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

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

The description states a specific composite purpose: a one-call 'should I add this npm package' check across deps.dev and bundlephobia. It clearly identifies the resource (npm dependency) and distinguishes the tool from siblings by emphasizing the one-call composite nature and returning package health/size metrics.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an alternative for non-NPM ecosystems (deps.dev:version directly), making the when/where boundaries clear.

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

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

Annotations already indicate read-only and idempotent, but the description adds meaningful behavioral details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, and the 200K char truncation flag. This goes beyond 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?

The description is front-loaded with purpose, then usage, alternatives, and technical behavior. Every sentence adds valuable information without unnecessary filler. It is concise given the tool's moderate 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 explains exactly what is returned (top-N passages with character offsets and similarity scores). It covers the main limitation (truncation) and provides workflow context via sibling pairing. Complete for confident tool selection.

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

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

Schema covers 100% of parameters, but the description enriches them: explains what 'text' is (already fetched record), gives example queries for 'query', and ties 'limit' to top-N passages with offsets. It adds context about chunking behavior that schema doesn't convey.

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

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

The description states a specific verb and resource: "Semantic search INSIDE a fetched record" and clearly distinguishes from siblings by explaining it pairs with ask_pipeworx_grounded. It also specifies the exact function: pass text plus query, get back passages with offsets and scores.

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

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

Explicitly states when to use: "Use when the record is too big to cram into the prompt" and mentions cost/context savings. It also names the alternative pairing with ask_pipeworx_grounded, providing clear usage 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?

Beyond the annotations, the description discloses the return value (subscription id), authentication requirements (OAuth account), phone verification prerequisite ('phone must be verified at /account first'), and the 10/day SMS cap. These details add significant behavioral context that the annotations do not cover.

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-loading the core purpose and then systematically covering prerequisites, types, and delivery options. Every sentence provides necessary information, with no fluff or redundancy, making it efficiently concise for the tool's complexity.

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

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

The description is largely complete for a complex tool, covering types, prerequisites, and email/SMS delivery with constraints. However, it omits the webhook delivery channel, which is present in the input schema but not summarized in the description. This is a minor gap since the schema fills it, but the description would be stronger with a brief mention.

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 has 100% parameter coverage, so the baseline is 3. The description enriches semantics by explaining what each subscription type means, e.g., 'sec_8k (8-K filings matching ticker + item codes — e.g. items:["5.02"] = officer change)' and 'polymarket_edge (Polymarket↔Kalshi cross-venue mispricings)'. This goes beyond the schema's mechanical 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 explicitly states 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id,' providing a specific verb and resource. This clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe, which focus on different operations.

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-not-to-use guidance: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also explains delivery channels with context, such as 'feed (always on — pull via recent_alerts...)' suggesting an alternative for feed access, and lists supported types with parameter examples, making usage context clear.

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

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

Annotations already convey safety (readOnly, idempotent, non-destructive). The description adds useful behavioral details: what it returns (category-bucketed example questions with exact tool + argument shape), that it's drawn from the live catalog, and that topic filters the output. It doesn't describe side effects or edge cases, but for a read-only onboarding tool this is solid.

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 opens with example user queries, states the core purpose, details the output structure, explains parameter options, and gives priority usage guidance. It is front-loaded and information-dense without 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 tool with one optional parameter, no output schema, and no nested objects, the description is complete. It explains what the tool returns, how to call it, when to use it, and what it teaches. It also situates the tool within the broader ecosystem by naming meta-tools, making it self-sufficient for an agent.

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

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

Schema coverage is 100%: the schema already fully describes the `topic` parameter with allowed values and the omission behavior. The description repeats this in prose ('pass topic (e.g. ...) to focus') but adds no new information beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point for an agent that just connected, using specific verbs like 'Returns category-bucketed example questions' and 'Use this FIRST'. It distinguishes itself from siblings like discover_tools or ask_pipeworx by focusing on example questions with exact tool + argument shape, and explicitly mentions meta-tools it teaches.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to tailor calls (no args for full spread, or pass topic). However, it does not explicitly state when NOT to use it or mention alternatives beyond naming meta-tools, so it lacks full when-not/alternatives coverage.

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

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

The description adds substantial behavioral context beyond the annotations. It explains that the row is deactivated rather than deleted, that ownership is enforced, and that historical events remain accessible—critical details that the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) do not fully convey. This goes beyond annotation indicators.

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 precise sentences deliver all essential information: the action, ownership constraint, and deactivation behavior. No redundant phrasing, and the most important fact (cancel a subscription by id) leads the description.

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 no output schema, the description fully covers what the agent needs: the action, side effects, and post-condition. Annotations handle safety flags, and the schema handles the parameter, so the description 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?

The schema already documents the 'id' parameter with a clear description (subscription id returned by subscribe). The description adds value by emphasizing that only the user's own subscriptions can be canceled, which informs which id is valid. This is semantic context beyond the schema's type and origin.

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 with a specific verb and resource: 'Cancel a subscription by id.' It distinguishes the tool from siblings like subscribe and list_subscriptions by clarifying the soft-delete behavior and ownership enforcement.

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

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

The description provides clear context on when to use the tool: it cancels a subscription, enforces ownership, and preserves historical events for recent_alerts. It doesn't explicitly name alternative tools or exclusions, but the soft-delete note implies when this is appropriate versus a hard delete, which isn't available.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description explains the fast path for financial claims with exact percent-delta math, the fallback grounded pipeline with verbatim evidence, the return structure (verdict, actual value, citation, reasoning), and the tolerance_pct override behavior. This is rich, non-obvious behavioral context that helps the agent reason about side effects and expected outcomes.

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-organized: it opens with user-facing phrasings, then defines the core purpose, explains routing, lists the return values, and ends with a performance benefit. Each clause adds necessary information, and there is 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?

With two well-described parameters, informative annotations, and no output schema, the description fully covers what the agent needs: when to use the tool, what inputs are expected, how it behaves for different claim types, and what output format to anticipate. It even explains the tolerance semantics and the fast-path vs. grounded pipeline, making it self-sufficient.

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

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

The schema provides descriptions for both parameters, but the description adds significant semantic value: it explains that tolerance_pct overrides the tolerance implied by the claim wording, suggests values for hallucination detection, and states the default behavior (capped at 5). It also gives concrete examples for the claim parameter, making the parameters more actionable than the schema alone.

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

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

The description clearly defines the tool as a natural-language claim verification service with examples of user intents ('Is it true that...', 'fact check'), a specific scope (company-financial vs. any other factual claim), and a distinct output (verdicts). It is explicitly differentiated from generic research or lookup tools by focusing on verification and the unified pipeline it replaces.

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 whenever the agent needs to check whether something a user said is factually correct', giving a clear trigger. It also outlines the internal routing for financial vs. other claims, which helps set expectations. However, it does not mention explicit alternatives or when not to use the tool, 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.