zippopotam

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavior: it explains the free default model (Workers AI Llama-3.3-70b), the BYO-key mechanism for Anthropic with direct cost implications, and the return structure {score, confidence, signals, raw_response} + combined view. No contradiction with annotations. It adds context beyond annotations without over-explaining.

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

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

The description is three sentences, front-loaded with the primary purpose, then details the default model/optional key, then the return format and use cases. Every sentence adds necessary information with 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?

Given the tool's moderate complexity (4 params, no output schema), the description covers the essential aspects: what it does, how to configure models, return format, and typical use cases. It lacks minor details like rate limits or score computation methodology, but these are not critical for selecting/invoking the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some extra context by explaining that the default model is free and that _apiKey is for Anthropic, but it largely reiterates what the schema already states (e.g., _apiKey is 'Optional Anthropic API key'). No major enrichment beyond schema descriptions.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This precisely states the tool's purpose and differentiates it from siblings like ask_pipeworx or deep_research by focusing on visibility scoring across models. The mention of per-model scoring and a combined view further clarifies its unique role.

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 use contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly state when not to use it or name alternative tools for similar tasks, so it stops short of the 'explicit when/when-not' level.

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

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

The description discloses key behavioral traits: it routes to 5,529 tools across 1,455 sources, fills arguments, returns structured answers with stable citation URIs, works on every tier, and is a fast single call. It also notes limitations (not hallucination-resistant, not for broad fan-out). Annotations declare readOnly/openWorld/idempotent, and the description complements rather than contradicts them, adding context about speed, scope, and citation format.

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 detailed and clearly structured, with actionable guidance, examples, and explicit comparison to alternatives. While it is longer than minimal, every sentence provides value, though some redundancy exists (e.g., listing many domains) that could be trimmed.

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

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

For a tool with no output schema, the description explains the return format (structured answer with citations). It covers when to use, what kinds of questions, examples, limitations, and alternatives. This is highly complete 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 coverage is 100% with descriptions for the 'question' parameter and its aliases. The description adds examples but doesn't provide additional technical parameter semantics beyond what the schema already states. Per guidelines, baseline 3 is appropriate when the schema carries the full burden.

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

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

The description clearly states the tool's purpose: it answers factual questions by routing them to the appropriate source among thousands of verified tools, returning structured answers with citations. It uses specific verbs like 'routes', 'fills arguments', and 'returns', and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by explicitly contrasting its behavior.

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 extensive usage guidance: it says to prefer this over web search, lists numerous domains it covers, gives example queries, and tells when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). This is explicit and well-differentiated.

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

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

Annotations already declare read-only, open-world, and idempotent behavior; the description adds valuable context about experimental live candidate routing, the current lack of an active candidate, and that behavior matches ask_pipeworx exactly. It also explicitly states this is a full working router, not a fallback, which is useful 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 front-loaded with the core identity and beta status, then provides current-state detail, usage guidance, and a reassuring fallback statement. It is slightly verbose with specifics like the date and tool count, but each sentence adds meaningful context without redundancy.

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

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

For a beta experimental variant, the description fully covers what the tool is, how to use it, and how it relates to the stable version. It mentions identical response shape, which compensates for the lack of an output schema. It does not explain what 'routing' entails, but that is not necessary given the comparison to ask_pipeworx.

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 aliases for the single semantic parameter (question). The description adds no additional parameter meaning, only noting 'same arguments' as ask_pipeworx, which is already implied by the schema. Baseline of 3 is appropriate given the schema does the heavy lifting.

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 this as the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and arguments, and distinguishes it from the stable ask_pipeworx by highlighting the experimental routing candidates. It lacks an explicit verb like 'routes your question' but the context makes the purpose evident.

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 provided: 'Use it exactly like ask_pipeworx when you want the newest routing' and results are compared against the stable router to decide merges. It also clarifies the current state (no active candidate, matches ask_pipeworx exactly), giving clear when-to-use direction versus the stable alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description goes far beyond by detailing the exact return shapes on success and failure, including refusal reasons like 'not_in_source' and 'data_truncated.' It also discloses the extra LLM call cost and that extraction uses only tool result content, providing rich behavioral context that annotations alone do not.

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

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

Three dense sentences pack the purpose, routing, return format, refusal reasons, use cases, and cost trade-off without redundancy. The description is front-loaded with the core value proposition and every sentence earns its place, providing high information density in a compact structure.

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 complete for agent selection and invocation: it explains what the tool does, when to use it, what it returns (including the full return schema on success and all refusal reasons), and how it differs from the sibling ask_pipeworx. With no output schema present, the description fully specifies return behavior, making it contextually complete.

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

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

The schema covers all 6 parameters with 100% description coverage, including aliases for question. The description does not add parameter-specific semantics, but none are needed since the schema already documents 'question' and aliases clearly. Baselin 3 applies because the schema carries the parameter documentation burden.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' that extracts answers strictly from tool results, with a specific verb+resource focus. It distinguishes itself from sibling ask_pipeworx by emphasizing grounded evidence, verbatim quotes, and explicit refusal behavior, making its 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?

Provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It names the alternative tool directly and states the cost trade-off (one extra LLM call), giving clear when-to-use and when-not-to-use 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?

