19hz

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

Annotations already declare readOnlyHint=true and idempotentHint=true, establishing a safe read-only profile. The description adds valuable context beyond annotations: default model (Workers AI Llama-3.3-70b), cost implications ('BYO key — you pay Anthropic directly'), and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This enriches the behavioral understanding.

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

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

The description is three sentences, each earning its place: (1) core function and output, (2) model options and cost, (3) example use cases. It is front-loaded with the action verb 'Probe,' efficient, and free of 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?

With no output schema, the description appropriately explains return values ('per-model {score, confidence, signals, raw_response} + a combined view'). It also covers model selection and use cases. Minor gaps exist (e.g., what 'signals' or 'combined view' entail), but overall it is sufficient for a tool with well-annotated safety and 4 well-described 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 description coverage is 100%, so the baseline is 3. The description does add some cost context for `_apiKey` (BYO key, pay Anthropic directly) and clarifies the default model, but the schema already thoroughly describes each parameter (e.g., `_apiKey` is 'only needed if "anthropic" is in models'). The marginal semantic addition is not enough to exceed 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 function: probing one or more LLMs for knowledge about an entity and scoring visibility (0-100 per model). It uses a specific verb ('Probe') and resource ('LLMs'). While it doesn't explicitly differentiate from the sibling tool 'scan_competitor_ai_presence', the focus on generic entities and per-model scoring provides enough specificity.

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 cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives agents context for when to invoke the tool. However, it doesn't mention alternatives or exclusions (e.g., when not to use it or which sibling tool to prefer), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context: it routes questions internally, returns structured answers with citation URIs, works on every tier, and is a single fast call. This goes beyond the annotations without contradicting them.

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

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

The description is long but densely informative, front-loaded with the primary directive 'PREFER OVER WEB SEARCH'. It uses a clear structure: purpose, usage triggers, examples, escalation path, and how it handles news. Every sentence contributes meaning; no filler or redundancy.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers the tool's role, the types of questions it handles, the return format (structured answer with citation URIs), performance characteristics (fast, single call), and relationships to sibling tools. It leaves no critical gap for an agent to misuse it.

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

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

Input schema already documents the required 'question' parameter and its aliases with 100% coverage. The description enriches this by explaining the range of acceptable questions (factual, real-world, numeric), providing concrete examples (unemployment rate, 10-K, clinical trials), and signaling that the parameter should be a natural-language query.

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 that the tool answers factual questions by routing to 5,439 tools across 1,412 verified sources and returns structured answers with citation URIs. It is explicit about the scope (SEC filings, FDA data, economic statistics, etc.) and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

It provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', trigger phrases ('what is', 'look up', 'find'), and examples. It also states when not to use it and which alternatives to step up to (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad multi-part questions).

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable context: it explicitly states 'Falls back to nothing — this IS a full working router', confirming it doesn't degrade to a fallback. It also discloses that no candidate is currently active and that it behaves identically to ask_pipeworx right now, plus that results are used for experimental comparison. This goes beyond annotations and aids trust.

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 rich with necessary details (beta status, identical behavior, routing improvements, current inactive state, usage instruction, fallback clarification) yet remains compact and well-structured. Every sentence adds value, and the critical 'use exactly like' guidance is front-loaded.

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

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

For a complex experimental router with no output schema, the description does a solid job explaining behavior, current state, and usage. It doesn't elaborate on the response shape or error behavior, but it notes 'same response shape' as ask_pipeworx, which is helpful. Given the annotations and full schema, this is reasonably complete, though a bit more detail on how it decides routing or what 'candidate improvements' means would push it higher.

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

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

Schema coverage is 100%, with all parameters documented as aliases for 'question'. The description doesn't add new parameter-level meaning, but given the full schema coverage, the baseline of 3 is appropriate. It doesn't introduce any syntax details beyond 'use exactly like ask_pipeworx', which is acceptable but not extra value.

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

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

Description clearly identifies this as a beta variant of ask_pipeworx, a universal router with 5,439 tools. It specifies the verb 'ask' and the resource (Pipeworx router), and distinguishes it from siblings by highlighting the experimental routing improvements and comparison against the stable router. However, it could be clearer about what the 'universal router' does functionally beyond the sibling name.

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?

Explains when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing'. It implies an alternative (use ask_pipeworx for stable behavior) and notes that results are compared against the stable router. It doesn't explicitly say when NOT to use it, but the experimental edge is clearly articulated.

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 details the exact return format on success (including evidence as verbatim quote) and all five possible refusal reasons on failure, going well beyond the annotations. It also discloses the internal routing behavior and the additional LLM call, providing full behavioral transparency.

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?

Five sentences each carry meaningful information: purpose, routing mechanism, success/refusal output, usage context, and cost comparison. It is front-loaded with the core purpose and stays concise given the tool's complexity. No filler or redundancy.

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

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

The description fully compensates for the missing output schema by specifying the return object's structure and all refusal reason values. It also provides scale context (5,439 tools, 1412 sources), cost trade-offs, and clear use cases, making it complete for an agent to decide when and how to invoke it.

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

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

