Rawg

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds return format details (score, confidence, signals, raw_response) and notes that Anthropic calls are billed directly by Anthropic, complementing the annotations well.

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: first states action and output, second explains defaults/key usage, third lists use cases. No redundancy, front-loaded with purpose.

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

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

Given 4 params, no output schema, and no nesting, the description covers return format (per-model + combined) and key behaviors. No missing critical info for a probe 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%; description adds value by clarifying defaults (Workers AI free, Anthropic requires key) and explaining the context parameter's role in disambiguation, going beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for visibility scores (0-100) per model, distinguishing it from siblings like entity_profile or scan_competitor_ai_presence by focusing on AI visibility rather than general entity info or competitive scanning.

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

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

The description specifies default model, when to use _apiKey for Anthropic, and lists use cases (AI-marketing audits, brand checks). It lacks explicit 'when not to use' or contrasts with siblings, but provides sufficient context for appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context beyond annotations: it routes to many underlying tools, returns citation URIs, is a single fast call, and works on every tier. It does not contradict annotations and provides meaningful operational detail.

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 quite long and promotional, with a large list of domains and examples. While each section serves a purpose, it could be tightened significantly. It is well-structured with bold lead-ins, but verbosity prevents a higher 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?

For a tool with a single required parameter and no output schema, the description is complete: it explains what the tool does, when to use it, how to phrase questions, and what to expect in return (structured answer with citations). It also covers edge cases like breaking news and step-up alternatives.

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 includes a description for 'question' with aliases. The description adds example questions but does not explain parameter formatting beyond the schema. Since schema already carries the load, 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 explicitly states what the tool does: routes questions to one of 5,439 tools across 1,412 sources, fills arguments, and returns structured answers with pipeworx:// citations. It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by comparing when each should be used.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', tells the agent to 'Use whenever the user asks...', includes trigger phrases and examples, and names alternatives with clear conditions ('Step up only when needed'). This is exemplary usage guidance.

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

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

Annotations cover safety (read-only, idempotent, non-destructive). The description adds experimental status, active-candidate state, and current equivalence to ask_pipeworx. However, it does not detail response format beyond referencing ask_pipeworx's shape.

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-load purpose and usage, with no redundancy. Every sentence provides distinct, necessary context.

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 router with no output schema, the description sufficiently explains what it is, how to use it, and its experimental nature. It references ask_pipeworx's response shape but does not describe it, though this is acceptable given sibling context.

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

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

Schema coverage is 100%, with question and its aliases fully described. The description only notes 'same arguments' without adding new parameter meaning, so baseline 3 is appropriate.

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

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

Description clearly identifies it as the beta version of ask_pipeworx, a universal router with the same 5,439 tools, arguments, and response shape. It distinguishes itself from stable ask_pipeworx and ask_pipeworx_grounded by being the experimental edge.

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

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

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router, giving both a clear when-to-use and implying the stable alternative.

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

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

The description details the exact refusal behavior with specific refusal_reason values, the structured success response containing evidence and confidence, and the constraint that only tool-result content is used. This goes well beyond the annotations (readOnlyHint, idempotentHint, openWorldHint) and adds cost/invocation behavior.

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

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

The description is information-dense and front-loaded with the key differentiator ('Hallucination-resistant answer mode'). While it is longer than the minimum, every sentence contributes useful detail about process, return format, refusal reasons, usage context, and tradeoff; the structure is logical and easy to scan.

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

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

Given that there is no output schema, the description fully specifies the success return object and all five refusal reasons. It also covers cost, usage context, and sibling differentiation, making the description contextually complete for an agent to decide when and how to invoke the tool.

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

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

The input schema already covers 100% of the parameters (question plus five aliases), so the description does not need to add parameter-level detail. It adds no new meaning beyond what the schema provides, but the schema itself fully documents each alias, so a baseline 3 is appropriate.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, with a specific process of routing to tools and extracting answers only from tool results. It explicitly distinguishes itself from the sibling ask_pipeworx by describing the grounded extraction and refusal mechanism.

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

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

The description gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and facts must not be invented. It also provides an explicit alternative (ask_pipeworx for casual lookups) and notes the extra LLM call cost, making the choice clear.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description richly details behavioral traits: market resolution, classification, parallel fan-outs, response shapes, resolver contract, parent event extraction, news fallback handling, safety short-circuits for low-confidence and closed markets, tradeability warnings, and cancellation rule parsing. 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 comprehensive but quite long (over 2000 characters). It front-loads the core purpose and uses section keywords (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) to structure dense technical details. While every sentence adds value, the length may reduce scannability for an AI agent, earning a mid-range score.

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

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