Goes far beyond the annotations (readOnlyHint=true, idempotentHint=true). It discloses resolver contract behavior (market_match_confidence, alternatives, suggestions), safety short-circuits (low_confidence_match, market_closed_or_inactive), fan-out parallelism, tradeability flags, and resolution-rule risk with ev_impact. The description fully maps operational behavior that annotations cannot capture.

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

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

Despite being long, the description is densely informative and well-structured with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). The core purpose is front-loaded, and every section provides unique operational guidance without redundancy.

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

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

No output schema exists, so the description carries full responsibility for explaining return values. It details result shapes (result.market, result.analysis, result.evidence), status paths, safety mechanisms, news fallback fields, and cancellation-rule parsing. It thoroughly covers edge cases like de-indexed markets and GDELT 429s, making it 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 description coverage is 100%, so baseline is 3. The description repeats market input formats (slug, URL, question text) that already appear in the schema, and it does not add additional nuance for depth or include_raw beyond what the schema provides. No extra parameter meaning is contributed.

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

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

The description opens with a specific verb+resource combination: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This clearly distinguishes it from sibling tools like ask_pipeworx or deep_research by focusing on betting-specific evidence with fan-out. Concrete usage examples ('should I bet on X') 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 an explicit 'Use for' list: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It states clear contexts for invocation. However, it does not name alternatives or exclusion criteria (e.g., when to use ask_pipeworx instead), so it falls short of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description goes beyond them: it reveals that company data comes from SEC EDGAR/XBRL with correct off-calendar fiscal year handling, that results are sorted by the primary metric, and that output includes paired data plus citation URIs. 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: trigger phrases, preference instruction, type-specific data sources, fiscal-year handling, sorting behavior, and return format. It is front-loaded with usage intent and contains no filler.

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

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

Even without an output schema, the description fully specifies return contents (paired data + pipeworx:// citation URIs), result ordering, and per-type data sources. For a two-parameter comparison tool, it covers all necessary operational context.

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

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

Schema coverage is 100%, but the description enriches both parameters: 'type' is explained with what data each enum value pulls (10-K financials vs FAERS/trial counts), and 'values' is clarified with examples like tickers ([AAPL, MSFT]) and drug names ([ozempic, mounjaro]). This adds meaning beyond the bare schema definitions.

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

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

The description opens with concrete trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger') and clearly states the tool's function: side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes itself from sibling tools by explicitly naming the alternative ('sequential single-pack lookups') and detailing the exact data sources per entity type.

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

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

The description explicitly instructs agents to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear usage guidance. It also explains the two modes (company vs drug) and gives example queries, making it obvious when to invoke this tool 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?

The description is rich with behavioral details beyond the annotations: it explains how the tool decomposes questions, routes to 5,529 tools in parallel, returns gaps[] rather than fabricating, includes contradictions[] for standard/thorough, advertises fetchable citations, describes semantic excerpting, and provides latency expectations. No contradictions with the annotations exist.

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

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

The description is extremely long and dense, covering many details in a single wall of text. While every sentence carries useful information, there is redundancy (e.g., ask_pipeworx is mentioned multiple times), and the structure could be improved with bullets or sections. It is not concise, but it is information-packed.

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 fully by explaining the return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), the gaps[] and contradictions[] fields, the iterative depth behaviors, and timing. It also covers account requirements and usage boundaries, making it highly complete for a tool of this complexity.

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

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

The input schema already provides 100% coverage, thoroughly describing both `question` (natural language, broad/multi-part) and `depth` (quick/standard/thorough with detailed hop behavior). The tool description adds a couple of nuances (e.g., 'thorough' requires a paid plan) but largely repeats schema content, so it offers moderate added value beyond the schema.

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

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

The description clearly states the tool performs 'grounded multi-source research' across Pipeworx's structured data sources, and explicitly differentiates from siblings by noting 'this is NOT open-web search' and contrast with ask_pipeworx. It gives concrete use cases and specific resource types (SEC filings, FRED/BLS, etc.).

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and explicitly says for single lookups or breaking news to prefer ask_pipeworx. Also notes account requirements and that alternate tools work without sign-in. This is clear, actionable guidance with named alternatives.

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

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

Annotations already establish the tool as read-only and idempotent. The description adds useful behavioral context beyond this, such as returning top-N tools with full schemas and curated examples, and that no second schema lookup is needed. This gives the agent a clear expectation of the tool's output 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 succinct and front-loaded with the core purpose. The long domain list is informative rather than wasteful, and the additional sentences about return behavior and when to call it earn their place. It is not overly verbose.

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

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

For a discovery tool with no output schema, the description thoroughly explains what is returned (top-N tools with names, descriptions, full input schemas), that results are directly callable, and when to use the tool. It also covers the input style ('describing the data or task'). This is complete 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%, with all six parameters documented, including aliases and the default/max values for limit. The description's mention of 'top-N' reinforces the limit concept but does not add much beyond what the schema already provides. The baseline score of 3 is appropriate here.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes this tool from siblings by positioning it as the tool-discovery entry point, especially with 'Call this FIRST when you have many tools available.' The scope is explicit and unambiguous.

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

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

The description provides clear when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also gives an exclusion ('not just one answer'), though it does not explicitly name alternative sibling tools.

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

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

