usgswater

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

Annotations already declare readOnly, openWorld, and idempotent, so the description adds valuable non-redundant context: default free model, BYO key cost implications ('you pay Anthropic directly'), and the exact return structure per model. This goes beyond the safety profile captured in annotations.

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

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

Four dense sentences with front-loaded action. Every sentence earns its place: purpose, default behavior, return format, and use cases. No fluff or repetition of schema details.

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

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

Given the tool has no output schema, the description compensates by specifying per-model return fields ({score, confidence, signals, raw_response}) and a combined view. It also covers cost behavior and default model, which is essential for an agent deciding whether to use it. This is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds confirmation of the default model and that _apiKey enables Anthropic, but it doesn't meaningfully enhance parameter understanding beyond the schema. The return-format info is output semantics, not parameter semantics.

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

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

The description opens with a specific verb 'Probe' and a clear resource ('one or more LLMs'), then states the scoring output (0-100) and use cases. It clearly distinguishes itself from siblings like scan_competitor_ai_presence by focusing on generic visibility scoring across models rather than 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 provides explicit context: default model, when to pass _apiKey, and use-case categories (AI-marketing audits, pre-launch brand checks, competitive monitoring). It doesn't name specific sibling tools as alternatives, but the guidance is sufficient for an agent to decide when to invoke it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: routing to 5,529 tools, returning structured answers with citation URIs, being 'one fast call' that works on every tier, and routing breaking news to live news feeds. 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 front-loaded with a strong directive ('PREFER OVER WEB SEARCH'), followed by domain list, trigger phrases, examples, and alternative guidance. It is structured and informative, though slightly verbose in places; each sentence generally earns its place.

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

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

For an open-world tool with no output schema, the description covers domain scope, trigger phrases, return format (citation URIs), and alternative tools. It does not mention error cases or edge behavior, but the simple single-parameter schema and strong annotations make the description 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%, with the 'question' parameter and five aliases fully described. The description doesn't add syntax or format details beyond the schema, but it does reinforce that input is a natural-language question. This is baseline 3 for full schema coverage.

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

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

The description states a specific verb and resource: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It clearly distinguishes from siblings like ask_pipeworx_grounded and deep_research by noting when to use those instead.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions,' lists trigger phrases like 'what is', 'look up', 'find', and names alternatives: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the bar is lower. The description adds valuable behavioral context: candidate routing improvements are 'enabled live whenever one is under test', it currently matches ask_pipeworx exactly, and it 'Falls back to nothing — this IS a full working router'. This discloses the experimental, evolving nature and clarifies it is not a stub.

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

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

The description is three sentences, front-loaded with the tool's identity and purpose, and each sentence delivers relevant information about beta status, current behavior, usage, and fallback. There is no extraneous content, making it concise and well-structured.

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

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

Given the complexity of a universal router with 5,529 tools and no output schema, the description covers essential context: what it is, when to use it, current state, and differences from the stable version. It references the response shape via ask_pipeworx rather than detailing it, which is acceptable given the sibling relationship but leaves a slight gap for agents unfamiliar with ask_pipeworx.

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

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

The input schema fully documents the 'question' parameter and five aliases with descriptions, achieving 100% schema coverage. The tool description adds no additional parameter semantics, so the baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states it is a 'Beta version of ask_pipeworx: identical universal router' with 'same 5,529 tools, same arguments, same response shape', identifying it as a routing tool. It distinguishes itself from siblings by noting it is the experimental edge with candidate routing improvements, making its purpose and scope specific.

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 provides when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the alternative (stable ask_pipeworx) and explains that results are compared with the stable router to decide merges, giving clear 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?

The description goes well beyond the annotations (readOnlyHint, openWorldHint, etc.) by detailing the exact return structure on success and the refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also discloses the extra LLM call cost, which is important behavioral context. 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 information-dense and structured, with the main purpose stated upfront and then expanded with mechanics, output format, usage rules, and cost. It is longer than the simplest descriptions but every sentence conveys necessary information, earning a 4 rather than a 5.

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

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

Given the complexity of the tool and the lack of an output schema, the description fully covers return values, refusal behavior, and cost implications. It provides enough context for an agent to use the tool correctly and understand what to expect, making it complete for its intended 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%, with all parameters being aliases for 'question' and clearly described in the schema. The tool description does not add additional parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a 'Hallucination-resistant answer mode for high-stakes reads' and explains its mechanism: it routes like ask_pipeworx, fetches data, and extracts answers only from the tool result. This distinguishes it from sibling tools like ask_pipeworx and ask_pipeworx_beta by emphasizing grounded, evidence-based answers. The verb+resource+scope is specific and actionable.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' This clearly states when to use and when to use an alternative, making the selection decision straightforward.

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 extensive behavioral traits beyond the annotations. It details the resolver contract (match confidence, alternatives, suggestions), the parent-event extractor, news fallback behavior (_fallback_attempted, retry_after_sec), safety short-circuiting (status:"low_confidence_match"), closed-market handling, wide-spread illiquidity warning, and resolution-rule risk parsing. This goes far beyond the read-only/open-world/idempotent hints, giving the agent a comprehensive understanding of edge cases and internal logic. No contradiction with annotations.

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

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