Given the tool's complexity and lack of output schema, the description provides exhaustive detail about response fields (market, analysis, evidence, parent event, news fields), edge cases (low-confidence matches, closed markets, wide spreads), and resolution risk (cancellation rules). It covers all necessary context for an agent to interpret and safely use the tool.

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

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

Schema description coverage is 100%, and the description adds extra context: examples of market input (slug, URL, question text), explanation of depth with examples 'quick' vs 'thorough', and the purpose of include_raw with its typical size implications. This adds value beyond the schema while the schema already covers parameter types and defaults.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and action (pull Pipeworx data). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on data research for bet evaluation, not 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 explicitly states usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-outs per category and warns about checking market match confidence and cancellation rules. While it does not explicitly state when not to use it, the alternative sibling tools imply other use cases, and the cautionary notes guide appropriate usage.

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

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

Annotations indicate readOnly, idempotent, not destructive. Description adds fiscal year handling (AAPL Sep, NVDA Jan), data sources (EDGAR/XBRL, FAERS/FDA), and return format (paired data + citation URIs). 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?

Single block but dense with examples and specifics. Front-loaded with query patterns. Could use slight structuring (e.g., broken by type) but remains 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 full schema coverage and annotations, description explains return format and sorting. Omits error handling or edge cases, but sufficient for typical use.

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

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

Schema coverage is 100%. Description clarifies values for each type (tickers/CIKs for companies, drug names for drugs) and specifies min/max items and sorting behavior. Adds meaning beyond enum labels.

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 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' with concrete examples like 'compare X and Y', and differentiates from 'sequential single-pack lookups'. It specifies data sources for each type and mentions sorting by primary metric.

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 advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides query patterns (head-to-head, rank, vs). Does not explicitly list when to avoid, but the context is clear.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive traits. The description supplements this with rich behavioral detail: the tool returns explicit gaps[] (never invents facts), provides contradictions[], includes hop and citation_uri fields, semantically excerpts large records, and has timed expectations (15-60s, up to ~90s for thorough). It also discloses the account requirement and paid-tier restriction, which is beyond what annotations convey. The only reason it's not a 5 is that the description is so dense that a few details like 'findings packet' could be more clearly structured.

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 quite long and dense, packing many details (account requirement, output format, hops, contradictions, timing, excerpts) into a single paragraph. While every detail has value, the lack of paragraph breaks or bullet-style structure makes it harder to scan quickly. It is front-loaded with the account warning and primary use case, which helps, but overall it's a wall of text.

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

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

For a complex tool with no output schema, the description does a great job covering what the user will get back: findings with verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop field, and citation_uri. The 2 parameters are well documented in the schema, and the description explains edge cases like empty gaps[] for non-catalog topics. Missing a short mention of output format (e.g., 'returns an array of findings'), but the findings packet description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by explaining the depth parameter's practical implications ('standard=5', 'adds a gap-recovery hop'), and describes the question parameter as accepting broad/multi-part natural language. It does not fully explain how depth values map to cost/time in the schema, but the description compensates with real-world trade-offs, making it a 4.

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

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