Discloses concrete behavioral details: parallel fan-out across SEC/XBRL/USPTO/news/GLEIF, specific return fields, USPTO PatentsView sunset with soft-fail, and GDELT→GNews fallback. This goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by explaining how results are assembled and potential degradation.

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?

While lengthy, every clause serves a purpose: examples for intent matching, explicit preference rule, return schema, limitations, and fallbacks. It is front-loaded with user intents and directly addresses what the tool does, making the density appropriate for the tool's complexity.

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

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

Given no output schema, the description fully specifies the return structure (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It also covers limits (up to 5 filings), edge cases (USPTO sunset, fallbacks), and input restrictions, leaving little ambiguity for an agent.

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

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

The schema already covers both parameters fully, but the description adds real value by providing concrete examples ('AAPL', '0000320193') and the critical constraint 'names not supported — use resolve_entity first.' This clarifies semantic nuances that the schema alone does not 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 opens with clear user intents ('Tell me about X', 'research Acme') and defines the tool as 'full cross-source profile of a US public company in ONE parallel call.' This specific verb+resource+scope distinction clearly separates it from sibling tools like deep_research and compare_entities.

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

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

The description explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' providing direct when-to-use guidance. It also notes names are not supported and instructs to use resolve_entity first, giving clear alternative pathways.

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

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

Description states what is destroyed (a previously stored memory) and implies permanence with 'delete'. Annotations provide destructiveHint=true and idempotentHint=true, so the description adds contextual context about clearing sensitive data beyond the annotations.

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

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

Two concise, front-loaded sentences that cover purpose, usage, and complementary tools 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 simple one-parameter tool with good annotations, the description fully covers when and why to use it. No output schema exists, but no return value explanation is needed.

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 describes the single parameter `key` as 'Memory key to delete' at 100% coverage. The description adds no additional parameter semantics 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?

Clearly states the tool deletes a previously stored memory by key. Uses the verb 'delete' and specifies the resource, distinguishing it from sibling memory tools like 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?

Provides explicit use cases: stale context, completed task, clearing sensitive data. Mentions pairing with remember and recall, showing integration, though it doesn't explicitly specify 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 readOnly/idempotent/non-destructive. The description adds useful process context: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. 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?

Three sentences, front-loaded with the primary action, and each sentence contributes value (what it does, how it does it, use cases). 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 2-param tool with complete schema and safety annotations, the description covers output format (standard llms.txt, single text blob) and use cases. The tool is simple enough that no further details are needed.

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

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

Schema has 100% coverage for both parameters, and the description adds no additional parameter-specific meaning beyond what the schema already provides. Baseline 3 is appropriate due to full schema coverage.

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

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

Specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. Distinguishes from siblings by mentioning AI crawler indexing and auditing competitor visibility, which differentiates from tools like scan_competitor_ai_presence.

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

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

Provides explicit 'Useful for:' scenarios (client indexing, own project, competitor audit), but does not name alternative sibling tools or state when not to use this tool. The context is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral details: it returns specific fields, defaults to active subscriptions, and supports including cancelled ones via the include_inactive parameter. No contradiction with annotations.

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

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

Two concise sentences: the first states the action and return fields, the second explains when to use the tool. Every sentence earns its place, with no redundancy or filler. Excellent structure.

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 listing tool with one optional parameter, the description is largely complete. It lists the return fields, notes the default filter, and provides usage context. It is slightly lacking in explaining the format of the 'params' field and any pagination, but those are minor given the low complexity.

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

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

The schema has 100% description coverage for the only parameter (include_inactive), which is already explained in the schema. The description mentions 'active' vs 'inactive' but does not add meaningful syntax or semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists 'the caller's active subscriptions' with a specific verb ('List') and resource ('subscriptions'), and even enumerates the returned fields. This distinguishes it from sibling tools like subscribe and unsubscribe, which are mutation tools.

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

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

The description provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This offers clear contextual guidance, though it does not mention alternatives or when not to use the tool, so a 4 is appropriate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect profile. The description adds input flexibility (names or codes) but does not disclose additional behavioral traits like rate limits, pagination, or error handling. Given the strong annotation coverage, the description provides some value but not substantial behavioral context, warranting a baseline 3.

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, efficient sentence that immediately states the tool's purpose and includes valuable input flexibility examples. It is front-loaded with the verb and resource, and every phrase earns its place. No fluff or redundant details.

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

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

For a simple read-only lookup tool with a comprehensive input schema and an output schema, the description is complete enough. It clearly indicates required inputs, provides formatting examples, and the annotations cover safety and idempotency. There are no missing critical details for selecting and invoking the tool correctly.

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

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

The input schema has 100% description coverage with detailed descriptions for each parameter (e.g., state: 'by name or abbreviation'), and the description includes examples like 'California'/'CA' and 'United States'/'US'. However, the description largely reiterates what the schema already states, adding no new semantic meaning beyond the schema. Thus, the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Get all postal codes (ZIP codes) for a city, given its country and state or province.' It uses a specific verb ('get') and resource ('postal codes'), but does not explicitly differentiate from the sibling tool 'lookup_zipcode', which might be the reverse operation. Therefore, it meets the criteria for a clear purpose without 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 implies when to use the tool (when you need postal codes for a city given country and state), and provides input flexibility guidance ('Country and state may be written as names or codes'). However, it does not mention alternatives or when not to use this tool, such as pointing to 'lookup_zipcode' for the reverse lookup. Thus, usage context is implied but no explicit exclusions or alternatives are given.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds valuable operational context: 'Free, sub-second, no auth' and the 60+ country coverage, which go beyond the structured annotations. No contradiction with annotations exists.

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

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

Three sentences, each earning its place: the first states core purposes, the second gives targeted usage guidance, and the third provides operational facts. The description is front-loaded with the key verb and avoids any filler, making it highly efficient.

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

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

For a simple two-parameter lookup with an output schema, the description covers purpose, usage context, geographical scope, performance, and auth requirements. It is complete enough for an agent to select and invoke the tool correctly without additional information.

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

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

Input schema coverage is 100% with both parameters clearly described (ISO 3166-1 alpha-2 country code and ZIP/postal code). The description adds no new parameter-level details, but the schema fully carries that burden, so a baseline 3 is appropriate.

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

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

The description starts with the specific verb 'Resolve' and clearly states the input (ZIP/postal code) and outputs (city, state/province, latitude/longitude) for 60+ countries. This distinguishes the tool from siblings like lookup_city and web search by framing the exact reverse geocoding function.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' for specific query types and instructs to use it as the first step in geo-aware workflows, even naming downstream examples like weather and attom. This provides clear when-to-use guidance and an explicit exclusion of web search.

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

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

Annotations only provide negative hints (all false), so the description carries the burden. It discloses that anonymous filing returns a claim_token, how to pass it back later to check status, rate-limiting (5 per identifier per day), free/quota-exempt status, and the team's daily digest review. It also warns not to paste end-user prompts, adding a behavioral boundary 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 dense and front-loaded with the core purpose. Every sentence earns its place (usage, exclusions, token flow, rate limits, quota). It's longer than typical, but the complexity of the tool (anonymous token flow, policy boundaries) justifies it. No fluff, though a tighter structure could improve readability.

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

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

With no output schema, the description compensates by explaining the return behavior (claim_token), the follow-up mechanism, and the policy constraints (rate limit, quota exemption, daily digest). It also covers error-avoidance guidance (don't report non-Pipeworx tools). For a feedback tool, this is complete and 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?

Schema coverage is 100%, so baseline is 3. The description adds cross-parameter meaning: how claim_token is used in a follow-up call with no other arguments, and explicit guidance for the message parameter to 'describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This goes 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 first sentence clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This is a specific verb (tell) + resource (Pipeworx team) + scope (broken/missing/existing). It distinguishes from sibling tools like ask_pipeworx, which are for querying, not reporting.

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

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

The description explicitly states when to use it: for bugs, feature requests, data gaps, or praise. It also provides exclusions and alternatives: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' This gives clear guidance and names 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, non-destructive), the description adds valuable behavioral details: the data source (CF analytics-engine), privacy (no PII), content (pack, tool, count), and caching behavior (5min-1h). This transparency helps set expectations for freshness and scope, exceeding what annotations alone provide.

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

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

The description is concise, front-loaded with the core purpose, and uses a structured list for use cases. Every sentence adds new information—from the aggregate signal nature to caching details—without fluff or redundancy.

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

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

The tool is simple (one optional parameter) and has strong annotations and schema coverage. The description covers the return structure (top tools, top packs, total call volume), the timing windows, and data provenance. Without an output schema, this is sufficient for an agent to understand what to expect.

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

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

The schema already fully documents the single 'window' parameter with enum values and descriptions (including the hot-right-now vs steady-state trade-off). The tool description mentions the window options but adds no additional semantic value beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: showing what other AI agents are calling on Pipeworx, returning top tools, top packs, and total call volume. It uses specific verbs and outputs, and distinguishes itself from siblings like ask_pipeworx or discover_tools by focusing on aggregate signals from other agents.

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 tools, seeing alignment with collective usage) and explains the trade-off between windows. It doesn't explicitly name alternative tools or say when not to use it, but the use cases give clear context for appropriate invocation.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds substantial behavior: Jaccard ≥0.30 threshold, >3pp deviation trigger, >20% placeholder filter, and the fill check distinction between theoretical vs realizable edge. No contradiction.

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

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

The description is dense but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence carries operational weight; no filler.

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

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

Given no output schema, the description fully documents the response structure and field names, plus edge cases and fallback behavior. It also references the fill risk tool for custom sizing, leaving no significant gap.

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

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

Schema coverage is 100%, but the description elevates the semantics by explaining how 'event' and 'topic' map to scan modes, giving examples of slugs, and detailing the different checks performed in each mode. It also reveals the no-arg 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 a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges or polymarket_fill_risk by focusing on arbitrage detection.

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

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

It explicitly tells when to call with no args ('trending_scan'), when to pass 'event' vs 'topic', and recommends 'event' for specific markets. It also directs custom sizing to 'polymarket_fill_risk', naming an alternative.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), response segments (by_segment, fed_candidates, _diagnostics), and per-opportunity warnings ('Market moved X.Xpp in 24h'). It also explains why some segments may be empty via _diagnostics funnel counters.

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 (~300 words) but front-loaded with purpose and organized with bold section labels (FIVE MODEL FAMILIES, RESPONSE TOP-LEVEL, TRADEABLE-EDGE KNOBS). While not concise, the density is warranted by the tool's complexity; every section adds operational or interpretability value.

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

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

