nvd

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

Beyond the annotations (read-only, non-destructive), the description discloses important behavioral context: it makes external API calls, that Anthropic calls are billed directly to the user, and that the default model is free. This adds value beyond the structured 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 three sentences, front-loaded with the core function, then important caveats, then use cases. No wasted words.

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

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

Despite no output schema, the description specifies the return structure (per-model score, confidence, signals, raw_response, combined view). It also covers cost implications and prerequisites (_apiKey). This makes 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 covers 100% of parameters, but the description adds relational context: clarifies `_apiKey` is only needed when 'anthropic' is in `models`, and explains the default model. This is beneficial but not comprehensive since `entity` and `context` semantics are only in the schema.

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

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

The description uses the specific verb 'Probe' and clearly identifies the resource (LLMs) and the scope (business/brand/product/topic). It also states the output (score 0-100) and distinguishes from sibling tools by mentioning AI-marketing audits, pre-launch checks, and competitive monitoring, which differentiates from tools like scan_competitor_ai_presence.

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

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

Provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), which tells the agent when to use it. However, it does not explicitly name alternative tools or exclusion criteria, so it falls short of the top level.

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

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

Annotations already declare safety traits (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). The description adds valuable behavioral context: dynamic routing, argument filling, stable citation URIs, and 'works on every tier, one fast call'. No contradiction with annotations.

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

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

The description is dense and front-loaded with the key recommendation ('PREFER OVER WEB SEARCH'), followed by categories and examples. Some minor redundancy (e.g., listing many example queries) but overall well-structured and justified for a tool with broad applicability.

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 routing tool with no output schema, the description covers purpose, usage triggers, alternatives, examples, and return behavior (structured answer with citations). It lacks exhaustive output format details, but that is not critical for tool selection and invocation.

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

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

Input schema coverage is 100%, including the question property with alias descriptions. The description does not add parameter-specific semantics, but it provides usage examples in the schema. Baseline 3 is appropriate since the 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 states the tool routes questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with pipeworx:// citation URIs. It distinguishes itself from ask_pipeworx_grounded and deep_research by framing itself as the default entry point for most factual questions.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and specific conditions for stepping up to ask_pipeworx_grounded or deep_research. It also gives concrete examples of query types and a fallback note for breaking news, making when-to-use unambiguous.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context about the experimental nature: candidate routing improvements are enabled live whenever under test, and currently no candidate is active so it matches ask_pipeworx exactly. It also mentions the comparison process and retirement date, which are not derivable from 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?

The description is dense but every sentence contributes: beta status, equivalence to stable, current state, usage direction, comparison purpose, and fallback behavior. It is front-loaded with the core purpose and avoids redundant phrasing. Despite multiple sentences, it is concise for the complexity it covers.

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

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

The tool is a router with a simple one-question schema and strong annotations. The description adds essential context about its experimental nature, current equivalence to stable, and intended usage. It omits specific response shape details but references 'same response shape' as ask_pipeworx, which is acceptable given the sibling context. Overall, it is complete enough for an agent to select and invoke correctly.

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

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

The input schema has 100% coverage, explaining that all six parameters are aliases for the required 'question' field. The description does not add parameter-level detail, but none is needed since the schema is thorough and unambiguous. This meets the baseline for schema-heavy 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 identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements. This provides a specific verb+resource+scope and differentiates from 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 gives explicit usage direction: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router for merge decisions. It also clarifies that it does not fall back to anything, ensuring the agent knows it is a fully functional router. This is clear when-to-use and alternative guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the output structure, five refusal reasons, the extra LLM call cost, and the fact that it routes across 5,529 tools. This significantly enriches behavioral understanding beyond annotations.

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

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

The description is somewhat long but every sentence carries important information about usage, output, and failure modes. It is front-loaded with the core purpose. Slight redundancy (e.g., 'tool result' mentioned multiple times) prevents a 5.

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

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

For a tool with no output schema, the description fully covers return values, error/refusal handling, cost implications, and relationship to sibling tools. It is complete enough for an agent to confidently 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?

Schema coverage is 100% with the 'question' parameter and all aliases clearly described. The description adds no new parameter-level information, but the schema already does the job, 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 clearly identifies this as a hallucination-resistant answer mode that routes through the same pipeline as ask_pipeworx but extracts answers solely from tool results. It distinguishes itself from siblings by emphasizing 'grounded' extraction and explicit refusal 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?

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups,' with the alternative tool named. Also lists high-stakes domains like financial verdicts and legal claims.

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 by detailing resolver match confidence, status codes for low-confidence and closed markets, GDELT/GNews fallback behavior, parent_event extraction, and cancellation-rule risk. All of this is disclosed without contradicting the read-only/idempotent 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 extremely well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded purpose and usage. Every section adds meaningful detail, though some repetition (e.g., blocking routes explanation) could be trimmed.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly documents response shapes, resolver contracts, safety flags, and market risk nuances. Agents are equipped to handle fuzzy matches, closed markets, and wide spreads, making this an unusually complete description.

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 100% of parameters with descriptions for market, depth, and include_raw. The description adds examples of market inputs (slug, URL, question text) but these are also present in the schema, so the added value is marginal, meeting the baseline for high schema coverage.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from sibling tools like deep_research or polymarket_edges by focusing on per-bet research with a fan-out 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?