The input schema covers all 6 parameters with 100% description coverage, including aliases and a clear explanation of 'question'. The description adds no new parameter-level semantics beyond stating it 'fills arguments' during routing, which is process context rather than parameter meaning. Baseline of 3 applies since schema already handles parameter 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 as a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers using only tool results, returning structured output with evidence and confidence. It explicitly contrasts with sibling 'ask_pipeworx' by noting the same routing but added grounding, making its unique 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?

It provides explicit usage criteria: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also states the alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost, offering a clear when-to-use vs. when-not-to-use directive.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing detailed behavioral traits: parallel fan-out, response shapes, resolver contract (market_match_confidence), safety short-circuits ('low_confidence_match'), handling of closed/dead markets, wide-spread market warnings, and resolution-rule risk (cancellation_rule). It also explains fallback behavior for news sources. No contradiction with annotations.

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

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

While long, the description is appropriately sized for the tool's complexity and is well-structured: it is front-loaded with the core purpose and usage, then systematically covers classifiers, fan-out examples, response shapes, resolver contract, safety, and resolution-risk. Every sentence carries useful information, and headers/uppercase keywords improve scannability.

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

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

With no output schema, the description fully compensates by detailing the response shape (result.market, result.analysis, result.evidence, parent_event, news fields), statuses (low_confidence_match, market_closed_or_inactive), and risk indicators. It comprehensively covers edge cases such as GDELT 429s, illiquid spreads, and cancellation rules, making the tool's behavior fully predictable 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains the three accepted input formats for 'market' (slug, URL, question text), clarifies the 'depth' quick/thorough distinction, and elaborates on 'include_raw' with reasoning for the default false and when to override. The description also provides concrete examples for each parameter.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input (market slug, URL, or question text) and the output (evidence packet + market-vs-model comparison), and it differentiates from siblings by listing explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'.

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 via 'Use for' statements and gives detailed fan-out examples for various bet categories. However, it does not explicitly mention when NOT to use this tool or name alternative sibling tools, which would fully meet the 'explicit when/when-not/alternatives' criterion.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses key behaviors: it pulls from SEC EDGAR/XBRL for companies and FAERS/FDA for drugs, handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. This gives the agent a clear picture of what happens during execution and what to expect in the response, far exceeding the bare 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 intent-matching examples, then immediately states the core capability and key details. Every sentence contributes useful context—data sources, sorting, output format, and efficiency gain—without fluff. It's dense but highly scannable.

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 entity types, multiple metrics, sorting, citations), the description covers all essential aspects. While there is no output schema, the description clarifies return format ('paired data + citation URIs') and the range of inputs, making it sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The description enriches the schema by explaining the meaning of each 'type' value: for companies it pulls specific financial metrics, for drugs it pulls adverse-event and trial counts. It also gives concrete examples of valid 'values' (tickers, drug names) and reiterates the 2–5 limit, adding meaning beyond the minimal schema descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It uses specific verbs ('compare', 'rank') and enumerates the entities and data types covered, making it distinct from sibling tools like entity_profile or deep_research.

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

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

Explicit usage guidance is provided: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also delimits the tool's scope with concrete examples of user queries ('which is bigger', 'rank these companies') and differentiates between company and drug lookups, ensuring the agent knows when to invoke 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?

Goes far beyond the annotations' read-only/idempotent hints, disclosing account/tier requirements, parallel routing to 5,439 tools, never-invented gaps[], contradictions[] for standard/thorough, semantic excerpting, hop fields, citation URIs, and expected latency. No contradiction with annotations.

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

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

The description is long but densely packed with essential operational details—each sentence contributes unique information about depth behavior, citations, gaps, or timing. It is front-loaded with the account requirement and alternative tool. A bulleted structure might improve scannability, but the content earns its length.

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

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

Given the tool's complexity and lack of an output schema, the description fully defines the return format (evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field), source scope, depth semantics, timing, and exclusions. An agent can confidently select and invoke this tool without ambiguity.

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

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

Although the schema documents both parameters at 100% coverage, the description adds substantial semantics: depth is elaborated with facet counts, gap-recovery behavior, and the paid requirement for 'thorough'; question guidance explicitly allows broad/multi-part natural language. This is valuable beyond the enum descriptions.

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

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

The description clearly states the tool performs multi-source structured research, decomposing questions into facets and returning a findings packet. It explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx, making its purpose and scope unambiguous.

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

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

Provides explicit when-to-use and when-not-to-use guidance: best for broad/multi-part questions over structured data; for single lookups or breaking/current news, prefer ask_pipeworx. Also notes account requirements and that depth:'thorough' needs a paid plan, with an alternative for unsigned users.

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 mark it read-only, idempotent, and non-destructive. The description adds that it returns top-N results with full input schemas and curated examples that are directly callable without a second lookup, which is meaningful behavioral context beyond the annotations.

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

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

The description is roughly four sentences, with the purpose stated in the first line, domains listed compactly, and the return format and usage advice following. Every sentence contributes to understanding, with 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?

Despite having no output schema, the description explicitly states what is returned (top-N tools, names, descriptions, full schemas, curated examples) and clarifies that results are directly callable. Combined with strong annotations and complete schema, this covers the context needed for an agent to use the tool effectively.

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

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