Given no output schema, the description fully explains top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers edge cases like Fed bet unreliability and placeholder-slug filters, making it sufficiently complete for correct invocation.

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

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

Schema covers 100% of 9 parameters with detailed descriptions. The description adds high-level grouping ('TRADEABLE-EDGE KNOBS') and explains the intent of min_liquidity/max_spread_pp and min_partition_leg_kelly beyond schema syntax, e.g., partition arbs always return kelly_fraction_half=0 at parent level. This supplemental context earns above baseline.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly differentiates from siblings like polymarket_arbitrage or polymarket_edge_tracker by highlighting the Pipeworx data disagreement and the 'what should I bet on today' use case.

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

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

Provides clear context for when to use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains what the tool returns and surfaces diagnostics for empty segments, but doesn't explicitly name alternative sibling tools or give when-not-to-use conditions.

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/idempotentHint annotations, the description discloses behavioral details: snapshot-based data collection, cache-miss writing behavior, 60-day TTL, daily close basis for decay numbers, and signed edge values. This gives the agent a full understanding of what the tool returns and its limitations.

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

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

Long but efficiently structured: purpose, args, response, limits in separate blocks. Each sentence adds functional value; no filler. The length is justified by the complexity of the response shape and edge cases.

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

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

For a complex tool with no output schema, the description provides a comprehensive breakdown of the response fields (tracked[], expired[], snapshot_dates[]), field semantics (trend, decay_pp_per_day, lifespan_days), and limitations (TTL, sampling). This fully compensates for the lack of an output schema.

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

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

