Osv Dev

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

Annotations already mark readOnly/idempotent, but description adds external API behavior: default Workers AI is free, and passing _apiKey also probes Anthropic with direct billing to the user ('you pay Anthropic directly'). No contradiction with annotations. This is valuable behavioral context beyond 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?

Three sentences: main action, default/key details, use cases. No filler; front-loaded with the core purpose. Each sentence adds distinct 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?

Description conveys output shape (per-model {score, confidence, signals, raw_response} + combined view) even without an output schema, covers model selection and cost implications, and states typical use cases. Sufficient for a 4-param tool with rich annotations.

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

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

Schema covers 100% of parameters, so baseline is 3. Description adds meaning beyond schema: names 'workers-ai' as free default, clarifies _apiKey is for Anthropic and passed straight through, and describes the returned per-model fields. This elevates it to 4.

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

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

Clearly states 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model' – a specific verb, resource, and output. Distinguishes from siblings like ask_pipeworx and scan_competitor_ai_presence by focusing on visibility scoring rather than Q&A or generic scanning. Use cases (AI-marketing audits, pre-launch checks) further clarify intent.

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

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

Provides explicit use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' Does not name alternative tools or state when not to use, but the context makes the intended scenario clear. Score 4 for clear context without exclusions.

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

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

Annotations already declare readOnly/openWorld/idempotent. The description adds rich behavioral context: routing across 5,529 tools, filling arguments, returning structured answers with citation URIs, working on every tier, and being a fast single call. No contradictions with annotations.

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

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

The description is long but every sentence earns its place: purpose, scope, examples, sibling comparisons, and step-up guidance. It is front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH') and avoids 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?