It provides explicit when-to-use guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also lists many fan-out examples by category, but it does not explicitly state when not to use it or name alternative tools for other scenarios.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive behavior. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorting by primary metric, and return of paired data plus citation URIs. This goes well beyond the annotations.

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

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

The description is dense and front-loaded with usage triggers, then explains mechanics and data sources. Every sentence adds value, though 'Replaces 8–15 sequential lookups' is somewhat redundant and the FISCAL-year example adds length. Still, overall it is well-organized and appropriately sized.

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

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

For a tool with no output schema, the description explains input scope, data sources, sorting behavior, and output (paired data + citation URIs). It does not fully specify the return structure or pagination, but it provides enough context for an agent to select and invoke the tool correctly.

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

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

The input schema already covers parameters with 100% description coverage. The tool description adds valuable meaning by explaining what each type ('company' vs 'drug') pulls and clarifying that values are tickers/CIKs or drug names, enhancing the schema's basic descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit trigger phrases and scope (companies or drugs). It distinguishes from sequential single-pack lookups, making its purpose and differentiation clear.

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 trigger phrases and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear when-to-use guidance. However, it does not explicitly name the alternative tool (e.g., entity_profile) or state when not to use this tool, so it falls short of a full 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses significant behavioral context: it is not open-web search, it returns gaps[] rather than inventing answers, citations are guaranteed fetchable, and it mentions latency expectations and paid tier requirements. This exceeds the annotation safety profile with rich operational details.

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

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

The description is long but every sentence carries information; it front-loads critical constraints (account required, fallback tool) before explaining mechanics. A few phrases are tangential, but overall the length is justified by the tool's complexity.

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

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

The description fully covers what the tool returns (findings packet with evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), how it handles large records, and expected latencies. Since there is no output schema, this narrative completeness is essential and executed well.

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

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

The schema already provides 100% coverage for both parameters, and the description adds extra meaning: it explains depth options in terms of hops and gap recovery, ties thorough to a paid plan, and gives example questions for the 'question' parameter. This enriches the schema descriptions without duplicating them verbatim.

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 concrete action: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly differentiates from open-web search and sibling tools like ask_pipeworx. It also specifies it is for broad/multi-part questions, making purpose unmistakable.

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

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

The description explicitly states when to use deep_research ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also provides an account-required fallback.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: returns top-N tools with names, descriptions, full input schemas, and curated examples, and notes results are ready to call directly without a second schema lookup. It also clarifies the 'discover' nature. While it doesn't cover pagination or error cases, it adds meaningful context beyond annotations.

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

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

The description is front-loaded with the core purpose and then provides useful detail about return format and use-case timing. The domain list is long but valuable for guiding the agent. While two sentences are efficient, the domain enumeration makes it slightly verbose, but every element 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?

The description is complete for a discovery tool: it explains what the tool returns (top-N tools with schemas and examples), how to invoke it (natural language query), when to use it first, and what domains it covers. No output schema exists, but the description fully describes the return value. The list of example queries in the schema complements this. Given the tool's simplicity and richness of annotations, nothing essential is missing.

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

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

Schema coverage is 100% (all parameters, including aliases, have descriptions). The description adds the natural-language examples and 'top-N' scalability, but substantially the schema already explains the query/limit semantics. Since coverage is high, a baseline of 3 is appropriate; the description doesn't need to compensate.

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: 'Find tools by describing the data or task.' It differentiates from siblings by positioning itself as a discovery meta-tool, with a specific verb ('find') and resource ('tools') and a list of covered domains (SEC filings, financials, FDA drugs, etc.). This makes it distinct from SIBLING tools like deep_research or search_cves.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and prioritization relative to alternatives, even though it doesn't explicitly name rejected alternatives.

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

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

The description adds significant behavioral context beyond the readOnly/idempotent annotations, including the parallel fan-out across sources, the USPTO API sunset soft-failure, the GDELT→GNews fallback chain, and the exact output structure. This gives agents a clear expectation of reliability and failure modes.

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

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

The description is dense and well-structured, opening with user intents and then detailing sources and outputs. However, the ticker/CIK constraint is mentioned twice (once in examples, once at the end), which is a minor redundancy preventing a perfect 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?

With no output schema, the description compensates by enumerating all return components and their subfields, including data source caveats (patent API sunset) and input limitations. It provides comprehensive context for a complex multi-source tool.

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

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

The input schema already describes both parameters thoroughly (type enum, value format with ticker/CIK examples, and the note about unsupported names). The description repeats this information without adding new parameter-level semantics, so it meets the baseline for 100% schema coverage.

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

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

The description clearly states the tool's purpose: generating a comprehensive cross-source profile of a US public company in a single parallel call. It includes specific query examples and distinguishes itself from siblings by positioning itself as the preferred holistic lookup tool and mentioning resolve_entity for name handling.

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 instructions are provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also directs users to use resolve_entity first if only a name is available, giving clear when-to-use and alternative guidance.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds meaningful context: memories are 'previously stored,' deletion is appropriate for stale/done/sensitive data, and the tool pairs with remember and recall. It could explicitly note irreversibility, but the destructiveHint annotation covers that, and the description's use-case framing adds value beyond the structured fields.

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 concise sentences. The first fronts the core action (delete by key), the second gives usage conditions, and the third mentions related 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?