The description is long and detailed but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is front-loaded with purpose and usage guidelines. While the length is justified by the tool's complexity, it is slightly verbose; a more concise version could maintain the same value. Thus a 4 rather than 5.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It explains response shapes for market, analysis, and evidence; covers resolver confidence and suggestions; describes parent_event for partitioned bets; details news fallback fields; explains safety mechanisms for low-confidence and closed markets; and warns about wide spreads and cancellation-rule risk. It gives agents everything needed to use the tool safely and interpret results correctly.

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

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

The input schema has 100% description coverage for all three parameters: market (slug/URL/question text), depth (quick/thorough), and include_raw (with default and size implications). The description reinforces market input formats with examples and adds fan-out examples, but these are more about tool behavior than parameter meaning. Since the schema already documents the parameters, the description adds only marginal extra value, matching the 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), the resource (Polymarket bet), and the mechanism (pull Pipeworx data), and further details the workflow: resolves the market, classifies the bet, fans out to category-specific data packs, and returns an evidence packet plus market-vs-model comparison. This distinguishes it from sibling tools like polymarket_edges or validate_claim, which serve different purposes.

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

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

The description gives explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context for when to invoke the tool. However, it does not explicitly state when NOT to use it or mention alternative sibling tools, which would warrant a 5. The guidance is sufficient but lacks 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 establish read-only, idempotent behavior; the description adds substantial context: SEC EDGAR/XBRL data for companies, FAERS/FDA/trial counts for drugs, off-calendar fiscal year handling, sorting by primary metric, and citation URIs in return. No contradictions with annotations.

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

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

The description is dense but front-loaded with trigger phrases and includes all critical information. Each sentence contributes either usage guidance, data scope, or output behavior, avoiding fluff. It is somewhat long but appropriately so for a tool with dual entity types and distinct data sources.

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

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