The input schema has 100% coverage for all six parameters, including aliases for the query. The description reinforces that the query is a natural-language task description and that 'limit' controls the top-N count, but the schema already documents these clearly, so the description adds only marginal value.

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

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

The description opens with 'Find tools by describing the data or task' — a specific verb+resource. It enumerates supported domains (SEC filings, FDA drugs, etc.) and states it returns tool schemas, clearly distinguishing this discovery tool from sibling research tools.

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

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

It explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available', providing strong when-to-use context. However, it does not name specific alternative tools to use instead in other cases, so it stops short of a 5.

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

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

Despite annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint:false) already covering safety, the description adds valuable behavioral context: it 'fans out' across multiple sources 'in ONE parallel call', mentions the 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated', and notes the 'GDELT→GNews fallback'. 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 contributes: example queries, preference directive, fan-out details, output breakdown, and parameter constraints. It is dense but efficiently structured, with front-loaded examples and clear limitations. Slightly verbose but not wasteful.

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

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

With no output schema, the description carries the burden of explaining return values—and it does: cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions, LEI. It also covers the soft-fail behavior and the name/CIK constraint. This is a complete picture for a multi-source tool.

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

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

Schema description coverage is 100% and both parameters are already well-documented (ticker/CIK, type enum). The description restates the 'names not supported' rule and provides examples, but does not add new meaning beyond the schema. Thus baseline 3 applies.

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

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

The description uses a specific verb ('full cross-source profile') and resource ('US public company'), grounding it with example queries like 'Tell me about X' and 'company profile for Microsoft'. It also distinguishes from siblings by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and directing name-only inputs to resolve_entity.

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

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

Explicitly states when to use: 'when the user asks for a holistic view'. Provides clear exclusions: 'names not supported (use resolve_entity first if you only have a name)' and warns against chaining simpler lookups. This is textbook guidance on choosing 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 read-only, idempotent, and non-destructive behavior. The description adds that results are 'normalized events sorted by date,' providing useful behavioral context beyond the annotations. No contradictions found.

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

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

Three concise, information-dense sentences: the purpose is front-loaded, and every phrase adds value without redundancy. 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 list operation with strong annotations and fully documented parameters, the description covers the essential behavior: what it lists, optional filters, and return format ('normalized events sorted by date'). It lacks explicit output field details or pagination explanation, but the limit parameter and normalization note are sufficient for this simplicity level.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces existing parameter semantics (keyword matches title/venue/genre/artist, date window) but does not add new parameter-level details beyond what the schema already provides. Thus, it earns the baseline.

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

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

The description opens with a specific verb and resource: 'List upcoming electronic/dance music events for a 19hz region.' This clearly distinguishes it from sibling tools like regions or recent_changes, making the tool's purpose immediately obvious.

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 conveys the core use case—listing upcoming events for a region—and mentions optional keyword and date filters, implying when to use it. It does not explicitly state exclusions or alternatives, but the context is clear enough for an agent to select it without confusion.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds useful context that it applies to 'previously stored memory' and emphasizes clearing 'sensitive data,' which goes beyond the annotations. No contradiction with annotations.

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

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

Three short sentences: purpose first, then usage triggers, then companion tools. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple tool with one required parameter, no output schema, and informative annotations, the description covers purpose, usage context, and relation to related tools. It is sufficiently complete without needing to document return values or error handling.

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

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

Schema coverage is 100%: the single parameter 'key' is already described as 'Memory key to delete.' The description repeats 'by key' but does not add extra meaning about key format, lookup, or origin. Baseline 3 is appropriate, as the schema carries the semantic load.

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 ('Delete') and resource ('previously stored memory') with a clear method ('by key'). It distinguishes from siblings like 'remember' and 'recall' by implying delete versus store/retrieve, 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?

Provides explicit triggers ('Use when context is stale, the task is done, or you want to clear sensitive data') and references companion tools ('Pair with remember and recall'). However, it does not explicitly state when not to use the tool or name alternatives for the same operation, 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 beyond the readOnlyHint/idempotentHint annotations by explaining the fetch-extract-emit process and the standard llms.txt markdown output format. It doesn't cover error cases, but annotations already establish the safety profile.

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

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

The description is compact and front-loaded: three sentences plus a bulleted use-case list. Every sentence earns its place, providing purpose, process, output, and applications 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 two-parameter tool with strong annotations, the description is complete: it covers purpose, process, output format, and use cases. No output schema is needed because the description explicitly states the output is a text blob ready for site-root placement.

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 both url and max_links are already fully documented. The description adds no parameter-level detail beyond echoing 'for any URL' for the url parameter, 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 it generates a production-ready llms.txt file for any URL, with a specific verb+resource. It details the extraction and output pipeline, and the use cases differentiate it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on analysis rather than file generation.

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

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

The 'Useful for:' list gives clear context for when to use the tool (client indexing, own project, competitor audit). It lacks explicit exclusions or alternative tool mentions, so it doesn't earn a 5, but the context is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description adds behavioral context by specifying that it returns the caller's active subscriptions and lists the response fields. It also implies default behavior of excluding inactive subscriptions, 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 two sentences, with the primary purpose front-loaded, followed by the return fields and a clear use case. No filler or redundant information—every sentence earns its place.

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

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