This is a simple one-parameter, destructive, idempotent tool. The description covers purpose, when to use, and sibling context. It doesn't explain return values or error behavior, but no output schema exists and the description need not compensate for a trivial operation. The coverage is adequate and slightly enriched by pairing information.

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

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

The schema has 100% coverage for the single 'key' parameter, described as 'Memory key to delete.' The description repeats 'by key' but adds no new semantic detail beyond what the schema already provides. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from siblings remember and recall, positioning it as the deletion counterpart. It also names the key-based mechanism, making the tool's function unambiguous.

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

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

The description provides explicit when-to-use conditions: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, which helps situate it among alternatives. However, it doesn't explicitly state when not to use it or name alternative tools for non-deletion operations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context by explaining the internal process (fetches page, extracts title/description/key links, emits markdown) and the output format (single text blob). It lacks details on potential failure modes or robots.txt restrictions, but given the strong annotations, this is a solid 4.

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

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

The description is two sentences, front-loaded with the core purpose, and uses a colon-separated list of use cases. Every sentence earns its place, with no redundant information. It is concise, structured, and 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?

Despite lacking an output schema, the description explicitly explains the output ('single text blob ready to drop at site-root/llms.txt') and covers the tool's full workflow. With only 2 simple parameters covered by schema and no nested objects, the description is complete enough for an agent to select and invoke correctly without additional context.

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

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

Schema description coverage is 100% for both parameters (url and max_links), so the schema already handles parameter semantics. The description mentions 'any URL' and 'extracts title/description/key links', which adds slight context for the url parameter, but does not add meaningful behavior beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the action (generate), the resource (llms.txt), and the target (any URL), and distinguishes it from sibling tools like scan_competitor_ai_presence by focusing on the specific llms.txt generation task.

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 ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), which helps the agent decide when to use it. However, it does not explicitly state when not to use it or name alternative tools, so it scores a 4 rather than 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 read-only, idempotent, and non-destructive behavior. The description adds value by specifying what information is returned (severity, CVSS, affected products, remediation), which enriches the behavioral contract beyond the annotations.

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

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

Two concise sentences: the first states the core purpose and provides an example, the second lists return contents and gives a usage cue. No wasted words.

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

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

Given a single, well-documented parameter, a rich output schema, and comprehensive annotations, the description covers the necessary context. It explains what the tool does, what it returns, and when to use it, which is fully adequate for a tool of this simplicity.

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

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

The sole parameter cve_id is fully described in the schema, including an example. The description does not add new semantic details 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 uses a specific verb+resource ('Get full details for a specific CVE') and clearly distinguishes from search_cves by focusing on a single known CVE. It also lists the key fields returned, eliminating ambiguity.

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

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

Provides a clear usage context ('Use when you need comprehensive vulnerability analysis'). It doesn't explicitly mention alternatives or when not to use, but the context is strong enough to differentiate from sibling tools like search_cves.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds value by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that only active subscriptions are listed by default. This goes beyond annotation coverage and gives the agent a better understanding of the tool's output behavior.

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

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

The description is two sentences: the first states the core purpose and return fields, the second gives actionable usage guidance. It is front-loaded, clear, and every sentence earns its place. No redundant information or filler.

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

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

For a simple read-only list tool with one optional parameter, strong annotations, and no output schema, the description is sufficiently complete. It covers what is returned, the scope (caller's subscriptions), and when to use it. The absence of an output schema is compensated by explicitly listing return fields.

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 single parameter (include_inactive) is fully documented in the schema with a clear description and default behavior. The tool description does not add extra semantic meaning beyond the schema, so the baseline score of 3 is appropriate. The schema does the heavy lifting here.

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

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

The description uses a specific verb+resource construction: 'List the caller's active subscriptions.' It clearly identifies the scope (caller's own subscriptions) and differentiates from sibling tools like subscribe/unsubscribe by focusing on listing active subscriptions. The mention of returning specific fields further clarifies its purpose.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use this tool (reviewing existing subscriptions before modifying) without explicitly stating exclusions or naming alternatives, but the context is strong enough to guide selection.

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

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

With no useful annotations (all false), the description carries the full behavioral burden. It discloses rate limits ('5 per identifier per day'), the claim_token flow for anonymous submissions, that it's free and doesn't count against quota, and how the team processes feedback. This goes well beyond what annotations provide.

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

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

The description is longer than average but every sentence adds crucial context—purpose, usage, exclusions, claim_token mechanics, and rate limits. It is front-loaded with the primary purpose and follows a logical flow, though it could be slightly more scannable with bullet points. Still, it 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?

Despite having 4 parameters, nested objects, and no output schema, the description covers all critical aspects: what it does, when to use it, when not to, how to use parameters (especially claim_token), behavioral limits, and even hints at the return value. The agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra value by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by clarifying how to describe issues in terms of Pipeworx tools/packs, which enriches the message and context parameters beyond their 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the action (send feedback), the target (Pipeworx team), and the scope (only for Pipeworx connection tools), distinguishing it from sibling research/query 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 when-to-use guidance with concrete categories (bug, feature/data_gap, praise) and a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and not for other MCP servers. It also gives instructions on how to frame feedback and how to use claim_token for follow-ups.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds valuable behavioral context: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window,' informing users about data freshness and privacy. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose, followed by structured bullet points for use cases and a final sentence for caching/PII. Each sentence contributes value, but the length could be trimmed without losing key information, so not a 5.

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

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