Despite no output schema, the description specifies what is returned (paired data + pipeworx:// citation URIs), how results are sorted, and the data domains for both entity types. It also addresses edge cases like off-calendar fiscal years, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds operational meaning: type='company' vs 'drug' determines the data source and fields, and values accept tickers/CIKs or drug names. This goes beyond the schema's basic text descriptions by explaining the consequences of parameter choices.

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 a side-by-side comparison of 2–5 companies or drugs in one parallel call, using explicit trigger phrases like 'X vs Y' and 'rank these companies'. It distinguishes itself from sequential single-entity lookups and specifies the data pulled for each entity type, making the tool's purpose unambiguous.

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

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

It explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' offering direct selection guidance. Examples of user intents ('X vs Y', 'which is bigger') clarify when to apply. The description's strong preference directive and trigger examples provide clear 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?

Discloses rich behaviors beyond annotations: account requirements, latency expectations, gaps[] and contradictions[] fields, semantic excerpting, and the always-fetchable pipeworx:// citation URI. This goes well beyond the readOnly/openWorld/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?

Every sentence earns its place: auth, alternative tools, data source types, orchestration mechanics, output details, depth behavior, and latency. It's dense, front-loaded with account requirements, and appropriately sized for the tool's complexity.

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

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

With no output schema, the description compensates by detailing the findings packet (evidence, confidence, source, fetched_at, citation, hop, gaps, contradictions) and covers edge cases (news topics yield empty gaps, latency). It's highly complete for a complex tool.

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

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

While schema covers both parameters, the description adds crucial depth semantics (quick=3 facets, standard=5 with gap recovery, thorough=8 paid with iterative hop) and explains the natural-language question input, adding meaning beyond the schema.

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

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

The description clearly identifies the tool as performing 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly contrasts with open-web search and ask_pipeworx, making its purpose distinct from siblings.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when not to: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', plus a fallback for signed-out users.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds meaningful context about return format ('full input schemas (with curated examples)'), direct callability ('ready to call directly, no second schema lookup needed'), and the recommendation to 'Call this FIRST.' This goes beyond annotation information without contradicting it.

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 structured in three sentences, front-loading the core purpose, then usage guidance, then output details. The long list of domains is slightly verbose but serves to clarify the tool's coverage. Overall, every sentence contributes 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, the description compensates by explaining the return value ('names, descriptions, and full input schemas') and that results are directly callable. It covers purpose, usage timing, and return format, making it complete for a discovery tool. The only minor gap is not detailing behaviors like case sensitivity or error handling, but these are not critical here.

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

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

Schema coverage is 100%, with all parameters and aliases documented. The description reinforces 'query' as a natural language description and 'limit' via 'top-N,' but it does not add substantive parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task,' clearly stating the verb and resource. It enumerates specific domains (SEC filings, FDA drugs, FRED, etc.) and distinguishes this meta-tool from sibling data-access tools by highlighting that it returns schemas ready to call.

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

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

It explicitly states 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also implies a when-not-to-use ('not just one answer'), but it does not name specific sibling tools as alternatives, so it's not a 5.

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

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

Even with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds significant behavioral context: it fans out across multiple sources in parallel, mentions that the USPTO PatentsView API sunset May 2025 and soft-fails until reactivated, describes a GDELT→GNews fallback for news, and specifies the exact return fields. This goes well beyond what annotations provide.

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

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

The description is dense and front-loaded with example queries, which helps the agent recognize invocation patterns. It packs in many important details (sources, return fields, fallbacks, limitations) without wasted sentences. The list of paraphrases is slightly redundant but not excessive, and the overall structure flows logically from usage to behavior to input constraints.

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

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

With no output schema, the description fully responsible for describing return values, and it does: it lists cik + company_name, recent_filings with URIs, fundamentals (LATEST 10-K), patents, news mentions, and LEI. It also covers caveats like the patents sunset and name unsupported, as well as the parallel execution model. This is complete for a multi-source tool.

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

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

The input schema already covers both parameters thoroughly (type describes the enum, value explains ticker vs. CIK and the 'names not supported' note). The description repeats this information without adding new parameter-specific semantics beyond example queries. With schema coverage at 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It uses a specific verb with a defined resource and scope. It also distinguishes itself from siblings by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and by directing name-based lookups to resolve_entity.

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

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

The description explicitly tells when to use this tool ('when the user asks for a holistic view') and when not to ('names not supported — use resolve_entity first'). It also names the alternative approach (chaining single-pack lookups) and explains why this tool is preferred, providing clear context and exclusion criteria.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering safety and idempotency. The description adds the intent of 'clearing sensitive data' but does not elaborate on error handling or non-existent keys. Given the annotations cover the core behavioral traits, this is acceptable.

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

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

Three sentences, each earning its place: the operation, the usage triggers, and the related tools. No redundant phrasing or extra details. It is front-loaded with the core 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?

For a single-parameter destructive operation with rich annotations, the description covers purpose, usage, and related tools adequately. No output schema is needed for a delete operation, and the annotations fill the safety profile. The tool is simple, and the description is complete.

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

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

Schema coverage is 100%: the sole parameter key is described with 'Memory key to delete.' The tool description's 'by key' reiterates this without adding new semantics. The baseline of 3 is appropriate since the schema already carries all parameter meaning.

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

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

The description opens with a specific verb+resource: 'Delete a previously stored memory by key.' It clearly distinguishes from siblings like remember and recall, which are explicitly mentioned, making the purpose unmistakable.

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

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

It provides explicit when-to-use conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also names complementary tools ('Pair with remember and recall'), giving the agent clear workflow context. No exclusions are needed since this is the only deletion tool for memories.

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

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

Annotations already declare readOnlyHint and non-destructive behavior, and the description supplements this by explaining the internal process: fetches the page, extracts title/description/links, and outputs a text blob. This adds meaningful behavioral context beyond annotations, though it omits potential edge cases like failed fetches or rate limits.

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

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

The description is three sentences: purpose, process, and use cases. It is efficiently organized and free of filler, though adjectives like 'production-ready' and 'cleanly' are mildly promotional. Overall, it earns its place without waste.

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

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

The description covers input (URL), output (standard llms.txt markdown blob), and use cases, which is sufficient for a 2-parameter read-only tool. It does not explain error scenarios or max_links behavior, but with strong schema coverage and annotations, this 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% for both parameters, so the description need not elaborate on them. It does not go beyond the schema (e.g., no mention of max_links or URL format), making the baseline score of 3 appropriate.

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

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

The description uses a specific verb ('generate') and names the exact resource ('llms.txt file'), while clearly stating what it does: fetches a URL, extracts metadata, and emits the standard markdown format. It differentiates from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

The 'Useful for' section provides clear contexts (client indexing, personal project drafting, competitor auditing), giving solid usage guidance. However, it does not explicitly mention when NOT to use it or name alternative sibling tools, so it falls short of full exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds behavioral context by specifying the return fields (id, type, params, etc.) and the default active-only filtering. It doesn't contradict annotations, and the added detail is valuable beyond what annotations provide.

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

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

The description is two sentences, with the first sentence covering purpose and return format, and the second providing use-case guidance. Every word earns its place; there is no fluff or redundancy.

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

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

Given the tool's simplicity (1 optional param, no output schema, strong annotations), the description provides sufficient contextual completeness. It lists return fields, clarifies scope, and explains when to use it. No critical information is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% for the single parameter (include_inactive), and the schema description already explains its meaning well. The tool description doesn't add much beyond the schema, only implicitly referencing active status. Since the schema carries the burden, the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions.' It specifies the verb (list), resource (subscriptions), and scope (caller's active). It differentiates from sibling tools like subscribe and unsubscribe by focusing on listing. The return fields are enumerated, leaving no ambiguity.

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

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

The description gives explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool (before subscribing or unsubscribing). While it doesn't explicitly state when not to use it, the context makes the purpose clear relative 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?