For a simple list tool with one optional boolean parameter and strong annotations, the description is complete. It covers what is listed, the return fields, and when to use it, leaving no critical gaps.

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

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

The only parameter, include_inactive, is fully described in the schema with a default note. The tool description adds no additional semantic meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'List the caller's active subscriptions.' It also distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing, and enumerates the exact fields returned.

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

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

The description provides clear context on when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies using this before subscribe/unsubscribe but does not explicitly name those alternatives, so it lacks a full when-not-to-use statement.

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?

With all annotations set to false, the description carries full responsibility for behavioral disclosure. It goes beyond the basics by stating rate limits (5 per identifier per day), that it's free and doesn't count against quota, that the team reads digests daily, and that users should not paste end-user prompts. This gives agents a complete picture of side effects and constraints.

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 fast-paced: it front-loads the purpose, then covers usage, exclusions, content guidance, and policies in a compact sequence. Every sentence adds value, though the dense wall of text could benefit from bullet points or stronger visual separation. No fluff, but slightly heavy.

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

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

This tool has 3 parameters (2 required), nested objects, no output schema, and no helpful annotations. The description covers all aspects an agent needs: when to use, what to include, what not to include, limits, and effect on roadmap. It is fully 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 each parameter having a detailed description (enum meanings, message guidance, context fields). The description adds some extra instruction (e.g., 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), but this is supplementary rather than essential. Baseline 3 is appropriate since the schema already 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 opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This immediately distinguishes it from sibling tools like ask_pipeworx (asking questions) and remember (storing info), making the tool's unique role obvious.

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

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

It explicitly states when to use this tool: for bugs, feature requests, data gaps, praise, and other. It also provides a clear exclusion: only for tools served by this Pipeworx connection, and directs users to file elsewhere for other MCP servers. This is excellent when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds valuable context beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This discloses data provenance, privacy, and caching behavior.

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

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

The description is three sentences, front-loaded with the main action, and uses a structured list for use cases. Every sentence earns its place, with no filler or repetition of annotations.

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 is complete. It specifies the return content (top tools, top packs, total call volume), the duration options, and the underlying data source, making the tool's behavior effectively self-contained.

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

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

Schema description coverage is 100% for the window parameter, already explaining the enum values and their trade-offs. The tool description redundantly mentions '24h, 7d, or 30d' but adds no new semantic nuance beyond the schema. Baseline 3 applies because the schema handles parameter meaning.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window' with specific time options. It is a distinct verb+resource combination and differentiates from sibling tools like discover_tools by focusing on aggregated call trends rather than searching for 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: (1) discovering hot data sources, (2) confirming a canonical tool, (3) aligning with agent needs. It gives clear context for when to use the tool but does not explicitly state when not to use it or name alternatives, which would fully meet the 'when-not' guideline.

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

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

Beyond readOnly/other annotations, the description discloses algorithmic behaviors: the partition filter with 20% placeholder threshold, the semantic anchor with 0.30 Jaccard similarity, the fill check with realizable_edge_pp against CLOB depth, and the warning 'realizable_edge_pp ≤ 0... do not trade it'. It also explains skipped_low_similarity and output structure, providing comprehensive behavioral context.

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

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

Though long, every sentence earns its place for a two-mode arbitrage tool. It's front-loaded with the core purpose, then organized into clear labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) with no filler. The structure makes dense information scannable.

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 must explain return values, and it does: opportunities[] with fields and partition_check fields. It also covers edge cases (filters, fill validation, when not to trade), directs to polymarket_fill_risk for complementary needs, and handles both modes. Fully 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%, so baseline is 3, but the description adds deep meaning: it explains event slugs with examples, topic seed questions, what each mode does internally (walks child markets, checks orderings, partition sum), and which to choose. It elevates parameter understanding far beyond the schema's simple type/description.

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

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

The description opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', giving a specific verb, resource, and mechanism. It clearly distinguishes from siblings like polymarket_edges and polymarket_fill_risk by describing unique arbitrage detection and fill-price validation functionality.

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

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

Explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'pass event for...', 'or topic for...'. It recommends event mode for specific markets, explains cross-event mode catches patterns single-event misses, and directs custom sizing to 'polymarket_fill_risk'. This is exemplary when-to-use guidance.

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

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

Given the annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior, the description adds substantial behavioral context beyond them. It discloses caching ('Cached 1h at the KV level keyed on all knobs'), the 24h-move warning, the unreliability of Fed signals, and the fact that diagnostics reveal why segments are empty. No contradiction with annotations is present.

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 exceptionally dense and front-loaded with the core purpose, but it is also very long and presented as a single block of text. It is organized by segment categories (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.), which helps, but the sheer volume of detail could be more concise. Every sentence does add value, yet it would benefit from clearer formatting or segmentation.

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 provided, the description fully compensates by enumerating the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics) and explaining what each opportunity carries (edge_pp_net, kelly_fraction, etc.). It also covers edge cases like 'why a segment is empty' and the rare-by-design nature of concentrated_longshot, making it contextually 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?