With no output schema, the description sufficiently explains return values ('top tools, top packs, and total call volume') and also gives additional context like data source, no PII, and caching behavior. For a single-parameter, read-only tool, this is complete.

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

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

The only parameter 'window' is fully described in the schema (enum, default, effect). The description repeats the window options and semantics ('Shorter windows surface what's hot right now') but adds no net new meaning, so baseline 3 applies.

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

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

The description opens with a clear, specific verb and resource: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume.' It distinguishes itself from siblings like 'discover_tools' by focusing on real-time aggregated call activity rather than general discovery.

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

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

The description provides explicit use cases ('Useful for: (1) discovering what data sources are hot... (2) confirming a popular tool is the canonical choice... (3) seeing whether your use case aligns...'). It lacks explicit when-not-to-use or named alternatives, 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?

Discloses numerous behavioral details beyond the readOnly/openWorld/idempotent annotations: the Jaccard similarity threshold for cross-event pairing, placeholder-filter logic (dropping >20% returns null), and the fill-check process that prices against live CLOB depth. Even explains what 'realizable_edge_pp ≤ 0' means and advises not to trade.

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

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

The description is lengthy but well-organized with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the core purpose and then expands on modes and edge cases. While not strictly concise, the dense detail is necessary for a complex tool and every section provides value.

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

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

The description is remarkably complete given the tool's complexity and absence of an output schema. It specifies all response fields (opportunities[], partition_check, skipped_low_similarity, fill-check outputs), covers all modes including the no-arg trending_scan, and explains edge cases like placeholder filtering and the null signal when >20% placeholders.

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 adds substantial semantic meaning: explains what happens with event (walks child markets, partition_check) and topic (searches related events, flattens markets), provides example values, and notes that full Polymarket URLs are accepted for event. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies multiple modes (trending_scan, event, topic) with concrete examples, and differentiates from sibling tools by detailing the specific methodology and fill-check integration.

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

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

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also points to an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk') and cautions against trading when fill check shows no realizable edge.

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 already declaring reads-only/idempotent/non-destructive, the description adds substantial behavioral detail: cached 1h at KV level keyed on knobs, slippage assumptions, 24h-move warnings, placeholder-slug filtering, and diagnostics intended to explain empty segments. This is context beyond what annotations provide and does not contradict 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 a single, extremely dense paragraph with no line breaks or bullets; it buries important operational details between model internals and historical threshold references ('Run 8 from prior 85%/5%/50:1') that agents won't find useful. While it uses uppercase section labels for skimmability, the sheer length and repetition of response keys (already in schema/summary) make it verbose.

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

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

There is no output schema, so the description carries full responsibility for explaining return values. It enumerates per-opportunity fields (edge_pp_net, kelly fractions, liquidity, spread, volume, 24h warning) and top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics), leaving very little unspecified for a complex, three-segment 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?

With 100% schema description coverage, the baseline is 3, but the tool description adds exceptional operational nuance: slippage guidance ('Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade'), concrete thresholds (e.g., 'Set to 5000...'), and a critical caveat that partition arbs always return kelly_fraction_half=0 at parent level, which is essential to interpreting min_kelly/min_partition_leg_kelly correctly.

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

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

Description opens with a specific verb phrase: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' with a clear user goal ('what should I bet on today'). It further distinguishes from siblings by naming three output segments (model-driven, structural arbitrage, concentrated longshot) and explicitly stating this avoids paging hundreds of markets.

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

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

Provides clear context for when to use the tool ('discover opportunities without paging hundreds of markets') and excludes Fed bets from ranking due to unreliable signal. However, it never names sibling tools (e.g., polymarket_arbitrage, polymarket_fill_risk) or explicitly states when to prefer them over 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?

Beyond the read-only/idempotent annotations, the description discloses data generation (snapshots written on cache-miss), data gaps, history depth bounds, and the computation basis for decay (daily closes, net of default slippage). This is rich behavioral context that helps the agent interpret results correctly.

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 section earns its place: purpose, arguments, response structure, and limits. It is logically organized with clear labels (Args, RESPONSE, LIMITS), making it easy for an agent to parse the essential information without fluff.

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

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

With no output schema, the description fully documents the response format (tracked[], expired[], snapshot_dates[]) and their fields. It also explains expiration reasons, lifespan median, and data caveats, making the tool's behavior completely understandable in context.

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

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

Schema coverage is 100%, and the description mostly restates the schema (defaults and allowed values). It adds the phrase 'snapshot family' for window, which provides modest context, but does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry built from daily polymarket_edges snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings by focusing on time-series tracking rather than edge calculation or arbitrage.

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

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

The description implies when to use the tool by contrasting fresh vs. 3-week-old edges, and notes limitations (60-day TTL, daily closes not intraday, snapshot gaps). It does not explicitly name alternative tools, but the context makes the use case clear.

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

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

Beyond the readOnly/idempotent annotations, the description discloses simulation behavior: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), interprets size_usd differently for buys vs sells, and warns about forced_directional_risk and partial-fill hazards. This is substantial added context about what the tool computes and its limitations.

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

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

The description is long and dense, but well-structured with mode keywords and return-field lists. Every sentence contributes necessary operational details; however, it could be tightened without losing meaning. The front-loaded purpose and inline guidance earn a high score, but the verbosity prevents a 5.

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

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