The description adds critical behavioral context beyond annotations: rate limiting ('Rate-limited to 5 per identifier per day'), free usage, claim_token return behavior, and the warning not to paste end-user prompts. It also explains that feedback is read daily and influences the roadmap. No contradictions with annotations.

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

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

The description is longer than average but every sentence earns its place, covering purpose, use cases, exclusions, token usage, and operational details. It is front-loaded with purpose and flows logically. Slightly verbose but appropriate for the tool's complexity.

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

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

With 4 params, no required, 100% schema coverage, and no output schema, the description fully equips an agent to select and invoke the tool correctly. It explains the feedback categories, claim_token lifecycle, and constraints, leaving no significant gaps for correct usage.

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 value by clarifying message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and explaining claim_token usage, which complements but does not merely repeat the schema.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly scopes the tool to feedback about Pipeworx tools, distinguishing it from siblings like ask_pipeworx (which asks questions) and other MCP server tools.

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

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

Explicit when-to-use is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives when-not and alternatives: 'if the tool came from a different MCP server... file it with that server instead.' This is exemplary.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond this: it states the data is self-aggregating from CF analytics-engine, contains no PII, and is cached for 5min-1h. This gives the agent important information about freshness, privacy, and provenance not present in 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: the first sentence states purpose, the second lists outputs, then three numbered use cases, and a final sentence on data source/caching. Every sentence adds distinct value, with no fluff or repetition, and the most critical information is front-loaded.

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

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

Despite having no output schema, the description explains exactly what the agent can expect: 'top tools, top packs, and total call volume' and 'just (pack, tool, count)'. It also covers the window parameter, data provenance, privacy, and caching. For a simple, read-only trending tool, this is complete and leaves no significant gaps.

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

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

The schema covers 100% of the parameter descriptions, including a detailed explanation of the window enum ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description merely mentions the window options without adding new semantic detail, so the baseline score of 3 applies per the rubric.

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

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

The description opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now' and immediately specifies the outputs: top tools, top packs, and total call volume over a recent window. This distinguishes it from sibling tools like ask_pipeworx (question answering) and discover_tools (discovery), with no ambiguity about its function.

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

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

The description provides three explicit use cases with bullet points, such as discovering hot data sources and confirming a canonical tool before asking a question. This gives clear context for when to use it, though it does not explicitly name alternatives or state when not to use it, which prevents a 5.

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

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

The description discloses key behaviors that go beyond the readOnlyHint/idempotentHint annotations, such as the partition filter for placeholder slugs, the semantic anchor threshold (Jaccard ≥ 0.30), and the fill-check logic explaining when a signal is not tradeable. It also states the response structure, providing full transparency about what the tool returns. No contradiction with annotations.

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

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

The description is dense but well-organized using CAPS-labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a clear front-loaded summary sentence. Every sentence contributes new information, and the length is justified by the tool's complexity.

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

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

Despite lacking an output schema, the description explicitly lists the response fields (opportunities[], partition_check{}, fill check details), covering what an agent needs to understand the return value. It also explains the edge case of realizable_edge_pp ≤ 0 and directs to polymarket_fill_risk for custom sizing, making the tool self-contained.

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

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

Both parameters (event and topic) already have detailed schema descriptions covering 100% of the parameters. The description substantially enriches the semantics by explaining exactly what each mode does—e.g., 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check' for event, and the cross-event search behavior for topic. It also adds the semantic anchor and partition filter context that are not present in the schema.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It further distinguishes the two input modes (event and topic) and the no-arg trending scan, making it distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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 for when to use each mode: no args for a trending scan, `event` for a specific market, and `topic` for cross-event scanning. It also notes limitations ('Cross-event mode catches ... patterns that single-event misses') and points to an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk').

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses a wealth of behavioral traits: the exact model formulas (lognormal barrier from 90d FRED log-returns, GDELT 7d/21d ratio), Kelly caps at 0.25, the 'Market moved X.Xpp in 24h' warning, slippage assumptions, the rare-by-design nature of concentrated longshots, and the 1h KV-level caching. It also transparently flags the Fed signal unreliability, giving the agent an honest picture of limitations.

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

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

The description is long but highly structured and front-loaded with the core purpose. It uses clear section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) to organize dense information. Each sentence carries substantive value, and the complexity of the tool justifies the length. It does not waste words on 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's complexity, the description is remarkably complete. It covers the three model segments, the tradeable-edge knobs, the response structure with by_segment and diagnostics, the cache behavior, and important caveats (e.g., Fed signal reliability, 24h-move warning). Since there is no output schema, the description explicitly enumerates response top-level fields, making it fully self-contained.

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

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

The input schema already provides 100% coverage with descriptions for all 9 parameters. The description adds meaningful context beyond that: it explains min_liquidity and max_spread_pp as 'tradeable-edge filters' that drop opportunities where the edge isn't realizable, and it adds critical nuance for min_partition_leg_kelly (partition arbs always return kelly_fraction_half=0 at the parent level, so min_kelly never filters them). It also clarifies that min_edge_pp is evaluated net of slippage.

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+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also details the three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and the five model families, which clearly distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides exclusions (Fed bets are excluded from ranking due to unreliable signal) and explains when to adjust tradeable-edge knobs (e.g., set max_spread_pp to 2 for tight books, min_liquidity to 5000 to drop thin-book opportunities). While it doesn't directly compare to alternatives by name, 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?