Schema covers 100% of parameters, including defaults and valid ranges. The description restates 'days (lookback, default 14, max 30)' and 'window (snapshot family, default 1wk)' without adding new semantic meaning, so it doesn't elevate beyond the schema's thorough documentation.

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

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

The description clearly defines the tool's function with a specific verb phrase ('Edge persistence and decay telemetry') and answers a concrete question ('how long has this edge existed and is it shrinking?'). It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series persistence rather than current edges.

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

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

Provides clear context for when to use: when you need to assess edge age and decay trends, framing the distinction between fresh and stale edges. It gives response interpretation guidance ('median lifespan is your competition clock') but does not explicitly exclude alternatives for scenarios like current edge discovery, though that is implied by the existence of 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 indicate read-only, idempotent, non-destructive behavior. The description adds substantial context beyond annotations: it details what the tool calculates (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, capture_ratio, forced_directional_risk, etc.), how size_usd is interpreted in each mode, and the risk of partial basket fills converting an arb into 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 dense and well-structured, front-loading the core purpose and then alternating between single-market and basket details. It is fairly long but every sentence carries essential information given the tool's two modes and many return fields. It could be slightly more concise by eliminating minor repetition, but overall it is organized for readability.

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

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

Given the tool's complexity (two modes, multiple parameters, rich return values), the description is remarkably complete. It explains output fields, parameter semantics, usage timing, potential risks, and limitations. With no output schema, the description carries the burden of conveying what the tool returns, and it does so thoroughly.

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

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

Schema description coverage is 100% and the schema documents each parameter's basic role. The description adds significant meaning: it explains the two modes (`market` vs `event`), the default behavior of `side` in basket mode (auto based on partition sum), and the distinct interpretation of `size_usd` in single-market vs basket mode (spend/proceeds vs settlement notional per share). This exceeds the baseline.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It uses a specific verb ('check') and resource ('CLOB order-book depth'), and distinguishes between single-market and basket modes. It also references sibling tools (polymarket_arbitrage, polymarket_edges) to position its unique role, making it easy to differentiate.

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 provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the context and rationale, including why theoretical overround on thin books is not capturable and how partial fills create unhedged directional risk. This clearly states when and why to use this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: compatibility_warning semantics, temporal_alignment, skipped_cross_type/subtype counters, and the meaning of matched_pairs:0 with different skipped_cross_type conditions. 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 well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence carries important behavioral or usage information for a complex tool, so it earns a high score, though the length prevents a perfect 5.

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

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

Given 3 optional parameters, no output schema, and the tool's complexity in handling cross-venue matching, the description comprehensively documents the response structure, safety fields, temporal alignment, and failure modes. It provides enough detail for an agent to correctly 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 coverage is 100% since all three parameters have descriptions. The tool description adds the relationship between the optional topic and the explicit overrides, enumerates valid topic values, and clarifies that explicit parameters override the topic mapping. This adds meaning beyond the schema, though not extensively.

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 computing a cross-venue spread between Kalshi and Polymarket for the same resolving question, with a specific formula (Kalshi − Polymarket). It further distinguishes from siblings by emphasizing the cross-venue nature and explicitly describing two operation modes (topic vs. explicit pairings).

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 explains when to use the topic mode versus the explicit kalshi_event_ticker + polymarket_event_slug mode. It also warns that most pre-mapped topics are not tradeable due to compatibility warnings, and explains when no arb exists (non-equivalent bet shapes, temporal misalignment).

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, so the baseline for extra value is lower. The description adds meaningful behavioral context beyond annotations: the tool is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID), and omitting the key lists all saved values. This clarifies data isolation and dual-mode behavior, though it does not cover return formats or error handling.

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

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