For a tool with 4 parameters, no output schema, and two complex modes, this description is exceptionally complete. It covers parameter interpretation, return values, mode-specific behavior, risk warnings, and integration with sibling tools. The absence of an output schema is compensated by enumerating all return fields.

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 still adds significant meaning: it explains the mutual exclusivity of market and event, auto default for basket side based on partition sum, settlement notional semantics for size_usd in basket mode, and the clamp range 10–1,000,000. This goes well beyond the schema field descriptions.

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

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

The description opens with a clear, specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes two modes (single-market and basket) and ties itself to sibling tools like polymarket_arbitrage and polymarket_edges, making its unique role unmistakable.

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

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

It states exactly when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why—because theoretical overround on thin books is not capturable and partial fills create unhedged directional risk—which clearly communicates usage context versus alternatives.

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

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

The description goes far beyond the annotations by disclosing response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning with specific conditions, temporal_alignment, skipped_cross_type/subtype), and the caveat that most pre-mapped topics aren't tradeable. This is highly transparent and consistent with the readOnlyHint.

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

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

Although lengthy, the description is well-structured and front-loaded with purpose, then modes, response fields, safety, and caveats. Every sentence contributes valuable information with no filler, making the length appropriate for the tool's complexity.

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

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

With no output schema, the description must and does explain the response format in detail, including matched spread, compatibility_warning, temporal_alignment, and skipped counters. It also covers limitations and edge cases, making it self-contained for an agent to use effectively.

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

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

Schema coverage is 100%, so parameters are documented, but the description adds meaning by explaining how they interact: explicit kalshi_event_ticker and polymarket_event_slug override topic-mapped sides, and the topic shortcuts are contextualized. This goes beyond the schema's basic 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 clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with a specific purpose and scope. It implicitly distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison, though it doesn't name them explicitly.

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 two explicit usage modes (topic shortcuts vs explicit ticker/slug) and explains when each is appropriate, including override behavior. It also warns that most pre-mapped topics return compatibility_warning and that pre-mapped does not equal tradeable. However, it does not explicitly name alternative tools for when this tool should not be used.

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, idempotent, and non-destructive behavior. The description adds that lookups are scoped to an identifier (anonymous IP, BYO key hash, account ID) and that omitting 'key' lists all saved keys, which are useful behavioral details 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?

Three clear sentences that front-load the action, then provide usage context, scoping, and tool relationships. Every sentence earns its place with no wasted words.

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

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

For a single-optional-parameter retrieval tool with no output schema, the description covers purpose, usage context, scoping, and relationship to sibling tools. It is sufficient for an agent to select and invoke it appropriately.

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

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

The schema describes the 'key' parameter with 100% coverage, including the omission behavior. The description reinforces this with examples but does not add significant new parameter semantics beyond what the schema already provides.

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

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

The description explicitly states the tool retrieves saved values or lists keys, naming the companion tools (remember, forget) and distinguishing it from them. It uses the specific verb 'Retrieve' and provides concrete examples of stored context types like ticker, address, and research notes.

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

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

It gives clear use cases ('look up context the agent stored earlier') with examples (ticker, address, research notes) and references complementary tools (remember, forget). It does not explicitly state when not to use this tool, but the context strongly implies it is for previously saved information.

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 directly contradicts the annotation readOnlyHint: true. It states that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones,' which is a state-changing operation. Despite the description being transparent about this side effect, the annotation falsely claims the tool is read-only. This is a serious inconsistency that could mislead an agent relying on 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 compact, consisting of three sentences that efficiently cover the core action, return fields, filtering, and the mark_read side effect. It front-loads the main purpose and avoids irrelevant details. The structure is logical, though slightly dense; a bullet list could improve scannability, but it remains concise and readable.

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

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

For a tool with no output schema and multiple optional parameters, the description is quite complete: it explains return fields (source, citation_uri, raw payload), provides usage patterns, and mentions an alternative access method. It doesn't cover error cases or explicitly state default behavior for mark_read false, but given the annotations (except the contradiction) and simple nature, it's nearly sufficient. The contradiction with readOnlyHint partially undermines completeness, but the description itself is informative.

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

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

Although the schema already documents all five parameters with descriptions, the tool description adds valuable semantics beyond the schema: it explains the effect of mark_read on future calls ('next call only shows newer ones'), provides an example value for type ('sec_8k'), and clarifies the 'since' parameter as an ISO timestamp. This enriches the param information beyond the bare 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: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the action (pull/retrieve), and distinguishes itself from sibling tools like recent_changes and recent_cves by focusing on alerts/events. The mention of 'fired events' and 'alerts' makes the tool's 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?

The description provides practical usage context: it mentions polling is fine, explains filtering by type and since, and suggests an alternative access method for scripts/dashboards via a URL. While it doesn't explicitly say when not to use it or compare with specific sibling tools, it gives enough context for the agent to decide when this tool is appropriate, especially with the note about an alternative HTTP endpoint.

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

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