The description opens with a specific verb+resource ('grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources') and is very explicit about what the tool does and does not do ('this is NOT open-web search'). It clearly distinguishes itself from sibling tools like ask_pipeworx and bet_research by emphasizing parallel decomposition across 5,439 tools and returning a findings packet.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and gives concrete counter-examples ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It even names the alternative tool and explains why it is better for those cases.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds beyond that: it discloses the output format ('returns 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,' which is valuable behavioral context.

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

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

The description is front-loaded with the core purpose. It lists many domains, which is helpful but slightly verbose. Every sentence adds value; there is no fluff. It could be trimmed slightly, but it is well-structured and 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?

Given the complexity (6 parameters, no output schema), the description fully compensates by explaining the output: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' It also addresses the tool's role in the overall workflow. No 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?

Schema description coverage is 100%, so baseline is 3. The description mentions 'query' and 'task' but does not add semantics beyond what the schema provides for each parameter. However, it clarifies that multiple aliases exist, which is a minor addition. No significant extra meaning.

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

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

The description begins with 'Find tools by describing the data or task,' clearly identifying the tool's purpose. It lists numerous specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by emphasizing 'Call this FIRST when you have many tools' and that it returns tools ready to call—differences from direct answer tools like deep_research or search_within.

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

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

The description explicitly states when to use the tool: 'when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It provides examples but does not explicitly mention when not to use it or alternatives, though 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?

Adds context beyond annotations: it fans across multiple sources, mentions patent soft-fail due to API sunset, and lists return fields. Annotations already cover readOnly, openWorld, idempotent, and non-destructive.

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

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

Front-loaded with example queries, well-structured, but slightly verbose in enumerating all output fields; still 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?

Despite no output schema, description fully explains return fields, data sources, fallbacks, and limitations, making it complete for an aggregation 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%, so description adds minimal new info beyond reinforcing that type is limited to 'company' and value must be ticker or CIK, which is already in 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 clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call' with specific verbs like 'brief me on' and 'company profile for', distinguishing it from chaining individual lookups.

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 tells when to use (holistic view requests) and when not (names not supported, use resolve_entity first), and states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'.

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 destructiveHint=true and idempotentHint=true, which cover the behavioral traits. The description adds usage context (clearing stale or sensitive data) but does not contradict the annotations. No additional behavioral detail beyond the annotations is needed.

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

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

The description is two sentences long, with the first defining the action and the second providing usage guidance. Every sentence is essential and front-loaded, making it efficient and easy to parse.

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 delete operation with a single required parameter and no output schema, the description is fully complete. It covers the action, usage context, and relationship with sibling tools, leaving no 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 has 100% coverage for the single 'key' parameter, which already describes it as 'Memory key to delete'. The description does not add new semantic information about the parameter, so a baseline score of 3 is appropriate.

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

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

The description explicitly states 'Delete a previously stored memory by key', using a specific verb and resource. It also mentions pairing with sibling tools 'remember' and 'recall', clearly distinguishing its role.

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

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

The description provides clear when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It suggests pairing with siblings but doesn't explicitly state when not to use or alternatives beyond the immediate family.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds behavioral detail: fetches page, extracts title/description/key links, emits standard markdown format. This provides useful context beyond the annotations.

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

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

The description is a single, well-structured paragraph with front-loaded main action. Every sentence adds value: purpose, process, output format, use cases.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description is complete. It covers purpose, process, output format, and use cases. No missing information needed for agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds some context (e.g., what the tool does with the URL) but mostly repeats schema info for max_links. The output format hint is helpful, but not directly about parameters.

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

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

Description clearly states the tool generates a llms.txt file for any URL, specifying the output format and use cases. It distinguishes from sibling tools which are mostly research or game-related, none of which perform this 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?

Description lists explicit use cases (client indexing, personal project drafting, competitor auditing). Does not explicitly state when not to use or mention alternatives, but the context is clear enough given the sibling list.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already declare safety. The description adds value by listing the specific fields returned (description, ratings, Metacritic score, etc.) and providing an example, but does not contradict annotations.

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

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

The description is two sentences, front-loads the purpose, and includes an example. Every sentence is useful and concise with no wasted words.

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

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

Given the annotations cover safety and idempotency, and the schema covers parameters, the description adds the list of return fields and an example. No output schema exists, but the description compensates adequately. However, it could mention expected data size or rate limits.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description's example adds a concrete id value but does not add meaning beyond the schema's description of the id parameter.

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

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

The description uses specific verb 'Get' and resource 'single video game', lists fields (description, ratings, Metacritic score, etc.), and provides an example. This clearly distinguishes it from sibling tools like search_games.

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

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

The description implies use for retrieving full details of a single game but does not explicitly state when to use this tool over siblings (e.g., search_games). No when-not or alternative guidance is given.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which cover the main behavioral traits. The description adds that the tool returns game counts per genre, but does not elaborate on other behavioral aspects like rate limits or response structure. The description is consistent with annotations and adds minor context.

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

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

The description is a single, well-structured sentence that front-loads the main action and includes concrete examples. Every word contributes value, with no wasted text.

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 simplicity of the tool (no required parameters, no output schema), the description provides sufficient context: what it lists, from where, and what additional info is included. It could be slightly more complete by describing the return format (e.g., a list of objects), but the examples partially address that. No output schema exists, so the description carries the burden adequately.

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

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

The single parameter _apiKey is fully described in the input schema (100% coverage), so the description adds no additional meaning. Baseline score of 3 applies because the schema already handles parameter documentation adequately.

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 ('List') and clearly identifies the resource ('all video game genres in the RAWG database') and additional detail ('with game counts per genre'), with concrete examples. It distinguishes this tool from sibling tools like list_platforms, which lists a different resource.

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 implicitly indicates when to use the tool (when listing genres), but provides no explicit guidance on when not to use it or alternatives. For a simple listing tool this is adequate, but it does not reach the standard of explicitly stating use cases 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the output includes game counts per platform, but does not detail other behaviors (e.g., pagination, ordering).

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, concise sentence with no fluff, front-loading the key information (list all platforms with game counts) directly.

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

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

For a simple read-only list tool with rich annotations, the description adequately covers what the tool does and returns. Minor missing details like pagination are acceptable given the simplicity.

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

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

Schema description coverage is 100% for the single optional parameter _apiKey, which already has a good description. The tool description adds no further parameter insight, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists all gaming platforms in the RAWG database with game counts per platform, and provides concrete examples (PC, PlayStation 5, etc.), making the purpose unambiguous.

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

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

No guidance on when to use this tool versus sibling tools like list_genres or search_games. The description only states its function without usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns specific fields and pertains to the caller's subscriptions, providing moderate additional context without contradiction.

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

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

The description consists of two efficient sentences. The first sentence states the core purpose, and the second provides usage guidance. No extraneous content.

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

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

For a simple read tool with one optional parameter and no output schema, the description adequately covers functionality, returned fields, and usage context. No 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 covers the single optional parameter (include_inactive) with a complete description. The tool description adds no additional parameter information, so baseline 3 applies.

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

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

The description clearly states the verb 'List', the resource 'subscriptions', and the scope 'caller's active'. It also enumerates the returned fields, distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

The description provides explicit usage context: 'use this to review what you're monitoring before adding more or to find an id to cancel.' It implies when not to use it (when not needing to review), but does not name alternatives directly.

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 provide no safety hints (all false), but the description discloses rate limiting (5 per identifier per day), that it doesn't count against tool-call quota, that the team reads digests daily, and that signal affects roadmap. This is rich behavioral context beyond the schema/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 well-structured: purpose first, then usage triggers, exclusions, message guidance, and operational details. Each sentence serves a purpose, though it's longer than typical; still 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 3 params, a nested context object, and no output schema, the description covers all essential operational aspects: what, when, when not, how to phrase, rate limits, and quota. It is complete for agent decision-making.

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 100% of parameters with descriptive text. The description adds extra guidance for the message parameter: 'don't paste the end-user's prompt' and frame issues in terms of Pipeworx tools/packs. This complements the schema, earning a 4 rather than baseline 3.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling query/research tools by explicitly scoping to Pipeworx feedback, making it easy to identify.

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 explicit when-to-use triggers: bug, feature/data_gap, praise, and an exact when-not-to-use: tools from other MCP servers. It also instructs users to describe issues in terms of Pipeworx tools/packs, not paste end-user prompts, and notes rate limits.

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

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

Discloses data source (CF analytics-engine), privacy (no PII), output structure (pack, tool, count), and caching behavior (5min-1h). These details add value beyond the annotations, which already declare read-only and idempotent hints.

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

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

Single paragraph with no wasted words. Front-loaded with the primary function, followed by structured use cases and technical details. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description fully explains what the tool returns (top tools, packs, call volume), the data source, and caching. No 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 schema covers 100% of parameter documentation, including an enum and description. The tool description does not add new semantic information about the 'window' parameter beyond what the schema provides, meeting the baseline.

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

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

The description clearly states the tool returns trending data (top tools, packs, call volume) with a specific verb 'calling on Pipeworx'. It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on aggregate trending statistics.

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 three concrete use cases (discovering hot data, confirming canonical tools, aligning with agent needs) but does not explicitly state when not to use it. However, the use cases imply clear context for appropriate usage.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral detail: partition checks, fill checks, semantic anchor, placeholder filtering, and response structure. 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 well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose/mode selection. While dense, it is efficient and each part adds value. Could be slightly more concise but still high-quality.

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 thoroughly explains the response structure including opportunities array, partition_check fields, and fill check results. It also references a complementary tool (polymarket_fill_risk). The description is complete for the tool's complexity.

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

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

Schema coverage is 100% and the description adds valuable context beyond schema: examples of valid slugs, acceptance of full URLs, and seed question examples. This helps the agent understand acceptable input formats.

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 finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks, with specific modes (no args, event, topic). It effectively distinguishes the purpose from general trading or research tools, though it doesn't explicitly differentiate from sibling tools like polymarket_edges.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It recommends event mode for specific markets and explains the advantage of cross-event mode. However, it doesn't explicitly say when not to use the tool or compare it to 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 (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) are consistent and the description adds extensive behavioral context: model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), caching (1h at KV level), response structure with diagnostics, and tradeable-edge knobs. 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 long but well-structured, front-loaded with purpose and then detailed sections. Every sentence adds value, covering model families, response fields, knobs, and diagnostics. Could be slightly more concise but is efficient for the complexity.

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

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