The description is three sentences, front-loaded with the main action and behavior. The second sentence illustrates use cases, and the third covers scoping and related tools. Every sentence contributes value with no redundancy or fluff, achieving excellent brevity for the information conveyed.

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

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

With one optional parameter, no output schema, and annotations covering safety, the description is fully adequate. It explains the dual behavior (retrieve vs. list), scoping, and integration with remember/forget. Nothing critical is missing for an agent to select and invoke this 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 already provides 100% coverage for the single parameter, describing the key as 'Memory key to retrieve (omit to list all keys).' The description reiterates the same semantic in prose without adding new parameter-level details. With full schema coverage, the baseline of 3 applies; the description adds no additional parameter semantics.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly distinguishes the tool from its siblings (remember, forget) by describing both retrieval modes. The added examples of stored context (ticker, address, research notes) reinforce the purpose without ambiguity.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also identifies related tools for alternative operations: 'Pair with remember to save, forget to delete.' This provides clear contextual guidance and excludes the need for re-derivation, making usage intent unambiguous.

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 read-only/idempotent annotations, the description discloses key behavioral details: each alert carries source, citation_uri, and raw payload; mark_read:true flips read state so subsequent calls return only newer events. It also openly notes the same feed is accessible at a public URL. 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?

Three sentences, front-loaded purpose, no fluff. Every sentence earns its place: payload composition, filtering, mark_read behavior, polling suitability, and alternative URL.

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 tells the agent what the return items contain, how to filter, how mark_read changes subsequent calls, and mentions polling and an alternate REST endpoint. This is fully sufficient for a read-oriented tool with 5 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 already covers 100% of parameters, so baseline is 3. The description adds value by giving a concrete type example ('sec_8k'), clarifying since as an ISO timestamp with semantics, and explaining the side-effect of mark_read. This goes beyond the schema descriptions, hence 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 'Pull fired events from your subscription feed,' a specific verb+resource statement that clearly distinguishes this from siblings like list_subscriptions or recent_changes. It also specifies what each alert carries, making the purpose unambiguous.

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

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

The description provides solid usage context: explains filtering by type/since, mentions 'Polls work fine' to endorse polling, and offers an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly contrast with similar sibling tools (e.g., recent_changes) or state when not to use it, so it falls short of full 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 idempotentHint annotations, the description discloses important behavioral details: it fans out to multiple sources (SEC, GDELT/GNews, USPTO), explains fallback logic (GDELT preferred, GNews when rate-limited or 5xx), and mentions USPTO soft-failure due to API sunset. This context is not available from annotations alone and sets accurate expectations for reliability and output.

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

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

The description is longer than the simplest examples but each sentence earns its place: it starts with the core purpose, then details the multi-source fan-out and failure modes, parameter usage, return shape, and alternative tool. The structure is logical and front-loaded, though slightly dense, so a 4 is appropriate.

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

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

Given the complexity of the tool (multiple external APIs, fallbacks, failure modes) and the absence of an output schema, the description adequately explains what is returned ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs') and covers the main behavioral edge cases. It is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema already provides 100% coverage for all three parameters. The description enriches these by adding guidance like "Use '30d' or '1m' for typical monitoring," clarifying relative shorthand formats, and explaining how the value parameter maps to ticker or CIK. This goes beyond the schema's baseline and helps the agent choose good parameter values.

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 function as a 'change feed for a company in the last N days/weeks/months' and provides example queries. It distinguishes itself from the sibling tool entity_profile by explicitly directing users to that tool for static profile needs, leaving no ambiguity about scope.

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

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

The description gives explicit when-to-use context with natural language examples like "what's new with X" and "updates on Acme." It also names an alternative (entity_profile) for cases where a static profile is needed, providing a clear decision rule.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: key-value storage scoped by identifier, persistence differences (authenticated vs anonymous 24-hour retention), and pairing with recall/forget. 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?

Three concise sentences, front-loaded with the core purpose. Every sentence contributes—use case, storage mechanism, persistence, and complementary tools. No redundancy or filler.

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

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

For a simple tool with two parameters and no output schema, the description covers purpose, usage, persistence behavior, scoping, and related operations. An agent has all necessary information to decide when and how to invoke it correctly.

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

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

Schema covers 100% of parameters with descriptions and examples for key and value. The description reinforces these examples but does not add new parameter-level semantics (e.g., length limits, format constraints). Baseline of 3 applies 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 the tool saves data the agent needs later, using the verb 'Save' and identifying the resource as reusable data. It naturally distinguishes itself from sibling tools like 'recall' (retrieves) and 'forget' (deletes) by focusing on the write operation. Concrete examples (resolved ticker, target address, user preference) add precision.

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 explains when to use: 'Use when you discover something worth carrying forward' and provides examples. It also directs to complementary tools: 'Pair with recall to retrieve later, forget to delete,' making the choice vs alternatives clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds critical behaviors beyond that: identifiers are labelled with source, unresolved ones are explicitly listed, LEI/FIGI enrichment degrades gracefully without losing EDGAR data, and it cascades through multiple endpoints. 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 long but every sentence earns its place, packed with examples, type breakdowns, and edge-case behavior. It is front-loaded with natural-language queries that immediately signal use cases, followed by structured SUPPORTED TYPES and graceful degradation notes. No fluff or repetition.

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

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