Even though schema coverage is 100%, the description enriches parameter understanding significantly. It explains the nuanced behavior of min_partition_leg_kelly (parent-level Kelly is always 0 for partition arbs), provides context for slippage_pp (Polymarket fees as of 2024, typical bid/ask costs), and clarifies the tradeable-edge knobs (min_liquidity, max_spread_pp) with recommended values. This goes well beyond the schema's descriptions.

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

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

The description clearly identifies the tool's purpose ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and its intended use case ('what should I bet on today'). It is specific about the resource and outcome, but it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which limits the distinctiveness to a 4.

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 strong usage context, stating it is built for 'what should I bet on today' and avoiding the need to page hundreds of markets. It also gives practical guidance on setting knobs (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). However, it lacks explicit 'when not to use' or alternative tool references, so it earns a 4 rather than 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 declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: snapshot history depth is limited by a 60-day TTL and snapshotting start date, gaps mean no scan, decay is computed from daily closes of |edge_pp_net|, and the sign convention (negative = SELL YES). This goes far beyond the annotation 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 long but every sentence earns its place: purpose, parameters, response format, and limitations are clearly delineated. It is front-loaded with the purpose and uses labeled sections (RESPONSE, LIMITS) for scannability.

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

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

With no output schema, the description fully specifies the response structure (tracked, expired, snapshot_dates) and explains the meaning of each field. It also covers edge cases like missing snapshot days and TTL boundaries, making it 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?

Schema description coverage is 100%; both days and window already have descriptions. The description merely echoes the defaults ('default 14, max 30', 'default "1wk"') without adding new semantics, so it hits the baseline of 3.

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

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

The opening line 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' clearly identifies the tool's function. The rhetorical question 'how long has this edge existed and is it shrinking?' adds a concrete use case, and the contrast with a '3-week-old wide edge' distinguishes it from a simple current-edge lookup (e.g., sibling polymarket_edges).

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

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

The description frames the tool as answering a specific persistence/decay question and explains the trade rationale ('the latter is wide for a reason nobody is willing to take'), which implies when to use it. However, it never explicitly names alternative tools or states when not to use it, so it lacks the explicit exclusions 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 declare readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral context: it walks the order-book ladder, returns specific metrics (top_of_book, slippage_pp, shares_filled), and warns about partial basket fills converting an arb into an unhedged directional position. This goes far beyond the annotations.

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

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

The description is long but densely informative, with no filler. It is front-loaded with the core purpose and then uses clear section markers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) to structure a complex tool. It loses a point only for being somewhat overwhelming in length, though this is justified by the tool's complexity.

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

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

Given the tool's complexity, no output schema, and four parameters, the description is remarkably complete. It enumerates return values for both modes, explains the verdict values, details the basket output fields, and covers risk scenarios, leaving the agent well-equipped to invoke the tool correctly.

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

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

Schema coverage is 100%, and the description enriches parameter meaning well beyond the schema. It explains how size_usd is interpreted differently for single-market (max spend / target proceeds) versus basket (settlement notional), and clarifies side defaults including the auto mode based on partition sum.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by directly positioning itself as a pre-trade validation step for polymarket_arbitrage and polymarket_edges, and it differentiates single-market and basket modes.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also clarifies mode selection (single-market vs basket) and default behaviors, giving clear practical guidance.

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

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

Even with annotations indicating a read-only, idempotent operation, the description adds substantial behavioral context: it details the two compatibility_warning scenarios (with specific conditions), explains temporal_alignment and its impact on spread validity, and describes skipped_cross_type counters. This goes well beyond what annotations declare.

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-organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS), but it is quite long. While every sentence contributes, a slightly more concise version could improve quick parsing. Still, the structure earns a high score.

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

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

Given there is no output schema, the description fully specifies the response structure: each venue's leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning, and temporal_alignment. It also covers edge cases and skipped counter semantics, making the tool self-explanatory for an agent.

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

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

Schema coverage is 100%, but the description enriches parameter meaning: it clarifies the mode selection ('topic' vs explicit overrides), lists all valid topic values, and explains how kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. This is significant added value over the schema's per-property 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb+resource+scope that immediately distinguishes it from sibling tools like polymarket_arbitrage. It also names two modes ('topic' and 'explicit'), further clarifying the tool's functionality.

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 details when to use each mode, lists the valid topic shortcuts, and explains that explicit parameters override topic-mapped defaults. It also warns that many pre-mapped topics return compatibility_warning and that 'pre-mapped ≠ tradeable,' which is clear guidance about when the tool may not be 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 readOnly/idempotent/non-destructive, so the description only adds value. It adds useful scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior of omitting the key to list all keys, which goes beyond annotations.

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

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

Three front-loaded sentences cover the function, use case, and scoping without any fluff. Every sentence contributes meaningful information, making it appropriately sized and structured.

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

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

For a simple 1-parameter, optional-key tool, the description fully explains both invocation modes, typical use cases, related tools, and scoping. Annotations cover safety, and an output schema is unnecessary since the description clarifies return behavior (value or list of keys).

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% coverage of the single parameter with the same instruction ('omit to list all keys'). The description repeats this and provides examples of stored values, but does not add new syntax or format details. Thus, it stays at the baseline of 3 for high schema coverage.

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

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