The description adds substantial behavioral context beyond the annotations: it details the multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), the fallback logic (GDELT preferred, GNews on rate-limit/5xx), the PatentsView API sunset soft-fail, and the output structure (changes[], total_changes, pipeworx:// URIs). This enriches the read-only and idempotent nature already declared by annotations.

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

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

The description is information-dense and well-structured, with each sentence contributing useful detail. The opening examples are somewhat redundant (six paraphrases of the same query intent), which could be trimmed, but the rest is efficient and front-loaded with the core purpose.

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

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

Despite having no output schema, the description fully explains the return format and source behavior, including fallback and failure modes. It covers the tool's complexity adequately, enabling an agent to understand what to expect and when to use 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?

Schema description coverage is 100%—each parameter already has a detailed description. The tool description repeats the `since` format (ISO date or relative shorthand) and provides examples, but adds no new parameter-level meaning beyond the schema. The baseline of 3 applies.

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

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

The description clearly identifies the tool as a change feed for a company within a time window, supporting queries like "What's new with X" and "updates on Acme." It explicitly distinguishes itself from entity_profile, which is the static profile tool, making the purpose unambiguous and well-differentiated from 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 provides explicit when-to-use guidance through example queries and directly states the alternative: "Use entity_profile instead when you want the static profile... regardless of window." This gives clear direction for tool selection without ambiguity.

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 that it returns CVE IDs, descriptions, and severity, and scopes results to a publication date range. This adds useful behavioral context beyond the annotations without contradiction.

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

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

The description is brief and front-loaded with the primary action ('Get CVEs published within a date range'). Every sentence serves a purpose: scope, return contents, and intended use. No wasted words.

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

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

For a simple list tool with a fully documented schema, annotations, and an output schema, the description covers purpose, scope, return fields, and use case. It could mention default/max limit behavior, but that is already in the schema, so the description is sufficiently 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%; each parameter (start, end, limit) has a description. The tool description reinforces the ISO 8601 format but does not add meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Get CVEs published within a date range,' using a specific verb and resource with a clear scope (date range). It distinguishes itself from sibling tools like get_cve (single CVE) and search_cves (keyword search) by emphasizing the temporal filter.

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 context: 'Use to track newly disclosed vulnerabilities.' It does not explicitly mention alternatives or when not to use it, but the date-range scoping plus the stated use case gives clear 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 indicate idempotentHint=true, destructiveHint=false, and readOnlyHint=false, which covers basic safety. The description adds meaningful behavioral context beyond those flags: persistence across sessions, 24-hour retention for anonymous sessions, and scoping by identifier. It does not contradict the annotations, though it could have explicitly stated overwrite behavior for existing keys; however idempotentHint implies a safe, repeatable write.

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

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

The description is three sentences with no filler. It front-loads the action ('Save data...'), then provides when-to-use, storage model, and related tools. Every sentence carries useful information, and the use-case examples are concise but illustrative.

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 write tool with full schema coverage and no output schema required, the description is complete. It covers what the tool does, when to use it, how storage works (key-value, identifier-scoped), persistence details, and companion tools. There are no significant gaps for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics by framing the pair as 'scoped by your identifier' and giving example use cases (ticker, address, preference) that map to the key/value purpose. The schema already provides key and value descriptions and examples, so the description reinforces rather than significantly expands parameter meaning, but the scoping detail is a genuine enhancement.

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 'Save data the agent will need to reuse later — across this conversation or across sessions,' which is a specific verb-plus-resource statement that clearly defines the tool's scope and purpose. It also distinguishes this tool from its siblings by explicitly pairing it with recall and forget, making it evident that remember is for storing, not retrieving or deleting.

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

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

The description provides explicit guidance: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject) so you don't have to look it up again.' It gives concrete trigger examples and explains the benefit. It also refers to complementary tools ('Pair with recall to retrieve later, forget to delete'), helping the agent choose the right tool.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, lowering the burden. The description adds valuable behavioral context: it cascades through multiple lookup endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, labels every identifier with its source, and explicitly states unresolved identifiers rather than omitting them. This goes well beyond the annotations.

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

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

The description is lengthy but information-dense, with the opening trigger phrases, type breakdowns, and fallback notes all earning their place. It is front-loaded with the core purpose and usage directive. The only slight downside is the long list of example phrasings and the somewhat repetitive 'accepts' wording, but overall it is well structured for a complex tool.

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

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

Despite lacking an output schema, the description fully explains what the tool returns: identifier types for companies (CIK, ticker, company_name, LEI, FIGI) and drugs (RxCUI, ingredient, brand), source labelling, and explicit handling of unresolved identifiers. It also covers graceful degradation and the fact that one call replaces multiple manual lookups, making the tool self-contained enough for an agent to select and use it confidently.

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

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

The input schema has 100% description coverage: both `type` and `value` are fully described with examples. The tool description repeats some of this parameter information but adds no new semantic detail about the parameters themselves (e.g., no additional constraints or format nuances). Per the rubric, a baseline of 3 is appropriate when schema coverage is high and description doesn't compensate further.

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

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

The description uses a specific verb+resource ('resolve a user-spoken NAME to the canonical/official identifiers') and clearly distinguishes the tool from siblings by stating it provides identifiers other tools require as input. It also enumerates supported entity types and the specific identifiers returned (CIK, LEI, FIGI, RxCUI), making its purpose unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is direct usage guidance. It also explains which input formats are accepted for each type, but it does not explicitly discuss when not to use this tool or what alternatives (like entity_profile or compare_entities) would be better, so it stops short of full when/when-not coverage.

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

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

Even with annotations declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds meaningful behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. This goes beyond the annotation's safety profile and explains the internal operation.

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

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