For a tool with two entity types, no output schema, and multiple data sources, the description fully explains return values, input format, source attribution, unresolved handling, and failure behavior. It covers the complexity completely, making it a self-contained guide for an agent to invoke correctly.

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

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

Schema coverage is 100% with clear descriptions for 'type' and 'value'. The description enriches this by detailing accepted formats for value (e.g., 'AAPL', '0000320193', or company name) and specifying what each entity type returns (CIK, ticker, LEI, FIGI, RxCUI, etc.). This goes beyond the schema's basic examples, though schema already does significant heavy lifting.

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

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

The description states a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It includes concrete example queries and distinguishes itself from siblings like entity_profile by emphasizing ID lookup as a prerequisite step. The 'Use FIRST whenever you have a name but need an ID' clearly positions it against alternatives.

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 FIRST whenever you have a name but need an ID.' It also describes supported input types (ticker, CIK, name for company; brand/generic for drug) and gracefully degrades, which informs when the tool is appropriate. The mention that 'using resolve_entity replaces 2-3 manual lookups' reinforces its role as a go-to resolver.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond these: it explicitly states it probes with ai_visibility_check, ranks by score, and returns a list with score, confidence, and signal density per entity. This explains the internal orchestration and output shape, exceeding the annotation baseline.

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

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

The description is three sentences, front-loaded with the core purpose, followed by the mechanism and a concrete use case example. Every sentence adds value: the first defines the operation, the second explains the underlying call, and the third illustrates applicability and return structure. No wasted words.

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

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

Given the tool's moderate complexity (4 params, no output schema) and strong annotations, the description sufficiently covers what it does, how it works, and what it returns. It explicitly states the output includes ranking, score, confidence, and signal density, compensating for the missing output schema. The use case example also aids understanding.

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 of 3 is appropriate. The description does not add parameter-specific details beyond the schema; the schema already documents the entities array (first is subject, rest competitors), models, _apiKey, and context. The description's mention of 'your brand + N competitors' reinforces but does not extend the schema.

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

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

The description clearly states the tool's function: compare AI visibility across multiple entities side-by-side. It uses a specific verb ('probes'), identifies the resource ('each entity'), and distinguishes itself from the sibling tool ai_visibility_check by emphasizing multi-entity comparison and ranking. The purpose is unmistakable.

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

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

The description implies when to use this tool: for competitive AI-marketing audits, comparing multiple entities. It clearly indicates it wraps ai_visibility_check for multiple probes and returns a ranked comparison. However, it lacks explicit exclusions or alternatives (e.g., 'use ai_visibility_check for single-entity checks'), 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?

The description goes well beyond the readOnly/idempotent annotations by disclosing composite fan-out behavior, partial failure degradation ('Partial failures degrade gracefully'), a 5-30s latency on first bundlephobia measurement, and the meaning of 'sources_failed'. It also clarifies the return shape and ecosystem scope, adding significant context beyond the structured annotations.

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

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

Four dense sentences deliver purpose, use cases, return fields, ecosystem limitations, and failure behavior. Every sentence adds value and the most critical information is front-loaded in the first sentence. 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?

Given the tool's composite complexity and absence of an output schema, the description compensates exceptionally well. It enumerates the summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), mentions per-advisory detail, links, alternative versions, and explains timeout behavior. This is a complete picture 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 documents both params fully with descriptions (package name, scoped packages accepted; version defaults to latest). The description does not add meaningful new semantic detail about the parameters themselves, so the schema coverage 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 opens with a specific composite purpose: 'Composite "should I add this npm package to my project" check in ONE call' and names the two underlying services (deps.dev, bundlephobia). It clearly distinguishes itself from sibling tools by being the only dependency-focused scanner, and lists exactly what it returns.

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 a clear exclusion rule: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which directs users to an alternative for non-npm ecosystems.

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

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

The description discloses substantial behavioral details beyond the annotations: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and has a 200K char cap with truncation and flagging. This provides rich context beyond the readOnly/idempotent hints.

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

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

The description is well-structured and front-loaded: the opening sentence gives the core purpose, followed by usage guidance, then technical specifics. Every sentence earns its place—no fluff, and it remains informative despite 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 the tool's complexity and lack of output schema, the description is remarkably complete. It explains the return format (passages with offsets and similarity scores), the algorithm, the input cap and truncation behavior, and how to integrate with a sibling tool. This covers all essential aspects for an agent to use it correctly.

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

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

Although the schema already describes all parameters (100% coverage), the description adds meaningful context: it explains the 'text' parameter as 'the text you already pulled' with examples, gives concrete query examples, and clarifies that 'limit' controls 'top-N passages' with default 5. This enhances the schema definitions.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record,' with a specific verb (search) and resource (record). It distinguishes from siblings by emphasizing the 'inside' scope and explicitly pairing with ask_pipeworx_grounded, making its 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?

Explicit guidance is given: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This clearly states when to use it and how it relates to an alternative.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true), the description discloses critical behaviors: subscriptions are persistent, webhook signing secret returned only once, auto-disable after 10 consecutive failures, and auth requirements. These are actionable details not derivable from annotations.

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

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