The description discloses several important behaviors: data comes from daily snapshots, history limited by 60-day TTL and snapshot enablement date, decay computed from daily closes (not intraday), and gaps in snapshot_dates mean no scan occurred. This information goes well beyond the annotations' readOnly/idempotent hints, providing the agent with a thorough understanding of data semantics and limitations.

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

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

The description is dense but well-structured, front-loading the core purpose and then covering arguments, response format, and limitations. While somewhat long, each section adds necessary detail, and the logical flow makes 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?

With no output schema, the description thoroughly explains the response structure: tracked[] with time-series and trend, expired[] with lifespan, and snapshot_dates[] with gap meaning. It also covers computational basis and data availability limits, making it complete for an agent to use correctly.

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

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

The schema already documents both parameters with clear descriptions and defaults ('Lookback in days (default 14, clamp 2-30)' and 'Which polymarket_edges window family to read snapshots for: 24hr | 1wk | 1mo'). The description's 'Args' section largely repeats this information, adding no new parameter-specific semantics beyond what the schema provides.

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

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

The description explicitly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and poses a specific question it answers. This clearly differentiates it from sibling tools like polymarket_edges (which likely provides current edges) by focusing on historical persistence and trend analysis.

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

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

The description provides clear context by explaining that 'a fresh wide edge and a 3-week-old wide edge are different trades,' implying this tool is used when evaluating edge age before trading. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions.

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

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

Annotations already mark this as read-only/idempotent, but the description goes far beyond: it details exactly what is computed (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd), what the verdict means, and the specific return fields for basket mode. It discloses the risk of partial fills converting an arb into an unhedged position—a key behavioral trait not captured in annotations. No contradictions with annotations.

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

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

The description is long but packed with essential information for a complex tool. It is front-loaded with the core purpose and then organizes details by mode. Every sentence adds value; however, it could be slightly more scannable with bullet points for the two modes. Still, it earns a high score for density and 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?

Given the tool has 4 parameters, dual modes, no output schema, and important risk implications, the description is remarkably complete. It enumerates the return fields, explains the verdict categories, and warns about partial-fill dangers. It also provides usage thresholds and links to related tools. There is no significant missing context.

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

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

Schema description coverage is 100%, but the description adds significant contextual meaning beyond the schema. It clarifies the dual-mode interpretation of size_usd (max spend on buys, target proceeds on sells, vs settlement notional for basket), explains default side selection behavior, and defines what 'market' vs 'event' means. This goes well above the structured 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 states a precise purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by stating it should be used before them. The verb 'check' plus resources (market/event, order-book depth) make the function unmistakable.

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

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

This is exemplary. The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides the reasoning: theoretical overround on thin books is not capturable, and partial basket fills cause unhedged directional risk. This gives clear when-to-use and which alternatives to prefer.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description goes well beyond that by detailing compatibility_warning conditions, temporal_alignment meaning, skipped_cross_type/subtype semantics, and the exact spread formula (Kalshi - Polymarket). It also discloses real-world caveats about pre-mapped topics not being tradeable, offering rich 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 correctly front-loaded with the core purpose and uses bold section labels (TWO MODES, RESPONSE, SAFETY FIELDS) for structure. However, the opening sentence about participant pools is somewhat verbose and could be trimmed without losing essential information.

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 three optional parameters and no output schema, the description is exceptionally complete. It covers input selection, output fields (leg-by-leg prices, spread in pp, safety fields), warning conditions, temporal alignment, and usage limitations. This is sufficient for an agent to decide when and how to call the tool correctly.

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

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

Although the schema covers 100% of parameters, the description adds significant meaning by listing the full set of valid topic shortcuts and clarifying that explicit tickers override the topic-mapped side. It includes concrete examples like 'KXFED-26OCT' and 'fed-decision-in-june-825', which are absent from the schema.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It differentiates from siblings by focusing on comparing two venues and explicitly describes two modes (topic shortcuts and explicit tickers), making its purpose unambiguous and specific.

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?

Usage is well contextualized: the description explains when to use topic shortcuts vs explicit tickers and warns that most pre-mapped topics currently return compatibility_warning, implying they may not be tradeable. However, it does not name alternative sibling tools or explicitly state when to prefer a different tool, so it misses the 'alternatives' criterion by a small margin.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: the data is scoped to the agent's identifier (anonymous IP, BYO key hash, or account ID), and omitting the key lists all saved keys. It does not describe behavior on missing keys or return format, but given annotations, this is sufficient.

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

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

The description is three sentences, front-loaded with the core action, and every sentence adds value: purpose, usage guidance, and scope/alternatives. No redundancy or unnecessary verbiage.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage timing, scope, and relationships to sibling tools. It implies return values ('Retrieve a value' / 'list all saved keys') and does not need to explain an output schema. Minor gaps like error behavior are acceptable 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?