The description is two sentences, front-loaded with the primary action, then provides a use-case quote, and ends with the return format. Every sentence carries meaning and there is zero filler; it is tightly structured and easy to scan.

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

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

Despite having no output schema, the description fully discloses return fields (score, confidence, signal density) and gives a concrete use case. For a 4-parameter tool with comprehensive schema coverage, this description is complete; any missing details like model options are already explicit in the input schema.

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

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

Schema description coverage is 100% and already documents all four parameters, including that the first entity is treated as the 'subject' and rest as competitors. The description adds no new parameter-specific semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb-resource pairing: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling ai_visibility_check, which checks a single entity, by emphasizing the comparative ranking and output. The mention of ranking and surfacing most/least recognized makes the tool's unique function 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 a concrete use case ('competitive AI-marketing audits') and an illustrative example ('does Claude know about us as well as our competitors?'). It implies when to use this tool over ai_visibility_check (the latter is the underlying single-entity probe), but it does not explicitly state 'use ai_visibility_check for a single entity' or list exclusions.

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

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

Annotations already mark readOnly/idempotent, so the bar is lower; the description adds valuable operational details: composite fan-out, 5-30s first bundlephobia latency, graceful partial failure via sources_failed. No contradiction.

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

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

Although lengthy, the description front-loads the core purpose and flows logically through usage, return payload, ecosystem scope, and failure mode. No filler—every sentence adds operational value.

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

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

For a composite tool with no output schema, it enumerates the summary block fields, mentions per-advisory details, links, and alternative versions. It also covers limitations and performance behavior, making it complete for an agent to decide 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?

Both parameters are fully described in the schema (100% coverage), and the description simply repeats schema notes about scoped packages and version defaults without adding further semantics. 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 clearly states the tool is a composite npm package risk/size check in one call, naming both datasources (deps.dev and bundlephobia) and the exact question it answers. This distinguishes it from sibling research tools by specific scope.

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

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

Explicitly gives use cases ('is X safe / popular / small') and a concrete example ('what does adding lodash cost me'). Also excludes non-npm ecosystems and points to deps.dev:version as the alternative, providing clear when-to-use vs when-not-to.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses key behavioral subtleties: search terms match against CVE description text, every word must appear (AND logic), and question words are stripped automatically. This gives the agent essential insight into how queries are processed, which is not evident from the annotations or schema.

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

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

The description is a single, focused paragraph with three sentences. It front-loads the purpose, then gives critical usage details, then a clear use-case. Every sentence earns its place with no redundancy or bloat, making it both 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 rich schema, annotations, and output schema, the description fully covers the tool's purpose, query behavior, parameter semantics, and usage context. It lacks only explicit sibling-tool differentiation, but that is not essential for completeness when the purpose and behavior are so clearly stated. Overall, it provides all necessary information for an agent to select and invoke 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 already covers 100% of parameters with descriptions, so the baseline is 3. The description adds significant extra meaning for the 'query' parameter by explaining the matching semantics (every word must appear, plain-English questions stripped), which directly impacts how the agent constructs queries. The 'limit' parameter is not mentioned in the description, but the schema fully documents 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 'Search NVD for CVE vulnerabilities by product or component name' with a specific verb and resource. It distinguishes from sibling tools like get_cve (which likely retrieves a single CVE) and recent_cves (which lists recent vulnerabilities). It also specifies return fields, making the tool's 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 when-to-use guidance: 'Use when researching security threats or checking if a known vulnerability affects your systems.' It also warns against plain-English questions and explains the AND-matching behavior, which is valuable usage context. However, it does not explicitly name alternative tools or state when not to use this tool vs. get_cve or recent_cves.

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

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

Beyond the readOnly/idempotent annotations, the description reveals concrete behavioral traits: the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlap), a 200K char cap with truncation behavior, and a 'flagged' indication when truncation happens. It also clarifies that every passage carries an offset for verification—valuable context the agent needs to trust the results.

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

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

The description is two sentences, front-loaded with the core purpose and followed by usage context and technical details. Every clause earns its place—there's no fluff or repetition. The dense technical detail is relevant and clearly separated from the main usage guidance.

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

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

With no output schema, the description adequately explains the return format (passages with character offsets and similarity scores). It also covers the input cap, truncation, and pairing with other tools, giving a complete picture of how the tool behaves. For a moderately complex search tool with 3 parameters, this is sufficient.

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

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

The schema already covers all three parameters with descriptions and examples, so the bar for added value is high. The description adds the notion of 'text you already pulled' and mentions 'top-N' passages, but these are slight elaborations rather than essential new semantics. It doesn't provide any additional constraints or clarifications beyond the schema's own text.

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

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

The description opens with 'Semantic search INSIDE a fetched record', immediately stating the verb, resource, and scope. It goes on to specify inputs (text + natural-language query) and outputs (top-N passages with offsets and similarity scores), making the purpose unambiguous and setting it apart from broad search tools like 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?

Explicitly states 'Use when the record is too big to cram into the prompt' and directly references the companion tool 'ask_pipeworx_grounded' to clarify the intended workflow. This provides both a clear when-to-use condition and an alternative, which is exactly what the dimension asks for.

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

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