No output schema, so the description thoroughly explains the return format: by_segment groups, edge attributes (edge_pp_net, kelly_fraction, etc.), diagnostics, fed_candidates, and caching behavior. Complete for an agent to understand the response 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?

Schema coverage is 100% with detailed descriptions for all 9 parameters. The description adds some context (e.g., explanation of 'Tradeable-edge knobs' and min_partition_leg_kelly), but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate given high coverage.

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

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

Description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. The verb 'scan' and resource 'Polymarket markets' are specific. The purpose 'what should I bet on today' is explicit. While sibling tools like polymarket_arbitrage and polymarket_edge_tracker exist, the description uniquely positions this tool for edge discovery using Pipeworx signals, making it distinguishable.

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 explains what the tool does but does not provide explicit guidance on when to use it versus siblings such as polymarket_arbitrage or polymarket_edge_tracker. There are no when-to-use or when-not-to-use statements. The implied usage is for discovering opportunities, but without explicit alternatives, it scores 3.

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 readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: snapshots have a 60-day TTL, decay is computed from daily closes of edge_pp_net net of default slippage, gaps mean no scan occurred, and it explains the response structure (tracked, expired, snapshot_dates). 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 front-loaded with the core question and purpose. It is somewhat verbose but each sentence adds value. The structure flows from purpose to response format to limits, making it easy to follow.

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 has only two parameters and no output schema, the description is remarkably complete. It details the response structure (tracked, expired, snapshot_dates) and boundary conditions (TTL, history depth), leaving little ambiguity for an agent.

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

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