The schema description covers 100% of the parameter ('Memory key to retrieve (omit to list all keys)'), so the baseline is 3. The description repeats the omit behavior and provides examples of key values, adding some semantic context about what keys represent, but it does not add new parameter-level detail.

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

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

The description states a specific verb ('Retrieve' / 'list') and resource ('a value previously saved via remember' / 'all saved keys'), clearly distinguishing it from sibling tools like remember and forget. It also provides concrete examples ('user's target ticker, an address, prior research notes'), making the purpose unambiguous.

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

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

The description explicitly says 'Use to look up context the agent stored earlier...' and names the complementary tools ('Pair with remember to save, forget to delete'), giving clear guidance on when to use this tool vs alternatives. The scope note ('Scoped to your identifier') adds context about its applicability.

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 a write side effect ('Set mark_read:true to flag returned events read so the next call only shows newer ones'), which directly contradicts the annotation readOnlyHint:true. This is a serious inconsistency that undermines trust in the tool's safety profile.

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

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

The description is front-loaded with a clear purpose and each sentence adds value—return payload details, filtering options, mark_read side effect, and alternative URL. No filler or redundancy.

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

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

Despite lacking an output schema, the description covers the return format (source, citation_uri, raw payload) and explains all key behaviors. It is complete for a tool with 5 optional parameters and nuanced state-changing semantics.

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

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

While the schema already covers all 5 parameters, the description adds meaningful context: examples (type 'sec_8k'), clarifies 'since' as ISO timestamp, and explains the effect of mark_read on future calls. This goes beyond mere schema repetition.

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 ('Pull') and resource ('subscription feed') to clearly state the tool's function. It distinguishes from siblings like list_subscriptions by focusing on fired alerts from the evaluator and the persisted feed.

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

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

The description gives clear context: mentions polling workability and provides an alternative access method (URL) for scripts/dashboards. However, it does not explicitly state when not to use this tool or compare it to siblings like recent_changes.

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

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

Annotations already indicate read-only/idempotent behavior, and the description adds substantial detail: multi-source fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to PatentsView sunset, and supported `since` formats. It also discloses the return shape (changes[], total_changes, pipeworx:// URIs).

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

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

The description is dense and front-loaded with user-phrase examples, but it is long. All sentences carry functional information so nothing is wasted, and the length is justified by the tool's multi-source complexity.

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

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

With no output schema, the description compensates by documenting the multi-source pipeline, fallback behavior, failure mode (USPTO soft-fail), return contract, and citation URIs. This is complete for a complex read-only 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 covers all 3 parameters at 100%, and the description adds actionable semantic detail—especially for `since` (ISO or relative shorthand plus recommended '30d'/'1m')—and clarifies `value` accepts ticker or zero-padded CIK. This is slightly more than the schema provides, but not enough to justify a 5.

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?

Describes a change feed for companies over time windows with specific verbs ('fans out', 'Returns') and clearly distinguishes itself from the sibling entity_profile tool ('Use entity_profile instead...'). The resource and scope are explicit and actionable.

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?

Gives explicit when-to-use triggers with natural-language examples ('What's new with X'...) and names an alternative (entity_profile) for the static-profile use case. Also explains fallback routing for news sources, which helps decide when this tool is appropriate.

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

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

Annotations already signal idempotence and non-destructive behavior; the description adds scoping by identifier and retention differences between authenticated and anonymous sessions. These are material behavioral details not present in the annotations, adding significant value 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?

Three dense sentences cover purpose, usage triggers, storage model, persistence behavior, and companion tools without redundancy. Every sentence contributes actionable information, making it highly efficient.

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

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

For a simple two-parameter write tool, the description covers what, when, why, persistence semantics, and relationships with related tools. With annotations covering safety and idempotence, nothing critical is missing.

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

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

Schema description coverage is 100%, with both parameters clearly described and exemplified. The description doesn't add new parameter semantics beyond reinforcing the key-value nature, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb+resource ('Save data the agent will need to reuse later') and clearly distinguishes itself from memory siblings by naming recall and forget as partners. It leaves no ambiguity about the tool's 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?

It states exactly when to use the tool ('when you discover something worth carrying forward') with concrete examples, and gives explicit guidance on companion tools ('Pair with recall to retrieve later, forget to delete'). 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?

Despite strong annotations (readOnly, idempotent, openWorld), the description adds substantial behavioral context: it cascades through multiple endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, labels each identifier with its source, and explicitly lists unresolved identifiers. This goes well beyond the annotations and describes failure behavior and output structure.

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

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

The description is long but every sentence earns its place. It opens with memorable examples, gives a clear directive, and then breaks down supported types with return details and caveats. The structure is front-loaded, and there is no redundant filler or repetition of schema field names.

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

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

There is no output schema, so the description carries full responsibility for explaining return values. It does this thoroughly for both supported types, including ownership data, source labeling, unresolved identifiers, citations, and graceful degradation. It also gives input examples and notes that it replaces multiple manual lookups, giving the agent enough context to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining what each entity type returns (e.g., for company: CIK, ticker, LEI, FIGI with ownership; for drug: RxCUI, ingredient, brand, citation). It also clarifies the value parameter with concrete examples and acceptable formats, enriching the schema's terse 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 starts with a rich set of example queries, clearly stating that the tool resolves user-spoken names to canonical IDs. It explicitly names the resources (CIK, LEI, RxCUI, etc.) and distinguishes itself from sibling tools as the go-to for name-to-ID conversion. The verb 'resolve' plus the supported types makes the purpose unmistakable.

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

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

The description provides explicit guidance ('Use FIRST whenever you have a name but need an ID') and mentions that it replaces manual lookups. However, it does not explicitly state when not to use it or name alternative tools for specific cases, only implying that this is the preferred first step. This is clear but lacks formal 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?

The description discloses internal behavior beyond the annotations: it probes each entity with ai_visibility_check, ranks by score, and returns score/confidence/signal density. It also notes the 'first entry treated as subject' narrative. Annotations already declare safety, so this process detail adds significant value.

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 with front-loaded action, a concrete use-case example, and a clear return-format mention. No filler or redundant wording.

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

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

Given no output schema, the description explains exactly what is returned (ranked list with score, confidence, signal density). Combined with full schema coverage and informative annotations, this is a complete package for a moderately complex tool.

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

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

Schema coverage is 100% with descriptive text for every parameter. The description adds no new parameter meaning beyond the schema; it even repeats the 'first entry treated as subject' line already present in the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific action and resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes from sibling tools like ai_visibility_check by emphasizing multi-entity comparison and ranking, and it explicitly mentions what it 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 clear context for when to use this tool: 'Useful for competitive AI-marketing audits' with an example question. It implies this is for multiple entities vs. single-entity checks but does not explicitly name alternatives or exclusions, so it falls short of a 5.

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

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

Beyond the annotations (readOnly, idempotent), the description reveals important runtime behavior: fan-out across two external services, partial failures degrading gracefully, bundlephobia's first measurement can take 5-30s, and 'sources_failed will list it if it times out'. This is valuable non-obvious information.

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, then gives usage trigger, output structure, ecosystem scope, and failure behavior. Each sentence serves a distinct purpose and there is no filler. Despite its length, it is concise for the complexity it covers.

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

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

For a composite tool with two parameters and no output schema, the description thoroughly explains what is returned (summary block fields, per-advisory details, links, alternative versions) and the failure mode (sources_failed). This is sufficient context for an agent to invoke and interpret results.

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

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

The input schema already describes both parameters with 100% coverage. The description adds no further parameter-specific semantics beyond what the schema provides; however, it confirms 'package' is an npm package name and 'version' is optional, which is already in the schema. Baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Composite "should I add this npm package to my project" check in ONE call' and then details the two data sources (deps.dev, bundlephobia). It clearly distinguishes itself from siblings by stating it is a composite check for npm packages, which is unique among the listed tools.

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

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

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides exclusionary context: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This tells when not to use and directs 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?

The description adds substantial behavioral detail beyond the annotations: it specifies the return format ('top-N passages with character offsets and similarity scores'), the embedding model and matching algorithm ('BGE-base-en embeddings + cosine over 500-char overlapping windows'), and the input cap with truncation behavior ('cap is 200K chars (longer inputs are truncated and flagged)'). Annotations are consistent; 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 purpose, then delivers use case, workflow, technical details, and limits in a compact structure. Every sentence contributes distinct information: purpose, input/output, when to use, sibling relationship, and operational constraints. No filler or redundancy.

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

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

Even without an output schema, the description explains what the agent receives (passages with offsets and similarity scores) and how results can be used ('verify a verbatim quote'). It covers inputs, limits, truncation, and the complementary workflow, making the tool's behavior fully understandable for an agent selecting and invoking it.

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

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

Schema coverage is 100%, with each parameter (text, query, limit) already described with examples and defaults. The description reinforces this by calling text 'the text you already pulled' and query 'natural-language query,' but it does not add meaning beyond what the schema provides. The baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description immediately identifies the tool as 'Semantic search INSIDE a fetched record' with a specific verb and resource, and it distinguishes itself from siblings by describing the workflow with ask_pipeworx_grounded: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This makes the tool's scope and differentiation clear.

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

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

The description gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also names a complementary sibling tool (ask_pipeworx_grounded) and explains how the two fit together, which provides clear context for selecting between 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?

The description goes well beyond annotations by disclosing auth requirements (anonymous/BYO cannot persist), phone verification, SMS cap, webhook auto-disable after 10 failures, and one-time signing secret. It does not contradict the idempotentHint annotation, though it could add more detail on idempotency 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 a single dense paragraph that stays on-topic. Every clause adds value (types, auth, channels). It is longer than the typical description but the complexity justifies it; no 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's complexity (3 params, nested objects, 5 enum types, no output schema), the description covers purpose, return value, auth, all supported types, delivery options, and consumption path. It doesn't mention subscription limits or cancellation, but these are less critical and sibling tools cover them.

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%, providing baseline 3. The description adds concrete examples for each type (e.g., items:['5.02'] = officer change, topic:'fed') and delivery constraints (10/day SMS cap, phone verification), enriching parameter understanding beyond schema text.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream,' a specific verb and resource. It clearly states the return value (new subscription id) and distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description implies usage for ongoing monitoring ('proactive monitoring subscription', 'always on feed') and notes a prerequisite (OAuth account). However, it does not explicitly mention alternatives or when not to use subscribe, such as referencing list_subscriptions for viewing existing subscriptions.

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

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

Annotations already declare readOnly, openWorld, and idempotent. The description adds meaningful behavioral context: it returns 'category-bucketed example questions' with 'the exact tool + argument shape', drawn from a 'live catalog of thousands of tools'. It also notes that calling with no arguments gives the full spread, and passing `topic` focuses the results. This goes beyond the annotations without contradicting them.

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

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

The description is a single dense paragraph that packs in many example queries, the tool's purpose, output details, call instructions, and usage guidance. While every sentence carries useful information, the structure is not optimized for scanning—it could benefit from bullet points or clearer separation of 'what' and 'when'. It is informative but slightly verbose.

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

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

The tool has one optional parameter and no output schema, yet the description fully covers what the tool does, what its output looks like (category-bucketed examples with tool and argument shapes), and when to use it. It even explains the source ('live catalog') and how to narrow results. Given the tool's simplicity, the description is complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% for the one parameter, so the baseline is 3. The description adds value by providing concrete examples ('finance', 'pharma', 'betting') and explaining that the parameter 'focuses' the results, which is not fully explicit in the schema description alone. It also clarifies that omitting the parameter yields a cross-category spread.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape. It includes the verb 'returns' and the resource ('category-bucketed example questions'), and distinguishes itself from siblings by framing itself as the 'FIRST' step to learn how to use meta-tools like ask_pipeworx and entity_profile.

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

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

Explicit guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This establishes when to use the tool and references alternatives (meta-tools), effectively telling the agent to start here before using others. It also explains how to call it with or without the `topic` parameter.

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

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

Goes beyond annotations by disclosing ownership enforcement, deactivation instead of deletion, and the preservation of historical events via recent_alerts. The annotations already indicate idempotency and non-destructiveness, and the description adds meaningful behavioral context without contradicting them.

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

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

Two sentences, front-loaded with the main action, and every sentence earns its place by covering purpose, constraint, and side-effect behavior with zero redundancy.

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

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

For a single-parameter, non-destructive, idempotent cancellation tool, the description covers all essential aspects: what it does, the ownership constraint, the exact effect (deactivation), and how historical events remain accessible. No output schema is needed, and the description is complete for 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?

The schema already provides thorough description of the 'id' parameter (uuid returned by subscribe) with 100% coverage, so the description adds little extra meaning. It merely restates 'by id,' which is inherent to the tool's purpose. Baseline of 3 is appropriate.

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

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

The description opens with 'Cancel a subscription by id,' which is a specific verb plus resource. It clearly distinguishes this from siblings like subscribe, list_subscriptions, and recent_alerts by describing a cancel operation, and further differentiates by noting the row is deactivated rather than deleted.

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

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

Provides clear context: ownership is enforced, so you can only cancel your own subscriptions. It also indirectly guides the user by mentioning recent_alerts for historical events, but it doesn't explicitly state when to use this tool versus alternatives or when not to use it.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the description's value comes from adding non-obvious behavioral details: the two pipeline routes with exact percent-delta math, and the critical distinction between could_not_verify (check did not happen, must not be shown as evidence) and unsupported (no source exists). It also exposes the structured verification_error{stage,detail}, going well beyond annotation hints.

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

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

At roughly 115 words, the description is dense but well-organized, front-loading trigger phrases and a clear purpose before detailing pipelines, return values, and error semantics. Every sentence contributes essential context for a tool with complex behavior, though a slightly tighter presentation would improve readability.

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

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

Without an output schema, the description carries the full burden of explaining return values, and it does so thoroughly by listing the six verdicts and clarifying the two most ambiguous ones. It also covers parameter behavior, routing logic, and efficiency trade-offs, making it self-contained for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for the two parameters, so the baseline is 3; the description adds meaningful nuance by explaining how tolerance_pct overrides the tolerance implied by claim wording, including the 0.5–50 range and a concrete use case ('set 1–2 for hallucination detection'). It also notes the default cap of 5, which the schema does not state.

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

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

The description opens with concrete natural-language examples ('Is it true that…', 'fact check', 'verify the claim that…') and immediately states the tool performs 'natural-language claim verification against authoritative sources'. It names the specific verb+resource ('Validate Claim') and clearly differentiates from sibling research tools (e.g., deep_research, entity_profile) by focusing on verdict-based fact-checking.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and then distinguishes between two routing paths (SEC EDGAR for company-financial claims, grounded pipeline for any other factual claim). It also notes it 'Replaces 4–6 sequential calls', implying it is a consolidated alternative, though it does not list formal exclusions beyond that implicit coverage.

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