The description starts with the specific verb 'Retrieve' and the resource 'value previously saved via remember', also covering the alternative mode of listing all saved keys. It distinguishes itself from siblings by explicitly naming 'remember' and 'forget' and explaining the omit-key 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?

It explicitly says 'Use to look up context the agent stored earlier' and provides concrete examples, plus the rationale 'without re-deriving it from scratch'. It also positions itself within a workflow by mentioning pairing with 'remember' and 'forget'.

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?

Annotation Contradiction: The annotations declare readOnlyHint: true, but the description describes mark_read:true as flagging returned events read, which changes state. This contradicts the read-only annotation. No other behavioral details like rate limits or auth are provided.

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

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

The description is concise, with three sentences that front-load the purpose, then detail output fields, filtering, mark_read behavior, and an alternative access method. Every sentence is informative and there is no 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 description covers the key aspects: what events are returned, their structure, filtering options, mark_read semantics, polling suitability, and an alternative endpoint. Though limit and unread_only are not explicitly mentioned in the description, they are documented in the schema, and the overall description is thorough 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 schema covers all 5 parameters with descriptions (100% coverage). The description adds value by giving a concrete type example ('sec_8k') and explaining the side-effect of mark_read on subsequent calls, which 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 description clearly states the tool 'Pull fired events from your subscription feed' and specifies the output fields (source, citation_uri, raw event payload). It distinguishes itself from sibling tools by focusing on the evaluator's persisted feed and polling 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?