Input schema has full coverage with clear descriptions. The description restates parameters (days and window) and adds context: days are lookback with default 14 and max 30 (consistent with schema's 'clamp 2-30'), window is described as 'snapshot family' which adds meaning beyond the schema's wording.

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

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

The description clearly defines the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes between a fresh wide edge and an old one, which differentiates it from siblings like polymarket_edges.

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

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

The description explicitly states what the tool answers ('how long has this edge existed and is it shrinking?') and provides context for when to use it. It does not, however, explicitly state when not to use it or list alternative tools.

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

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

Description reinforces readOnlyHint and destructiveHint by describing it as a check. Discloses that partial basket fills can convert arb into unhedged directional position. No contradictions with annotations.

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

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

Dense but well-organized; front-loaded with purpose. Every sentence adds value. Could be more structured with sections, but given complexity, it is 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 no output schema and high complexity (two modes, warnings), description covers inputs, behaviors, risks, and usage context completely. No 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?

Despite 100% schema coverage, description adds meaning: explains default values, interpretation of size_usd in both modes, side auto-detection for baskets, and clamping range. Significantly enhances understanding.

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

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

Clearly states it checks realizable-vs-theoretical edge against CLOB order-book depth. Distinguishes between single-market and basket modes. Purpose is immediately clear and distinct from siblings like polymarket_arbitrage.

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

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

Explicitly says when to use (before acting on arbitrage signals or trades above ~$500) and why (theoretical overround not capturable, partial fills cause directional risk). No ambiguity.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), description details response structure, compatibility_warning cases (matched_pairs=0 with specific conditions), temporal alignment checks, and skipped counters. 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?