Despite no output schema, the description explains the return format (structured answer with pipeworx:// citation URIs), covers use cases, alternatives, and limitations, and notes it works on every tier as the default entry point. This is complete for a single-question routing tool.

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

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

Schema coverage is 100% (all parameters described as aliases of 'question'), so baseline is 3. The description elevates by providing concrete example queries and instructing natural-language phrasing ('what is', 'look up', etc.), which gives practical guidance for parameter value selection beyond the schema.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and clearly states it 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It distinguishes from siblings by explicitly naming ask_pipeworx_grounded and deep_research.

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

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

It provides explicit when-to-use guidance: 'Use whenever the user asks "what is", "look up", "find"...' and 'START HERE for most questions'. It also gives step-up alternatives: 'for a hallucination-resistant single answer ... use ask_pipeworx_grounded; for a broad/multi-part question ... use deep_research.'

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses that candidate routing improvements may be live, that no candidate is currently active (matching ask_pipeworx exactly), and that it does not fall back to a limited mode. This adds valuable context about its experimental nature and current behavior. There is no contradiction with annotations.

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

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

The description is about 100 words and front-loads the essential beta/universal router identification. Each sentence contributes useful information, though there is some redundancy in listing the identical aspects ('same 5,529 tools, same arguments, same response shape'). It is efficiently structured for the information conveyed.

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

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

Given the lack of an output schema, the description helps by pointing to 'same response shape' as ask_pipeworx, and it covers the current experimental status. It provides sufficient context for an agent to decide whether to use this beta variant versus the stable router. No major gaps remain, but a bit more detail on response format could push it higher.

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

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

Schema coverage is 100% with all six parameters documented as 'question' or its aliases. The description only says 'same arguments' without adding semantic detail beyond what the schema already provides. Therefore it meets the baseline of 3 but does not exceed it.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from siblings by being the experimental edge while confirming it is a full working router. This provides a specific verb+resource and clear differentiation.

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

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

The description explicitly instructs to use it 'exactly like ask_pipeworx when you want the newest routing' and notes that results are compared to the stable router to decide merges. This gives a clear when-to-use context and implies the alternative (ask_pipeworx) for stable needs. Although it doesn't list explicit exclusions, the guidance is strong.

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

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

The description thoroughly discloses behavior beyond annotations: it returns evidence, confidence, and refusal reasons; it explicitly refuses when data doesn't directly answer, and lists refusal types. It also notes the additional LLM call cost. The readOnly/openWorld/idempotent annotations are consistent with the described behavior, no contradictions.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, return format, use cases, and cost tradeoff. It's front-loaded with the key phrase 'Hallucination-resistant answer mode' and flows logically from behavior to 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?

For a question-answering tool with a simple one-parameter schema and no output schema, the description fully compensates by detailing the exact return shape, refusal reasons, and use-case restrictions. It provides everything an agent needs to invoke and interpret results correctly.

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

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

Schema coverage is 100%, with all aliases already documented in the schema. The description adds minimal parameter-specific meaning—only mentioning that the tool 'fills arguments' internally, which is about tool routing rather than this tool's own parameters. 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+resource: 'Hallucination-resistant answer mode' and clearly distinguishes from the sibling ask_pipeworx by explaining the same routing but evidence-only extraction. It defines what the tool does and how it differs, leaving no ambiguity.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on' and provides a clear alternative: 'prefer ask_pipeworx for casual lookups.' Also notes the cost tradeoff of an extra LLM call, giving concrete selection criteria.

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

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

Beyond the basic readOnly/idempotent annotations, the description extensively discloses behavioral traits: short-circuit statuses like 'low_confidence_match', closed-market handling, wide-spread tradeability flags, GDELT fallback fields, and cancellation-rule risks. This gives agents crucial safety information not available from 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 long and dense, but it is well-structured with clear section labels (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY) and concrete examples. Every section provides necessary operational detail, though the sheer length and heavy use of uppercase labels make it slightly less concise than ideal.

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 provides a remarkably complete picture: input formats, fan-out logic, response shapes, resolver confidence semantics, safety statuses, and cancellation-rule risks. An agent can safely invoke and correctly interpret the result without needing additional documentation.

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 all three parameters with detailed descriptions (market formats, depth options, include_raw behavior). The tool description repeats these and adds contextual behavior examples, but does not add unique parameter-level semantics beyond what the schema provides. With 100% 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+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further clarifies the accepted input formats (slug, URL, question text) and explicitly states the tool's use cases ('should I bet on X', 'what does the data say about Y'), distinguishing it from sibling tools focused on arbitrage or edge tracking.

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

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

The description gives clear context on when to use the tool ('Use for...') and includes concrete classification and fan-out examples. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of a full when/when-not/alternatives guideline.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and the return of paired data with citation URIs. 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 well-organized, leading with trigger examples and usage guidance before diving into per-type details. It is a bit lengthy, but every sentence contributes new information, so it earns a high score.

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

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

With no output schema, the description compensates by explaining the return format (paired data + citation URIs), sorting behavior, and the data pulled per entity type. It also quantifies the efficiency gain over sequential lookups, making the tool's place in the broader workflow clear.

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

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

Although schema coverage is 100%, the description goes beyond by explaining exactly what data each type pulls: companies get revenue, net income, cash, and long-term debt; drugs get FAERS adverse-event counts, FDA approvals, and trial counts. It also provides concrete examples for the values array.

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 ('compare') with a clear resource (companies or drugs) and provides explicit trigger phrases like 'X vs Y' and 'rank these companies'. It also differentiates from sequential single-pack lookups, distinguishing itself from sibling tools such as entity_profile.

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

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

It explicitly states when to use the tool ('Compare X and Y', 'which is bigger', 'rank these companies') and instructs to ALWAYS PREFER it over sequential single-pack lookups when comparing entities. It also provides guidance on choosing company vs drug type.

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 decomposition/parallel routing, the findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[] behavior ('never invented'), hop fields, resolvable citation_uri, semantic excerpting, and latency. It also notes a failure mode for current-news topics (mostly empty gaps). This enriches the readOnly/openWorld hints without contradicting them.

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

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

Very information-dense and somewhat long, but each clause earns its place—auth gate, core mechanism, sample use, alternative routing, citation invariants, and performance expectations. It is front-loaded with the account requirement, though a leaner version could trim some parenthetical detail. Still, for this tool's complexity the length is justified.

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

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

Given no output schema, the description must carry the full burden of explaining the return contract—and it does: findings packet contents, gaps[], contradictions[], hop fields, citation_uri resolvability, and timing. It covers prerequisites (account, paid thorough), sibling differentiation, and failure modes. There is little an agent would be missing for 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?

Both parameters are already fully described in the schema (100% coverage), but the description adds behavioral meaning: depth:'quick/standard/thorough' are tied to facet counts, gap-recovery hops, contradictions[], and a paid tier for 'thorough'. It also clarifies that the question parameter favors broad/multi-part phrasing because decomposition is the point.

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?

States a clear verb+resource: 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly differentiates from siblings by noting 'this is NOT open-web search' and naming ask_pipeworx as the single-lookup alternative. The description also provides examples of intended broad/multi-part 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?

Explicitly spells out when to use vs alternatives: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also adds an account-tier exclusion: if not signed in, use ask_pipeworx instead.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds valuable behavioral context by explaining the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the structured annotations without contradicting them.

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

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

The description is three sentences with a clear front-loaded purpose. The first sentence states the function, the second details usage context and domains, and the third explains the return value and when to call it. Every sentence earns its place, and the domain list, while long, is highly informative.

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

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

For a simple discovery tool with only one required parameter and strong annotations, the description is complete. It explains the return value (top-N, schemas, examples) and the exact use case, so no output schema is needed. The tool's low complexity and full schema coverage mean there are no significant gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'describing the data or task' aligns with the required 'query' parameter but adds little beyond what the schema already details (aliases, limit default/max). The schema carries the full burden for parameter semantics, and the description does not 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 'Find tools by describing the data or task' with a specific verb and resource, and distinguishes itself from siblings by being the meta-tool for discovering other tools. It enumerates many domains (SEC filings, FDA drugs, etc.), making its 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?

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and provides a strong directive: 'Call this FIRST when you have many tools available.' This gives clear context and implies when other tools (for direct answers) would be more appropriate.

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

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

Annotations already declare readOnly and non-destructive, and the description adds rich behavioral context: data source fan-out (SEC EDGAR, XBRL, USPTO, GDELT/GNews, GLEIF), soft-fail on PatentsView sunset, GDELT→GNews fallback, and exact return fields. This fully discloses expected behavior 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 long but information-dense, front-loaded with trigger phrases and ending with critical input constraints. Slightly verbose due to the exhaustive return-field list, but every sentence contributes necessary guidance.

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

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

With no output schema, the description compensates by enumerating the full return structure (CIK, filings, fundamentals, patents, news, LEI) and fallback behavior. It also covers input constraints and edge cases (patents API sunset), making it complete enough for an agent to select and invoke correctly.

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

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

Schema covers 100% of parameters with clear descriptions, and the description adds practical examples ('AAPL', zero-padded CIK) and reinforces the name-not-supported constraint with a pointer to resolve_entity. This adds meaningful usage detail 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?

Description states a specific verb and resource: 'full cross-source profile of a US public company'. It distinguishes from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and explicitly contrasts with resolve_entity for name inputs.

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

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

Explicitly states when to use ('when the user asks for a holistic view') and when not to use (names not supported; use resolve_entity). Also gives clear preference over chaining alternatives.

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

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

Annotations already declare destructiveHint and idempotentHint, so the description doesn't need to restate those. It adds context about memory storage and the purpose of clearing sensitive data, but does not disclose other behavioral details like error handling or effects on related data. This is adequate but not rich, hence a 3.

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

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

Two functional sentences plus a relationship hint, no fluff. Front-loaded with the action, then usage context, then sibling pairing. Every sentence earns its place.

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

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

For a one-parameter, no-output-schema deletion tool with strong annotations, the description covers purpose, usage conditions, and sibling relationships. It does not discuss the return value, but that is not critical for this tool's simplicity. Slightly more detail about behavior after deletion would warrant a 5.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The tool description adds 'previously stored memory' context but does not meaningfully go beyond the schema's 'Memory key to delete'. Baseline 3 applies.

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

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

The description uses a specific verb ('Delete'), identifies the resource ('memory'), and specifies the mechanism ('by key'). It also distinguishes from siblings by naming 'remember and recall' as complementary tools, making the tool's role 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 conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also references related tools ('Pair with remember and recall') but does not explicitly state when not to use the tool, so it misses the full 'when-not-to-use' guidance.

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

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

The description explains the underlying process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This adds context beyond the annotations (read-only, idempotent) by describing the network fetch and output behavior, without contradicting any annotation.

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

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

The description is concise at three sentences, with the first sentence front-loading the core purpose, the second explaining the process and output, and the third listing use cases. No unnecessary words or redundancy.

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

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

The description fully covers what the tool does, how it works, what output to expect ('single text blob ready to drop at site-root/llms.txt'), and when to use it. With strong annotations and no output schema needed, this is complete for the tool's complexity.

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

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

The schema already provides 100% coverage for both parameters, including descriptions for 'url' and 'max_links'. The description adds minimal parameter-specific meaning ('any URL' aligns with the schema), so the baseline of 3 is appropriate.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file' for any URL, with a specific verb and resource. It distinguishes from siblings by focusing on the llms.txt output format and its unique purpose, unlike other tools that are research or prediction oriented.

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: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It gives clear context for when to use the tool, though it doesn't explicitly mention alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, indicating a safe read operation. The description adds behavioral context by noting it returns the caller's subscriptions (privacy boundary), defaults to active only (excluding inactive unless requested), and provides a specific list of fields, which aids interpretation. It doesn't mention rate limits or pagination, but the annotations cover the safety profile sufficiently.

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 action and return values; the second gives usage guidance. It is front-loaded with the most important information, every sentence adds value, and there is no wasted wording or redundancy with the schema.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It specifies the resource (caller's subscriptions), the scope (active by default), the return fields, and the common use cases. The annotations cover safety semantics, so no additional behavioral disclosure is needed.

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

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

Schema coverage is 100%: the only parameter, include_inactive, is fully described in the schema with its type and default behavior. The description doesn't explicitly mention the parameter, but it aligns by saying "active subscriptions," implying inactive are excluded. Baseline 3 is appropriate since the schema carries the parameter documentation burden fully.

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

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

The description begins with a specific verb and resource: "List the caller's active subscriptions." It clearly distinguishes itself from sibling tools like subscribe and unsubscribe by framing itself as the review step before adding or canceling subscriptions, and by listing the exact return fields it provides.

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

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

The description explicitly states when to use it: "Use this to review what you're monitoring before adding more or to find an id to cancel." This gives clear context and intended usage. It doesn't explicitly name alternatives or say when not to use it, but the context is strong enough that a user can infer its role relative to subscribe/unsubscribe.

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

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

All annotations are false, so the description carries the full disclosure burden. It transparently covers the claim_token flow ('Filing without an account returns a `claim_token`; pass it back later...'), the daily rate limit ('Rate-limited to 5 per identifier per day'), and the free/no-quota nature ('Free; doesn't count against your tool-call quota'). It also states how feedback is used ('The team reads digests daily and signal directly affects roadmap'). 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 longer than average, but every sentence earns its place: it packs in purpose, usage conditions, exclusions, claim-token mechanics, rate limits, and cost information. It is front-loaded with purpose and then flows logically into guidelines and behavior. While it could be trimmed, the density is justified given the tool's non-obvious workflow and the need to prevent misuse.

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 explains what the tool returns ('a `claim_token`' and later 'whether it was fixed and what changed'). It covers the four parameters in a rich context: type is tied to examples, context is linked to Pipeworx tools/packs, message is given length guidance, and claim_token is given the full lifecycle. With sibling tools ranging from research to memory, this feedback tool's scope is clearly delimited, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds meaningful context for parameters, especially claim_token: it explains the round-trip workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'). It also advises on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which enriches the semantics beyond the schema's descriptions. The only minor gap is no extra clarification for the nested context object beyond schema, but schema already explains it well.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from the other Pipeworx tools like ask_pipeworx or deep_research by focusing on reporting issues about the tools themselves. The purpose is unambiguous and immediately 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 gives explicit guidance on when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also tells the agent when NOT to use it, specifically for tools from other MCP servers: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' This level of when/when-not detail is exemplary.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing safety. The description adds meaningful behavioral context beyond that: it is self-aggregating, derived from CF analytics-engine, contains no PII, and cached 5min-1h. It also discloses the output content (pack, tool, count). This goes beyond what annotations provide, so a 4 is appropriate.

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

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

The description is well-structured and front-loaded: the first line states the core answer, followed by concrete use cases and data-source/caching details. Every sentence adds value; there is no fluff or redundancy. The use case list is concise and informative, making the description efficient.

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

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

Given the tool's simplicity (one optional param, no output schema, strong safety annotations), the description is fully sufficient. It explains what is returned, how data is aggregated, privacy implications, and caching behavior. An agent can confidently decide whether to invoke this tool and what to expect. No critical gaps remain.

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

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

The input schema already provides 100% coverage for the single parameter 'window', including an enum and a description explaining the trade-off between windows. The tool description merely restates '24h, 7d, or 30d' without adding new meaning. Per the rubric, high schema coverage makes 3 the baseline, and the description does not exceed that.

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 with a specific verb and resource: it returns trending call data (top tools, top packs, total call volume) from other AI agents on Pipeworx. This distinguishes it from siblings like discover_tools or recent_alerts, which focus on different aspects. The first sentence directly answers what the tool does.

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

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

The description gives explicit use cases ('Useful for: ...') that explain when to use the tool, such as discovering hot data sources or confirming a canonical tool before asking a question. It does not name alternative tools or explicitly state when not to use it, but the context is clear and actionable. This aligns with 'clear context, no 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 only declare read-only/open-world/idempotent, but the description adds substantial behavior: the 200-market scope, >3pp threshold, semantic Jaccard ≥0.30 filter, placeholder-slug handling, and fill-check caution that realizable_edge_pp ≤ 0 means 'do not trade it.' 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 well-structured with capitalized section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the main usage. It includes many operational details that justify the length, though some prose is dense.

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

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

Even without an output schema, the description specifies response fields (opportunities[], partition_check{}, fill check) and covers all major behaviors, filters, and thresholds. It leaves little ambiguity for a complex tool with two optional modes.

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 both event and topic with examples; the description goes further by explaining what each mode does operationally (event walks child markets, topic searches related events across the platform) and giving example slugs/questions. This enriches the parameters beyond the schema's baseline.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (no-args trending scan, event, topic) and references a sibling tool for custom sizing, making its purpose unambiguous.

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

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

It explicitly prescribes when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also recommends 'event' for a specific market and directs users to polymarket_fill_risk for custom sizing, serving as an exclusion/alternative.

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

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

Annotations only state readOnly/idempotent/non-destructive; the description adds caching behavior (Cached 1h at KV level), response structure with by_segment and _diagnostics, the 24h-move warning, and explains why Fed bets are unreliable. This goes far beyond the annotation hints.

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

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

The description is a single dense paragraph with a massive amount of detail (model formulas, gate thresholds, response keys). While every sentence carries information, the lack of structure and excessive length may overwhelm agents; could be split into sections for easier scanning.

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 9 knobs and no output schema, the description covers model families, response layout (by_segment, fed_candidates, _diagnostics), filter semantics, and caching. Callers know exactly what they'll receive and why a segment may be empty.

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

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

Schema covers 100% of parameters with descriptions; description enriches this by grouping min_liquidity/max_spread_pp as 'tradeable-edge filters' and explaining that min_kelly applies only to single-leg, with a dedicated min_partition_leg_kelly. This adds design rationale beyond the schema.

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

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

The first sentence states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' – a specific verb+resource+goal. It further distinguishes itself from siblings with 'what should I bet on today' framing, contrasting with tools like polymarket_arbitrage or edge_tracker.

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 includes 'Built for "what should I bet on today"' implying when to use it for opportunity discovery, and notes Fed bets are excluded from ranking, giving an exclusion. However, it doesn't explicitly name alternative tools or state 'when not to use' compared to siblings like polymarket_arbitrage.

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

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

The description richly discloses behavioral traits beyond the annotations: history depth bounded by a 60-day TTL, dependence on snapshotting being enabled, gaps meaning no scan, and that decay numbers are computed from daily closes (not intraday). This adds significant context about data freshness and limitations. The annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint:false) are fully consistent with a read-only telemetry tool, with no contradiction.

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

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

The description is dense but well-structured, with clear sections for ARGS, RESPONSE, and LIMITS. It front-loads the core purpose in the first sentence, then methodically details the response structure and caveats. Every sentence contributes unique value, and the use of uppercase section markers makes it easy to scan. This is concise for the amount of behavioral information conveyed.

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

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

Given that there is no output schema, the description thoroughly covers the return value structure, including 'tracked[]', 'expired[]', 'snapshot_dates[]', and the meaning of each field (e.g., trend categories, decay_pp_per_day, lifespan_days). It also addresses edge cases like gaps and TTL limits. The annotations and input schema are fully utilized, and the description fills all remaining gaps, making the tool's behavior and output well-understood.

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 parameters are fully documented in the schema (100% coverage), including defaults and ranges. The description repeats the same information ('days (lookback, default 14, max 30)', 'window (snapshot family, default 1wk)') without adding substantial new semantics beyond the schema. It reinforces the meaning of 'window' as a snapshot family, but this is already clear from the schema's phrasing. Thus, the baseline score of 3 is appropriate.

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

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

The description clearly defines the tool as telemetry for edge persistence and decay, answering a specific question: 'how long has this edge existed and is it shrinking?' It explicitly distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current edges. The verb 'tracker' plus the specific resource (polymarket_edges snapshots) makes the purpose unambiguous.

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

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

The description provides strong contextual guidance on when to use this tool: to differentiate fresh vs. aged edges before trading ('a fresh wide edge and a 3-week-old wide edge are different trades'). It also mentions the median lifespan as a 'competition clock'. However, it does not explicitly name alternative tools or provide direct 'use this instead of X' instructions, so it falls short of a 5.

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

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

Annotations indicate a safe read-only, idempotent operation. The description adds substantial behavioral detail beyond those hints: it 'walks the ladder', returns specific computed metrics (top_of_book, vwap_fill_price, slippage_pp), and identifies risk factors like 'thin_legs' and 'forced_directional_risk.' 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 purposefully structured with labeled sections (SINGLE-MARKET and BASKET). It front-loads the core objective and uses capitalization for emphasis. Every sentence carries operational value; no filler or repetition. The length is justified by the tool's two modes and multiple return fields.

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

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

For a complex two-mode tool with no output schema, the description enumerates all return values per mode and explains their interpretation (e.g., capture_ratio, profit_usd, thin_legs). It covers parameter behaviors, defaults, and risk implications, making it complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter meaning significantly: 'size_usd (default 1000 — max spend on buys, target proceeds on sells)' for single-market mode and 'size_usd interpreted as settlement notional S (shares per leg; each share pays $1)' for basket mode. It clarifies defaults and mode-dependent interpretation beyond the schema entries.

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 phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly delineates the tool's function from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on execution risk rather than signal 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?

Explicitly instructs when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the consequence of misuse (partial basket fills converting an arb into an unhedged directional position), giving clear context for 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?

The description extensively discloses behavioral nuances beyond the readOnly/openWorld annotations. It explains exactly when compatibility_warning fires (two distinct conditions), how temporal_alignment affects spread validity, and what the skipped_cross_type/subtype counters represent. This level of transparency about edge cases equips the agent to interpret outputs correctly, especially given the absence of an output 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 long but well-structured with labels like 'TWO MODES,' 'RESPONSE,' and 'SAFETY FIELDS,' making it navigable. Every sentence adds substantive information relevant to tool execution. It could be slightly tightened, but the density and organization justify a high score.

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

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

With no output schema and a complex response structure, the description compensates by detailing the output: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also explains failure modes (e.g., when matched_pairs:0 and skipped_cross_type:0 indicate unrelated events). This makes the tool fully understandable and usable without additional documentation.

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?

While the schema already documents all three parameters with 100% coverage, the description adds meaningful interaction semantics: the topic parameter auto-fetches pre-mapped events, while the explicit parameters override the mapped side. This mode-based explanation helps an agent decide which parameters to populate and how they affect the request. The description also explains why custom pairings may be necessary.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly states the tool's purpose and distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on single-venue opportunities. The explicit mention of 'spread' and cross-venue comparison removes ambiguity.

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

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

The description clearly outlines two usage modes (topic shortcuts vs explicit ticker/slug) and provides guidance on when to use each. It also warns that pre-mapped topics often return compatibility warnings and are 'not tradeable,' setting expectations for when the tool is reliable. While it doesn't explicitly name alternative tools for use-cases like single-venue arbitrage, the context implies this tool is for cross-venue comparisons.

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. The description adds valuable scope detail (scoped to anonymous IP, BYO key hash, or account ID) and explains the list-all behavior when key is omitted. 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?

Three sentences, front-loaded with the core action, then usage context, scope, and sibling pairing. Every sentence adds value without redundancy.

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

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

For a simple single-parameter read tool with strong annotations, the description fully covers functionality, usage, scope, and relationships. No output schema exists, but return values are implicit from retrieval semantics and not necessary to explain further.

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 key parameter with 100% coverage. The description reinforces the meaning by specifying the key was 'previously saved via remember' and clarifies the omit behavior, adding context 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 retrieves previously saved values or lists all saved keys when the key is omitted. It names the specific resource (memory) and distinguishes from siblings by explicitly pairing with remember and forget.

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

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

Provides explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Also names alternatives (remember to save, forget to delete), giving clear when-to-use vs alternatives guidance.

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

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

The description adds useful behavioral context beyond the annotations: it explains the return fields (source, citation_uri, raw payload), and critically discloses the side effect of mark_read:true (flagging events read so future calls return only newer items). It also points to an external copy of the feed. Annotations already declare readOnlyHint=true, but the description appropriately clarifies the optional state change from mark_read without contradicting the hint.

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 purpose and then covers return fields, filters, side effects, and an alternative endpoint in a logical order. Though longer than two sentences, every sentence contributes value and there is no redundancy. It is appropriately concise for the tool's five parameters and no output schema.

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

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

For a tool with no output schema and five optional parameters, the description provides a complete picture: what it does, what each returned item contains, how to filter, the mark_read side effect, and an alternative endpoint for scripts. It does not explicitly describe limit/unread_only, but the schema covers those, so the description is complete enough for selection and basic invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond schema by giving an example type ('sec_8k'), explaining the effect of mark_read (flagging read so next call only shows newer ones), and clarifying that 'since' is an ISO timestamp. This adds practical semantics that help the agent select and format parameters correctly.

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

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

The description opens with a specific verb ('Pull') and resource ('subscription feed'), and clearly states what it returns: fired events with source, citation_uri, and raw payload. It distinguishes from sibling tools like recent_changes by focusing on the subscription/persisted feed, and provides concrete filtering examples.

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

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

The description gives clear context for when to use the tool (pulling alerts from the feed) and even mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. It states that polling works fine, which is practical guidance. However, it does not explicitly name sibling tools or state exclusions, so it falls slightly short of a 5.

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

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

Annotations already mark read-only/idempotent, and the description adds non-obvious behavior: parallel fan-out to SEC/GDELT/GNews/USPTO, GDELT→GNews fallback on rate-limit/5xx, and USPTO soft-fail due to PatentsView sunset. 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?

Though long, every clause adds value—examples, source behavior, fallback, return shape, and alternative. Front-loading with natural-language triggers makes skimming easy.

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

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

Given no output schema, it specifies return structure (changes[], total_changes, citation URIs) and notes external API limitations. Sibling context plus annotations cover the safety profile, making this 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 covers all three parameters at 100%, and the description's since/value explanations largely duplicate the schema's text plus a default recommendation. No extra semantic depth beyond schema.

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

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

The description opens with concrete user phrasings and clearly states it returns a change feed for a company over a window via one parallel call. It explicitly contrasts with entity_profile, so it differentiates itself 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?

It gives clear context for when to use (recent-change queries like 'what's new with X') and explicitly says to use entity_profile for static profiles. This is direct when-to-use vs 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 signal idempotent and non-destructive behavior. The description goes beyond by adding persistence semantics: authenticated users get persistent memory, anonymous sessions retain only 24 hours, and data is scoped by identifier. It does not mention overwrite behavior on duplicate keys, but the added storage context is valuable.

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 a clear front-loaded main verb, followed by usage context, storage semantics, and companion tool references. Every sentence earns its place; there is no fluff or redundancy.

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

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

For a simple two-parameter write tool with no output schema, the description covers purpose, when to use, persistence behavior, scoping, and companion tools. It is fully sufficient for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% and each parameter (key, value) is already well-described with examples in the schema. The description adds domain-level examples of what to store, but does not provide additional parameter syntax or format details beyond what the schema already contains.

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: 'Save data the agent will need to reuse later.' It clearly distinguishes itself from sibling tools like recall (retrieve) and forget (delete) by explicitly pairing with them, and enumerates example use cases (resolved ticker, target address, user preference).

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 an explicit 'Use when you discover something worth carrying forward' with concrete examples, and instructs pairing with recall and forget. However, it does not explicitly state when NOT to use it (e.g., transient data, or when recall is more appropriate), so it misses the 'when-not' half of the benchmark.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals important behaviors: cascading through multiple endpoints, labeling identifiers with their source, explicitly stating unresolved identifiers under 'unresolved' rather than omitting them, and graceful degradation when GLEIF/OpenFIGI are unavailable. This adds significant context about reliability and output completeness.

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 relatable examples and a clear purpose statement. It then systematically breaks down supported types and behaviors without repetition. Every sentence contributes new information, and the formatting using quotes and capitalization makes it scannable despite its length.

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

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

Given the complexity of two entity types with multiple ID systems, the description covers inputs, outputs, sources, error handling (unresolved identifiers), and degradation behavior. It fully equips an agent to decide when to call and what to expect, even without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches this by explaining what each 'type' does (company vs drug) and what 'value' can be (ticker, CIK, name, brand/generic). It also adds output context (e.g., returns CIK+ticker+company name, etc.), going beyond the schema's simple descriptions. This adds meaningful value, justifying a 4.

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

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

The description uses specific verbs and resources: 'resolve a user-spoken NAME to the canonical/official identifiers'. It lists concrete examples ('ticker for...', 'CIK for...') and distinguishes itself from siblings like entity_profile and compare_entities by focusing on ID resolution. The supported types (company, drug) are clearly outlined.

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

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

It explicitly states 'Use FIRST whenever you have a name but need an ID', giving a clear when-to-use. It also lists supported input types and notes it replaces 2-3 manual lookups. However, it doesn't mention when not to use or alternative tools (e.g., entity_profile for detailed profiles), so it falls short of a 5.

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

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

Annotations already declare readOnly and non-destructive behavior. The description adds that the tool probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score/confidence/signal density, providing behavioral context beyond the annotations. It also implies batched probing and potential external API calls via _apiKey, which is useful for the agent.

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

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

Three focused sentences cover purpose, mechanism, and use case without fluff. The opening sentence immediately states the core function, and each subsequent sentence adds high-value detail.

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

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

The tool has no output schema, but the description explicitly lists the return fields (score, confidence, signal density) and the ranked format, covering the missing output information. Combined with full schema coverage and non-destructive annotations, the description is complete for this tool's complexity.

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

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

Schema description coverage is 100%, so the schema already fully documents all four parameters. The description's reference to 'your brand + N competitors' and 'first entity as subject' is already captured in the schema's entity description, adding no new semantic information. Thus the description provides no additional value beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, which is specific and action-oriented. It also distinguishes itself from siblings by explicitly referencing ai_visibility_check as the probe mechanism and by focusing on competitive ranking.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with an example question, giving context for when to use. However, it does not explicitly mention when not to use or alternative tools like ai_visibility_check for single-entity checks, so it stops short of full exclusion guidance.

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

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

Adds significant behavioral context beyond annotations: network fan-out across two external APIs, graceful degradation with partial failures, latency caveat ('bundlephobia's first measurement on a new version can take 5-30s'), and the presence of sources_failed field. Annotations (readOnly, idempotent, openWorld) are complemented, not contradicted.

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 every sentence delivers distinct value: purpose, usage, sources, output fields, ecosystem limitation, failure behavior. It is well-structured and front-loaded with the core use case, making it easy for an agent to scan and understand.

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 enumerates the exact summary fields returned (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable) and mentions per-advisory detail, links, and alternative versions. It covers failure semantics and ecosystem constraints, making it fully self-contained for an agent.

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

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

Input schema already has 100% coverage for both parameters with clear descriptions. The description adds subtle meaning by linking version to latency ('new version can take 5-30s') and indicating that the package is npm-specific. This goes slightly beyond the schema's baseline but doesn't extensively expand on parameter syntax.

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 provides a specific, compound purpose: 'Composite "should I add this npm package to my project" check in ONE call' and lists the data sources (deps.dev, bundlephobia) and covered dimensions (license, advisories, bundle size, etc.). This clearly differentiates it from sibling 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?

Explicit trigger examples are given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states the ecosystem boundary and directs users to an alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This is strong when-to-use/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 establish read-only, idempotent, non-destructive behavior. The description goes beyond by disclosing the output format (passages with character offsets and similarity scores), the technical approach (BGE-base-en embeddings, cosine, 500-char overlapping windows), and the critical cap of 200K chars with truncation flagging. These are valuable behavioral details not present in 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?

Four dense sentences, each earning its place: purpose, when to use, pairing with a sibling tool, and technical constraints. Information is front-loaded with the core action in the first sentence, and no fluff or repetition exists.

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

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

Despite lacking an output schema, the description fully explains what the caller receives (top-N passages, offsets, scores). It also covers practical constraints (cap, truncation flagging) and use-case context. For a tool with 3 parameters and no nested objects, 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?

Schema description coverage is 100%, so the baseline is 3. The description adds usable context for parameters: 'text you already pulled' clarifies the source of text, 'natural-language query' reinforces the query type, and 'top-N passages' explains the limit parameter's purpose. This is a meaningful enhancement over the schema's dry parameter descriptions, though not exhaustive, hence 4.

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

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

The description states a specific verb ('semantic search') and resource ('a fetched record' / source), clearly distinguishing it from sibling tools like ask_pipeworx_grounded. It also specifies the input type (text already pulled) and the output (passages with offsets and similarity scores), leaving no ambiguity about what the tool does.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and explicitly pairs with ask_pipeworx_grounded: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and an alternative, matching the high-calibration example.

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

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

Beyond the annotations, the description discloses important behavioral constraints: requires OAuth account, SMS phone verification, 10/day SMS cap, and that the feed channel is always on. It also states the return value. These add value beyond the annotations and do not contradict them, though it does not describe webhook auto-disable or signature verification in the narrative (schema covers those).

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

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

The description is dense but well-structured, packing examples and constraints into a compact block. Every sentence adds useful information, but the inline list of types and channels makes it slightly long. Still, no fluff or redundancy.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers the return value, auth requirements, and delivery channels sufficiently. It does not enumerate all 5 types in the narrative, but the input schema's enum and parameter descriptions fill the gap, making the overall tool context complete when both are considered.

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, but the description enriches parameter meaning by providing concrete examples like items:["5.02"] = officer change and explaining polymarket_edge as cross-venue mispricings. The description omits patent_grant and clinical_trial types, but the schema's param descriptions cover them, so no semantic gap.

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 'Create a proactive monitoring subscription to a live-data event stream,' which uses a specific verb and resource and clearly distinguishes this from sibling tools like list_subscriptions or recent_alerts. It also states the return value (new subscription id), leaving no ambiguity about the tool's function.

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

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

The description provides clear context for when to use the tool: it requires a Pipeworx OAuth account and explicitly excludes anonymous/BYO users. It also gives usage guidance for consuming the feed via recent_alerts or GET registry.pipeworx.io/alerts.json. However, it does not explicitly mention alternatives like list_subscriptions or unsubscribe for managing existing subscriptions, so it lacks explicit when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds beyond these by explaining the output shape (category-bucketed example questions with tool+argument shapes), the optional topic filtering, and that it draws from a live catalog. It does not introduce side effects or contradict annotations.

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

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

The description is fairly long but each part earns its place: the initial question phrases serve as natural-language trigger examples for the agent, and the subsequent clauses explain functionality and usage. It is structured as one continuous sentence, which is slightly dense, but it remains readable and free of fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It covers what the tool returns, how to call it (no arguments or with topic), its role as a first-step onboarding tool, and it carries the burden of explaining return values (which it does by describing category-bucketed example questions). The annotations cover safety, and the schema covers parameters, so the description fills all remaining gaps.

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

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

The input schema already describes the `topic` parameter completely, listing all allowed values and noting that omitting it returns a cross-category spread. The description repeats this information with examples like 'finance', 'pharma', 'betting', but does not add new meaning beyond what the schema already provides. Since schema coverage is 100%, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as the onboarding entry point for an agent wanting to know what to ask Pipeworx. It uses specific verbs like 'returns' and 'suggest' and distinguishes itself from siblings by explicitly mentioning it teaches how to call meta-tools (ask_pipeworx, entity_profile, compare_entities) and by being the 'FIRST' tool to use when unfamiliar with 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?

The description 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.' This gives clear context for when to use it, but it does not explicitly state when not to use it or name alternative tools to consider, only implying that more specific tools exist.

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 non-read-only, non-destructive, idempotent behavior; the description adds specific context about ownership enforcement and soft-delete semantics, ensuring the agent understands the side effects. It does not contradict annotations.

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

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

Three concise sentences deliver the core action, a security constraint, and a behavioral nuance without waste.

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

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

For a single-parameter tool with no output schema, the description covers what, who, and the side effects; the existence of recent_alerts is mentioned for follow-up, making the context complete.

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

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

The schema already covers the sole parameter with 100% coverage; the description reinforces that the id comes from subscribe and is subject to ownership, adding practical meaning beyond the schema.

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

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

The description uses the specific verb 'Cancel' with the resource 'subscription' and identifies the key input (id), clearly distinguishing it from sibling tools like subscribe and list_subscriptions.

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

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

It notes ownership restrictions ('only cancel your own subscriptions') and explains the consequence of cancellation (deactivation, not deletion), which guides when to use this tool vs recent_alerts for history. It doesn't explicitly exclude alternatives, but the context is sufficient.

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 annotations, the description discloses the two processing pipelines, the natural-language to structured data fast path with exact math, and the return structure including verdicts, actual value with pipeworx:// citation, and reasoning. Crucially, it differentiates could_not_verify (check didn't happen) from unsupported (no source coverage), warning callers not to treat could_not_verify as evidence. This is substantial behavioral context that prevents misuse.

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

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

The description is long but densely packed with valuable information, front-loaded with query examples and purpose before diving into routing details. While every sentence adds meaning, the 'Replaces 4–6 sequential calls' note is somewhat auxiliary and could be trimmed for brevity. Overall, it's 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?

With no output schema present, the description fully compensates by enumerating all possible verdicts, the structure of the returned value with citation and reasoning, and explaining error semantics. It covers the full lifecycle from input to interpretation, making it complete enough for an agent to handle both normal and edge-case outcomes.

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 clear descriptions. The description adds extra nuance, such as tolerance_pct overriding the claim-implied tolerance, its 0.5–50 range, and the default cap of 5. This goes beyond the schema's basic definition and helps the agent understand how the parameter behaves in practice.

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 and resource: 'natural-language claim verification against authoritative sources,' and provides concrete example queries like 'fact check' and 'verify the claim that…'. It clearly distinguishes itself from sibling tools by explaining the two routing paths (SEC EDGAR for financial claims, grounded pipeline for others) and explicitly noting it replaces sequential lookup calls.

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

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

Explicitly instructs 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies scope boundaries by explaining the different handling for company-financial vs. other claims and the meanings of could_not_verify vs. unsupported. However, it doesn't name alternative tools or state when not to use it, so it falls just short of a perfect score.

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