The description provides usage context by noting polling works fine and offers an alternative HTTP endpoint for scripts/dashboards, which helps in deciding when to use this tool. However, it does not explicitly compare with sibling tools like 'events' or 'list_subscriptions'.

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 richly discloses behavior beyond the annotations: it fans out to multiple sources in parallel, describes a fallback from GDELT to GNews on rate-limiting or 5xx errors, mentions the PatentsView API sunset causing a soft-fail, and specifies the return structure. This gives the agent a clear picture of what to expect, including edge cases.

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: example queries, source fan-out details, fallback behavior, since format, return shape, and an explicit alternative. It front-loads the most actionable information and avoids 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 multi-source aggregation tool with no output schema, the description fully covers the return value (changes grouped by source, total_changes, citation URIs), the data sources, fallback logic, and parameter syntax. No critical detail is missing 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 documents all three parameters with 100% coverage, so the baseline is 3. The description adds value by providing concrete examples for 'since' (ISO date, relative shorthand) and recommending '30d' or '1m' for typical monitoring, which is not in the schema. This is a modest but meaningful enrichment.

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 change feed for a company over a time window, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes itself from the sibling entity_profile by explicitly noting that entity_profile provides the static profile instead.

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 opens with natural language queries that indicate when to use the tool ('What's new with X'), and explicitly states 'Use entity_profile instead when you want the static profile...' This provides a clear alternative and usage boundary. It also implies this tool is for time-boxed changes rather than persistent profiles.

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. The description adds useful behavioral context beyond annotations by specifying the data scope ('19hz covers'), output format ('slug + label'), and domain focus ('electronic/dance music focus'). It does not contradict annotations.

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

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

The description is two sentences: the first states the primary purpose and output, the second provides a usage note and domain context. Every sentence adds value, and the most critical information is front-loaded.

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

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

Given the tool's simplicity (zero params, no output schema), the description is complete. It specifies the return value (slug + label), the coverage scope (19hz), the domain focus, and the relationship to the events tool, which fully covers what an agent needs to know to use 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 tool has zero parameters, so the baseline for parameter semantics is 4. The schema is empty and fully covered. The description adds no parameter details because none exist, but it does indicate that the output (slug) is used as an input to the events tool, adding related semantic context.

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

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

The description clearly states the tool's function: 'List the regions 19hz covers (slug + label).' This uses a specific verb ('List'), identifies the resource ('regions 19hz covers'), and specifies the output fields ('slug + label'). It also distinguishes itself from siblings by noting it is a precursor to the events tool.

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

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

The instruction 'Pass a slug to the events tool' provides clear usage guidance by explaining how the output connects to an alternative tool. However, it does not explicitly state when not to use this tool or contrast it with other region-related tools, so it lacks full exclusion guidance.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description adds critical behavioral details: memory is scoped by identifier, persistence depends on authentication, and anonymous sessions have a 24-hour TTL. It also explains the relationship with companion tools, enriching the agent's understanding of state changes.

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

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

The description is well-structured with a clear lead sentence, usage guidance, behavioral details, and companion tool references. While slightly long, each sentence contributes unique value and there is no redundancy, so it earns a 4.

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

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

For a simple 2-parameter tool with no output schema, the description adequately covers purpose, usage, and state behavior. The primary gap is the lack of mention of return value/confirmation, but this is minor given the tool's simplicity. The description is complete enough for effective use.

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

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

The input schema already provides 100% coverage with clear descriptions for both 'key' and 'value.' The description adds only marginal context (e.g., examples of values, key-value pair nature) but does not significantly enhance parameter understanding beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool's function with a specific verb ('Save data') and resource ('data... key-value pair'). It distinguishes itself from siblings by explicitly pairing with 'recall' and 'forget,' 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?

Provides explicit usage guidance with concrete examples ('a resolved ticker, a target address, a user preference') and contextual trigger ('when you discover something worth carrying forward'). It also clarifies scope (persistent vs 24-hour) and mentions complementary tools, effectively helping the agent decide when to use this tool.

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

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

The description adds behavioral context beyond the annotations (readOnly, idempotent) by explaining the internal cascading through multiple lookup endpoints, auto-disambiguation for company inputs, and the citation URIs in the output. It doesn't contradict the annotations and provides useful operational details that an agent would need to understand the tool's 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 dense but well-structured. It front-loads the purpose with examples, then separates supported types into a clear list, and ends with a rationale for using the tool. Each sentence carries useful information without excessive verbosity, earning a 4 rather than a 5 due to its length.

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

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

Given there is no output schema, the description effectively explains the return values for both entity types, including ticker, CIK, company_name, and citation URI for companies, and RxCUI, ingredient, brand, and citation for drugs. It also mentions the internal lookup process. It doesn't cover failure modes or edge cases, so it falls short of a 5.

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

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

The input schema already covers both parameters with examples, so the baseline is 3. The description adds extra meaning by explaining the auto-disambiguation behavior for company values and clarifying that drug accepts both brand and generic names. This goes slightly beyond the schema's descriptions, justifying 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 clearly states the tool's function: resolving a user-spoken name to a canonical/official identifier. It uses specific verbs like 'resolve' and provides concrete example queries ('What's the ticker for…', 'find the CIK for…'). It also distinguishes itself from sibling tools by noting it returns IDs that other tools require, making its 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 gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details the supported types and what each returns, and notes the internal cascading to justify efficiency. However, it doesn't mention alternatives or explicitly state when not to use this tool, so it misses the top score.

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 annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context beyond this: it explicitly says it 'probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and returns 'a ranked list with score, confidence, signal density per entity.' This provides useful operational detail without contradicting the annotations.

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

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

The description is four sentences, each adding value: purpose, method, use case, and output. It is front-loaded with the primary intent and contains no filler or repetition. This is concise and well-structured.

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

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

Given the complexity (4 parameters, no output schema), the description covers the essential context: the process (probes, ranks, surfaces), the return structure (ranked list with score/confidence/signal density), and the intended use case. It doesn't explain potential caveats like rate limits or the exact handling of the first entity as subject, but the schema covers the entity roles. Overall it is nearly complete for a read-only analytical tool with good annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some context about entity roles ('your brand + N competitors') and the mention of 'which models to probe' in the schema, but the description itself does not substantially enhance parameter semantics beyond what the schema already specifies. It is adequate but not beyond 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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare/probe/rank), the resource (AI visibility across entities), and the output (ranked list). It distinguishes itself from sibling tools like ai_visibility_check (which likely checks a single entity) and compare_entities (generic comparison) by focusing specifically on AI presence and mentioning the probe mechanism.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' This tells the agent when to use it. However, it does not explicitly mention when not to use it or name direct alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds valuable context beyond annotations: partial failure behavior ('sources_failed will list it if it times out, the rest still returns'), performance expectations ('first measurement on a new version can take 5-30s'), and return value details (summary block fields, per-advisory detail, links, alternatives). 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 fairly long but well-structured and front-loaded with the core purpose. It includes necessary details about return fields, ecosystem scope, and failure behavior without obvious redundancy. Slightly verbose listing of summary fields could be tightened, but every sentence earns its place.

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

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

There is no output schema, yet the description comprehensively explains return values (summary block fields, per-advisory detail, links, alternative versions). It also covers timing, partial failures, ecosystem limitations, and default behavior for the version parameter. Given the tool's moderate complexity, this is highly complete.

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

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

Schema coverage is 100% with both parameters fully documented ('npm package name... Scoped packages accepted' and 'Defaults to the latest published version when omitted'). The description adds minimal extra parameter meaning, mostly restating that version is optional and defaults to latest. This meets the baseline but does not exceed it.

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 is a 'Composite should I add this npm package to my project check in ONE call', with specific verbs and resources (deps.dev + bundlephobia). It distinguishes from sibling tools by explicitly noting the NPM-only scope and directing other ecosystems to deps.dev:version directly.

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

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

The description provides explicit usage triggers: 'Use whenever an agent asks "is X safe / popular / small"' and clarifies exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. This tells the agent both when to use and when not to use the tool.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses technical behavior: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation and flagging, and return of character offsets and similarity scores. This is rich behavioral context not present in schema or 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. It front-loads the core action, then covers use case, sibling pairing, and technical specifications in a logical order. There is no filler or redundancy.

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

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

Given the tool's complexity and the absence of an output schema, the description fully covers what the tool returns (passages with character offsets and similarity scores), its limits (200K char cap with truncation flagging), its algorithm, and its integration with ask_pipeworx_grounded. This is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds behavioral nuance for the text parameter ('longer inputs are truncated and flagged') beyond the schema's 'max ~200K chars,' and contextualizes the query with examples. However, most parameter semantics are already in the schema, so the extra value is moderate.

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 'Semantic search INSIDE a fetched record,' clearly identifying the action (semantic search) and resource (a fetched record). It details the inputs and outputs, and distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded, which provides 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?

It explicitly states when to use it: 'Use when the record is too big to cram into the prompt — search_within saves context...' and explains the relationship with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages instead of the whole document'). This provides clear usage guidance and 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, idempotentHint true, destructiveHint false), the description discloses the OAuth requirement, SMS verification and 10/day cap, webhook signing secret returned once, and auto-disable after 10 consecutive failures. This adds substantial behavioral detail not present in 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 dense but front-loaded with the core purpose, followed by prerequisites, type examples, and delivery details. Every sentence adds value, and the structure logically guides from purpose to constraints to specifics. 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 the tool's complexity (3 params, nested objects, no output schema), the description covers the return value, prerequisites, supported types, delivery channels, and operational limitations. This is comprehensive enough for an AI agent to invoke the tool correctly without ambiguity.

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

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

Schema coverage is 100%, but the description goes further by giving concrete examples for each type (sec_8k items, polymarket_edge topic, fred_series series_id) and detailed delivery options (phone verification, webhook signature format). This significantly enriches the schema and enables correct parameter construction.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb-resource pair that distinguishes the tool from siblings like list_subscriptions and unsubscribe, and also mentions the output.

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 valuable usage context: it requires a Pipeworx OAuth account (anonymous/BYO cannot persist) and notes that the feed is always on, referencing recent_alerts for retrieval. However, it does not explicitly name alternatives or say 'use this when X', 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 safe read-only and idempotent behavior; the description adds useful context: it draws from the live catalog, returns category-bucketed suggestions, and supports both no-argument and topic-focused calls. There is no contradiction with annotations.

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

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

The description is long but information-dense: it front-loads the use case, then gives return behavior and parameter guidance. Every sentence contributes value, though it could be slightly tighter by trimming the repeated example queries.

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 required parameters and no output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shapes) and how to scope via topic. It is complete for a zero-required-param onboarding tool.

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

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

Schema coverage is 100%, and the schema already fully documents the optional `topic` parameter with its allowed values and default behavior. The description's mention of "finance, pharma, betting" adds no new semantic detail beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with natural-language queries and identifies itself as "the onboarding entry point," clearly stating it returns category-bucketed example questions with the exact tool and argument shape. This makes it distinct from sibling tools like discover_tools or ask_pipeworx.

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

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

It explicitly says "Use this FIRST when you do not yet know what Pipeworx can do for you," giving strong usage context. It falls short of a 5 because it doesn't mention when not to use it, though it does reference learning to call meta-tools as a follow-up.

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 a non-read-only, non-destructive, idempotent operation. The description goes beyond by specifying ownership (auth requirement), that the row is deactivated rather than deleted, and that historical events persist. These are critical behavioral details not in 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?

Three sentences, each providing distinct value: action, ownership constraint, and deactivation side-effect. 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 one-parameter mutation with no output schema, the description covers action, authorization, data lifecycle, and onward history retrieval. It is complete for the tool's complexity and 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?

The sole parameter 'id' is fully described in the schema as a uuid from subscribe. The description adds the semantic constraint that the id must be the caller's own subscription, which is not in the schema. This meaningful addition justifies 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 'Cancel a subscription by id', using a specific verb and resource, and distinguishes from siblings like subscribe and list_subscriptions by focusing on cancellation. The ownership enforcement clarifies 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?

It states ownership is enforced, guiding that only own subscriptions can be cancelled, which is a clear usage constraint. It also notes that historical events remain available via recent_alerts, implying how to retrieve history after cancellation. No explicit alternatives are named, so it falls short of a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the dual-path routing logic, exact percent-delta math, the verdict categories returned, verbatim evidence citations, and that it replaces 4–6 sequential calls. No annotation contradiction exists.

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

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

The description is front-loaded with examples and a clear definition, and every sentence contributes useful information about routing, return values, or use case. It is slightly verbose due to the query examples and detailed return-value enumeration, but appropriately sized for the tool's complexity.

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

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

With no output schema, the description fully covers return values (verdict categories, grounded/structured actual value with citation, reasoning), routing behavior for financial vs. other claims, and tolerance overrides. For a two-parameter tool with rich annotations and a clear behavioral contract, the description is complete.

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

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

Schema description coverage is 100% and both parameters already have detailed descriptions. The tool description reinforces tolerance behavior ('exact percent-delta math', 'capped at 5', hallucination detection) and gives claim examples, but it does not add material meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description opens with concrete natural-language examples and defines the tool as 'natural-language claim verification against authoritative sources.' It clearly distinguishes financial-claim handling via SEC EDGAR/XBRL from any other factual claim going through the grounded pipeline, setting it apart from generic research or entity-comparison siblings.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and explains how financial vs. non-financial claims are routed. It does not name sibling tools as alternatives or provide explicit when-not-to-use guidance, so it has clear context but lacks exclusions.

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