Well-structured with section headers (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with key modes. Somewhat lengthy but each sentence adds value for the complexity.

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

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

With 3 optional parameters and no output schema, the description covers response fields, edge cases (compatibility_warning, temporal alignment), and behavior for both modes. No gaps in explaining what the tool returns.

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

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

Schema coverage is 100%, but description adds significant meaning: explains how 'topic' maps to 10 pre-mapped shortcuts, how explicit tickers override, and provides example values. Also describes response fields like top_spreads_pp.

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

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

Description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, and explains when the delta is a real signal. Distinguishes from sibling tools which are unrelated (no other spread tool).

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

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

Explicitly describes two modes (topic shortcuts and explicit tickers), and provides safety fields to warn when spreads are not meaningful (compatibility_warning, temporal_alignment). Also warns that pre-mapped shortcuts are not always tradeable.

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 scoping context (anonymous IP, BYO key hash, account ID) beyond annotations, without contradiction.

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

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

Three sentences, front-loaded with main action, no wasted words.

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

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

Sufficient for a single optional parameter tool with good annotations; covers purpose, usage, behavior, and parameter.

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?

Adds meaning beyond schema by explaining that omitting the key lists all saved keys, leveraging 100% schema coverage.

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

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

The description clearly states the tool retrieves a previously saved value or lists all keys, distinguishing from sibling tools like 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 concrete use cases (e.g., target ticker, address, research notes) and mentions pairing with remember/forget, though could explicitly exclude alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds that mark_read flags returned events as read in same call and that polling is fine—useful behavioral detail without contradiction.

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

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

Four efficient sentences: purpose, what is returned, filtering options, mark_read, and alternative endpoint. No fluff; 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?

With no output schema, description specifies return fields (source, citation_uri, raw payload). Covers filtering, mark_read, and alternative access. Could mention limit behavior or unread_only, but overall sufficient for a retrieval tool.

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

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

Schema coverage is 100% with schema descriptions. Description adds context: example filter value ('sec_8k'), purpose for mark_read, and mentions ISO timestamp format. Does not explain limit or unread_only further, but schema already does.

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

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

The description clearly states the tool pulls fired events from subscription feed, specifying returned fields (source, citation_uri, raw event payload). This verb+resource description distinguishes it from siblings like list_subscriptions and subscribe.

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 filtering guidance (type, since), mark_read behavior, and notes that polling works fine, plus an alternative REST endpoint. Lacks explicit when-not-to-use or direct sibling comparisons, but overall clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, establishing a safe, idempotent operation. The description adds significant behavioral context: the fan-out to multiple sources, fallback logic (GDELT→GNews), soft-fail for USPTO, and return structure (changes grouped by source, count, citation URIs). 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 concise yet thorough, with example queries front-loaded. Every sentence serves a purpose, covering usage, parameters, source details, and alternative tool mention. No filler or repetition.

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

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

Despite having no output schema, the description fully informs the agent about what to expect: changes grouped by source, total_changes count, and citation URIs. It covers all three parameters, source behavior, fallback, and boundaries (only company type). The contrast with 'entity_profile' completes the contextual picture.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that 'since' accepts ISO dates or relative shorthand, provides examples, and recommends '30d' or '1m'. It also clarifies that 'value' can be a ticker or CIK, and 'type' is limited to 'company'. This goes beyond the schema's own descriptions.

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

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

The description begins with example queries demonstrating the tool's purpose and explicitly states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It distinguishes itself from the sibling tool 'entity_profile' by advising when to use that alternative, ensuring 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?

The description provides explicit usage guidance: it fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO. It also tells when not to use it (use 'entity_profile' for static profiles) and gives specific recommendations for the 'since' parameter, such as using '30d' or '1m' for typical monitoring.

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 context beyond annotations: scoped by identifier, persistent vs 24-hour retention. Annotations already indicate idempotentHint=true and destructiveHint=false, and the description aligns without contradiction.

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

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

Four sentences, front-loaded with main purpose, no unnecessary words. Each sentence adds distinct information (what, when, scope, pairing).

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?

Complete for a simple 2-parameter tool: covers purpose, usage context, pairing, scoping, and persistence. No gaps given the tool's simplicity.

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

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

Schema coverage is 100% with descriptions. The description adds value by giving example key formats and clarifying that value can be any text, reinforcing practical usage.

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 'Save data the agent will need to reuse later' with specific examples like resolved ticker, target address, user preference. It distinguishes from sibling tools (recall, forget) by describing its function as storing key-value pairs.

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 tells when to use: 'when you discover something worth carrying forward'. Provides guidance on pairing with recall and forget, and differentiates between authenticated and anonymous sessions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds valuable context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups,' which aids understanding of internal behavior without contradiction.

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

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

The description is front-loaded with query examples, then instructions, then detailed type explanations. While slightly lengthy, every sentence adds value and there is no redundancy. Could be slightly more compressed but maintains clarity.

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 2 parameters, no output schema, and annotations present, the description covers purpose, usage, parameter details, and behavioral transparency. It implicitly describes return values (ticker, CIK, RxCUI) but lacks explicit output structure, which is a minor gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining the format for 'value' (e.g., 'ticker (AAPL), CIK (0000320193), or name') and mentions auto-disambiguation, enhancing parameter understanding.

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

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

The description clearly states the tool's purpose: resolve a user-spoken name to a canonical identifier. Examples like 'What's the ticker for…' make it intuitive. It also distinguishes from siblings by positioning it as the first step when an ID is needed, though no sibling directly conflicts.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear context. Lists supported entity types with details. However, it does not explicitly state when not to use it or name alternative tools, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds valuable behavioral context: the tool internally calls 'ai_visibility_check' for each entity, ranks results, and returns a ranked list with score, confidence, and signal density. 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 four sentences, front-loaded with the main action, then explains the process, gives a practical use case, and lists return elements. No redundant or unnecessary sentences.

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 adequately summarizes return fields (score, confidence, signal density). Input parameters are fully covered by the schema. It does not address edge cases like error handling or rate limits, but for a comparative tool with comprehensive annotations, it is sufficiently complete.

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

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

Schema coverage is 100% so parameters are well-documented. The description adds a small but useful semantic note: 'First entry treated as the "subject" for narrative; rest are competitors.' This helps the agent understand the role of the 'entities' order.

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') and resource ('AI visibility across multiple entities'), clearly distinguishes from siblings like 'ai_visibility_check' (single entity) and 'compare_entities' (general comparison). It states exactly what the tool does: probes entities, ranks by score, surfaces most/least recognized.

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 concrete use case ('competitive AI-marketing audits') and implies when to use this over alternatives (single-entity check vs. multi-entity comparison). It does not explicitly state when not to use or list alternatives, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds behavioral details: fans out across two services, partial failure handling, bundlephobia timing (5-30s), and listing failed sources. 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 a single paragraph but front-loaded with the core purpose. Some verbosity in enumerating return fields, but every sentence adds value. Could be slightly more structured (e.g., bullet points) but remains clear.

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

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

Despite no output schema, the description fully explains return structure (summary block, per-advisory details, links, alternative versions). Covers partial failures, ecosystem scope, and timing. Complete for a 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 coverage is 100% with clear descriptions. The description adds value by mentioning scoped packages ('@types/node') and explicitly stating version defaults to latest. While the schema already covers basics, the description reinforces and adds context.

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

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

The description clearly states the tool performs a composite check for npm packages, combining deps.dev and bundlephobia data. It uses specific verbs ('check', 'fans out') and resources ('npm package'), and the function is distinctive among siblings (none other do this composite check).

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 specifies when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also states limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', and handles partial failures gracefully.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds behavioral context by listing return fields (ratings, Metacritic scores, release dates, platforms, genres) and a concrete example with ordering. It does not contradict annotations and provides useful detail beyond 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 two sentences plus an example, front-loading the purpose and providing a concrete usage case. Every sentence adds value; there is no redundancy or fluff.

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

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

Given the tool has 6 parameters, 100% schema coverage, and annotations, the description provides a clear overview of functionality and return data. It could mention pagination behavior or rate limit considerations, but the example and schema compensate. Overall, it is sufficiently complete for effective use.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds an example showing how to use query and ordering, and mentions searching by name, genre, or platform, which loosely maps to parameters. While not necessary, the example aids understanding.

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

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

The description clearly states the tool searches the RAWG video game database by name, genre, or platform, which is a specific verb+resource. It distinguishes from sibling tools like get_game (single game lookup) and list_genres/list_platforms (data enumeration).

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

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

The description implies usage for searching games but does not explicitly state when to use this tool versus alternatives (e.g., get_game for specific details, list_genres for genre lists). The example provides practical guidance but lacks direct comparison to siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds: embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), and cap (200K chars with truncation flagging). This provides full behavioral transparency 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 efficiently structured: first sentence defines core purpose, followed by usage guidance, examples, technical details, and pairing. No wasted words; every sentence contributes meaning. It is front-loaded with the key action.

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

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