The description is longer than ideal, but every sentence carries useful content. It is front-loaded with the core purpose, then organized by type and delivery channel. A slightly more compact structure would improve, but the density 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?

Given three parameters with nested objects and no output schema, the description is remarkably complete. It covers supported subscription types, param syntax, delivery options, authentication prerequisites, and edge cases (webhook secret, SMS verification, failure auto-disable). The agent has enough 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?

The schema covers all parameters with descriptions, but the tool description enriches them with concrete examples for each type (sec_8k, polymarket_edge, fred_series, etc.) and explains the delivery object's fields in depth, including verification and signing. This goes far beyond the schema's bare definitions.

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

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

The description starts with a specific verb 'Create' and clearly states the resource: 'proactive monitoring subscription to a live-data event stream.' It also mentions the return value (subscription id) and distinguishes from siblings like list_subscriptions and unsubscribe by describing the creation action.

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 prerequisites (OAuth account) and exclusions (anonymous + BYO cannot persist). Details delivery channels and per-channel constraints (SMS verified phone, 10/day cap), helping the agent decide when to use this tool and how to configure it. Sibling tools like list_subscriptions and unsubscribe are implicitly contrasted.

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, covering the safety profile. The description adds context about the live catalog and output shape, but does not disclose additional behavioral traits such as rate limits, pagination, or side effects, which are not relevant for a read-only tool.

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 comprehensive and well-structured, front-loaded with example queries and clear sections for purpose, output, usage, and when-to-use. It is somewhat verbose but every part earns its place, fitting the tool's onboarding role.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers what it does, how to call it, what it returns, and when to use it. It also provides enough context about the output shape (category-bucketed questions with tool+argument shape) and the meta-tools, 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?

Schema coverage is 100% with the 'topic' parameter fully described (allowed values and omit behavior). The description merely repeats examples ('finance', 'pharma', 'betting') that are already in the schema, adding no new semantic meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool and argument shape, positioning it as the onboarding entry point. It distinguishes itself from siblings by focusing on suggesting questions rather than answering them, and names specific meta-tools.

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

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

Explicit guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and also when learning to call meta-tools. It explains when to call with no arguments vs. passing a topic, and mentions alternatives (meta-tools) by name.

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

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

Annotations already provide safety hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true), but the description adds valuable behavioral detail beyond these: ownership enforcement and explicit deactivation rather than deletion. This directly explains the 'destructiveHint' and clarifies the tool's non-destructive nature, adding context that annotations alone do not convey. The description does not contradict any annotations.

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

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

The description is two sentences, front-loaded with the primary action, followed by concise behavioral context. Every sentence adds value with no redundancy. It is appropriately sized for a one-parameter tool.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete: it explains the action, the ownership constraint, the deactivation behavior, and the impact on historical events via recent_alerts. Combined with rich annotations, the agent has all necessary context 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 already provides a clear description for the 'id' parameter ('Subscription id (uuid) returned by subscribe.'), achieving 100% schema description coverage. The description adds the ownership constraint ('you can only cancel your own subscriptions'), which is semantically relevant to the parameter and not present in the schema. This goes beyond the baseline 3 for full schema coverage.

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

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

The description opens with a clear verb+resource: 'Cancel a subscription by id.' It specifies the action, the target, and the input mechanism. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation and referencing subscription ownership.

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 indicates when to use this tool ('Cancel a subscription by id') and adds context that ownership is enforced (only your own subscriptions). It also explains the benefit of deactivation rather than deletion, implying use when history retention matters. It does not explicitly name alternative tools or list when-not-to-use scenarios, so it falls short of a 5.

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

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

Annotations already convey read-only, idempotent, non-destructive. The description adds substantial behavioral depth: the dual pipeline (SEC EDGAR structured vs grounded fallback), the full verdict enum, and the crucial caution that 'could_not_verify' is NOT evidence, carrying verification_error and must not be shown as supporting/refuting. This is exactly the kind of context annotations do not provide and no contradiction exists.

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

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

The description is longer than average but every sentence earns its place: scannable trigger phrases, a clear one-sentence definition, concise routing explanation, verbatim return payload summary, and a highlighted IMPORTANT caveat for error semantics. The structure is front-loaded and the 'IMPORTANT for callers' box draws attention to the critical edge case 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?

Despite lacking an output schema, the description enumerates all possible verdict values, mentions the grounded actual value with citation, explains the meaning of 'could_not_verify' versus 'unsupported', and describes the integration benefit of replacing sequential calls. Given the tool's complexity, this is sufficiently complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by explaining tolerance_pct semantics: 'Overrides the tolerance implied by the claim wording — set 1–2 for hallucination detection' and 'Default: implied by wording, capped at 5.' This transforms a bare numeric parameter into actionable guidance for different use cases.

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 natural-language trigger phrases then states the verb+resource explicitly: 'natural-language claim verification against authoritative sources.' It clearly distinguishes from siblings like ask_pipeworx_grounded by defining a fact-check verdict output and the structured financial path for SEC EDGAR/XBRL.

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

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

Explicit 'Use whenever the agent needs to check whether something a user said is factually correct' gives a clear when-to-use. It also explains the two routing paths (financial vs other) and notes it 'Replaces 4–6 sequential calls' to imply efficiency over alternatives, though it does not name specific sibling tools as exclusions.

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