The description discloses significant behavioral constraints beyond annotations: it requires an OAuth account, mentions phone verification and a 10/day SMS cap, specifies that the feed is always on, and describes the delivery channels. It does not contradict the annotations (readOnlyHint=false is consistent with 'Create'). It adds valuable context about side effects and prerequisites.

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 each sentence serves a purpose: it lists supported types with examples, delivery channels with constraints, and authentication requirements. The structure is logical, though it is a single long paragraph without bullet points, which slightly reduces skimmability.

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 creation, return value, authentication prerequisites, supported types, and delivery channels. It does not fully explain response fields other than the id (e.g., webhook secret is only in the schema), but given the rich schema, the description is reasonably complete. It could mention how to unsubscribe or list subscriptions, but that is not its responsibility.

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

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

The schema already provides 100% coverage with parameter descriptions. The tool description adds concrete examples (e.g., 'items:["5.02"] = officer change') and clarifies type-specific behavior, which enriches the bare schema definitions. It effectively helps the agent construct valid parameters.

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

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

The description clearly states the action: 'Create a proactive monitoring subscription to a live-data event stream' and the resource: 'a live-data event stream'. It also mentions the return value ('Returns the new subscription id'), and the text distinguishes the tool from siblings like unsubscribe and list_subscriptions by focusing on creation.

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

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

The description provides context for when to use the tool (creating a subscription) and includes prerequisites (requires Pipeworx OAuth account; anonymous + BYO cannot persist). It also explains how to retrieve alerts from the feed. However, it does not explicitly mention alternatives or exclusionary conditions, but the context is clear enough.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive behavior, and the description adds concrete behavioral context: it returns category-bucketed examples, includes exact tool+argument shape, and supports optional topic narrowing. There is no annotation contradiction, and the extra detail about output structure and parameter effect is valuable beyond the safety hints.

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

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

The description is dense and front-loaded with user-question examples, then explains output, parameters, and usage in one flowing paragraph. Every clause serves a purpose, though it is somewhat long and could be tightened, so it earns a 4 rather than a 5.

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

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

For a simple tool with one optional parameter and no output schema, the description covers what it returns, how to invoke it, and when to use it, even naming the meta-tools users can learn next. It fully addresses the onboarding use case with no missing operational detail.

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

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

The schema already documents the single optional `topic` parameter with valid values and the omit-for-cross-category behavior, providing 100% coverage. The description adds only mild reinforcement with examples like 'finance', 'pharma', 'betting' and the phrase 'to focus', which does not significantly go 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 is the onboarding entry point for discovering what Pipeworx can do, listing natural-language trigger phrases and specifying that it returns category-bucketed example questions with exact tool and argument shapes. This distinguishes it from general ask/entity tools by positioning it as the first-stop discovery 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?

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', which is clear when-to-use guidance. However, it doesn't name alternative discovery tools like discover_tools or state explicit when-not-to-use conditions, so it stops short of full alternative/exclusion coverage.

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

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

The description discloses critical behaviors beyond the annotations: ownership enforcement ('you can only cancel your own subscriptions') and soft-delete semantics ('The row is deactivated (not deleted)... historical events stay available'). These add substantial context not present in the structured 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 two sentences, front-loads the action, and every clause adds relevant information: ownership, deactivation, and historical retention. No filler or redundancy.

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

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

For a simple tool with one parameter, no output schema, and informative annotations, the description covers all essential aspects: the operation, the ownership prerequisite, the non-destructive nature, and the impact on historical data. Nothing critical is missing.

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

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

The schema already fully documents the single 'id' parameter with a clear description ('Subscription id (uuid) returned by subscribe'). The tool description adds no new meaning beyond saying 'by id', so with 100% schema coverage, baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes this from sibling tools like subscribe and list_subscriptions by stating the cancellation action and the soft-delete behavior.

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

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

The description provides clear context by noting ownership enforcement and the deactivation behavior, which helps the agent understand when cancellation is appropriate. It doesn't explicitly mention alternatives, but the context is sufficient given the simple scope.

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

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

Annotations already provide readOnly, openWorld, and idempotent hints; the description adds crucial behavioral nuance: the distinction between could_not_verify (verification failed, no evidence either way) and unsupported (no source covers it), and the presence of verification_error{stage,detail}. It also explains the two execution paths (SEC EDGAR+XBRL fast path vs grounded pipeline) and that evidence is cited with pipeworx://. 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 all content is functional: query examples, usage directive, path differentiation, return value summary, error semantics, and efficiency claim. It is front-loaded with examples and organized topically. 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?

For a tool with 2 parameters, full schema coverage, and no output schema, the description covers the essential behavioral contract: what it returns, how it routes, and the meaning of critical edge-case verdicts. It is sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema already covers both parameters with detailed descriptions (claim example, tolerance_pct override and default cap). The description adds no further parameter-level detail beyond referencing 'exact percent-delta math,' which is already implied. With 100% schema coverage, the baseline is 3.

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

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

The description opens with concrete query examples ("Is it true that…", "fact check") and states it performs natural-language claim verification against authoritative sources. It clearly distinguishes from sibling tools like ask_pipeworx_grounded by focusing on claim validation with two routing paths and specific verdicts. The verb 'validate' plus resource 'claim' is specific, and the scope is unambiguous.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear when-to-use. It also distinguishes between company-financial claims and other factual claims, indicating the tool handles both via different pipelines. It notes this tool replaces 4–6 sequential calls, implying it is the consolidated alternative, but does not name sibling tools or give explicit when-not to use.

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