Despite no output schema, the description fully describes return values: top-N passages with character offsets and similarity scores. It also covers input constraints (cap, truncation) and pairing with sibling tools. For a well-annotated tool, this is complete and self-sufficient.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The tool description enhances with illustrative examples: 'Pass the text you already pulled (e.g. a SEC 10-K body...)' for 'text', and query examples like 'supply-chain risk'. The limit parameter is clarified with default 5 and range. This adds 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 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with fetching. The examples (SEC 10-K, article) make it concrete.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains that it saves context by returning only relevant passages. Also describes pairing with ask_pipeworx_grounded for grounded reasoning.

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 important behavioral details beyond annotations (e.g., OAuth requirement, type-specific params, delivery limits) but the idempotent annotation is contradicted by the description implying each call creates a new subscription.

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?

Well-structured and front-loaded with purpose, each sentence adds value, though slightly verbose for a very detailed 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?

Comprehensively covers all aspects: purpose, requirements, supported types with examples, delivery options with limits and authentication, leaving no obvious gaps despite no output schema.

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

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

With 100% schema coverage, the description enriches parameters with concrete examples and constraints (e.g., phone verification, 10/day cap for SMS), providing significant added value.

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

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

The description clearly states the verb ('Create') and resource ('proactive monitoring subscription'), and distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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 context such as requiring a Pipeworx OAuth account and details on supported types and delivery channels, but does not explicitly state when to avoid using this tool or mention alternatives.

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

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

The description discloses that the tool is read-only, returns example questions with tool invocation details drawn from a live catalog, and has no side effects. This complements the annotations (readOnlyHint, idempotentHint) by adding context about the output format and the fact it's an onboarding aid. 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 informative but somewhat verbose. It lists many example queries and topics, which is helpful but could be trimmed without losing clarity. However, the structure is logical (purpose, when to use, argument explanation, typical use case) and front-loaded with the key intent.

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

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

Given there is no output schema, the description adequately explains what is returned (category-bucketed example questions). It also covers the single parameter, the tool's role among many siblings, and the intended use case. No gaps are apparent for an onboarding tool.

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

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

The schema already provides a description for the 'topic' parameter with default values. The tool description adds further meaning by explaining the purpose (focusing results) and giving example values (finance, pharma, etc.). Since schema coverage is 100%, the description provides incremental 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 uses specific verbs ('returns category-bucketed example questions') and clearly identifies the tool as an onboarding entry point. It distinguishes itself from sibling tools like 'ask_pipeworx' by stating it provides suggestions for what to ask, not answering queries directly.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do' and provides scenarios like 'getting started' or 'what can you do?'. Also gives guidance on when to omit or pass the 'topic' argument, and mentions alternative paths like 'ask_pipeworx' for actual questions.

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

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

Beyond annotations (which already indicate non-destructive), the description adds that the row is deactivated not deleted and historical events remain, providing key behavioral context.

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

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

Two sentences, front-loaded with action and constraints, with zero wasted words.

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

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

Given the simple tool (one required param, no output schema), the description fully covers behavior, ownership, and lifecycle, referencing sibling tools effectively.

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

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

Schema coverage is 100%, so the description adds minimal param info beyond reinforcing that id is from subscribe, meeting the baseline.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id', distinguishing it from sibling tools like subscribe (create) 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?

The description states ownership enforcement ('you can only cancel your own subscriptions') and implies the id comes from subscribe, but does not explicitly list when-not to use or 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 mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral context: it verifies claims via two distinct pipelines (structured SEC data vs. grounded pipeline), returns a specific verdict set, and includes citations. 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 detailed and well-structured, front-loading with examples and then explaining functionality. While every sentence adds value, it could be slightly more concise. Still, it avoids fluff and is easy to scan.

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

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

Given the complexity of claim verification (multiple sources, verdict types, two processing paths), the description covers all essential aspects: input format, behavior for financial vs. other claims, output structure (verdict, value, citation, reasoning), and performance benefit. No output schema exists, but the description suffices.

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

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

Both parameters are fully described in the schema (100% coverage). The description adds meaningful context beyond the schema: the tolerance_pct default, override behavior, and use case for hallucination detection. This adds value without redundancy.

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

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

The description explicitly states the tool's purpose: natural-language claim verification against authoritative sources. It provides example queries and clearly distinguishes between financial and other claims, making its scope unmistakable. It also contrasts with sibling tools by focusing on verification rather than general research or lookups.

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 says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is clear guidance. It also explains the two internal paths. However, it does not explicitly state when not to use this tool (e.g., for open-ended research) or name alternatives, though the sibling list implies differentiation.

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