Phishtank

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the bar is lower. The description adds valuable behavioral context: default model is free, passing _apiKey incurs Anthropic billing and sends data to api.anthropic.com, and the return format is per-model with score/confidence/signals/raw_response plus a combined view. No contradiction with annotations.

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

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

Three sentences, each earning its place: the first defines the action and scoring, the second covers model/billing options, the third specifies return structure and use cases. Front-loaded and free of filler.

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

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

Given there is no output schema, the description compensates by detailing the return fields (score, confidence, signals, raw_response, combined view), the default model, optional parameters, and example use cases. This is sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with clear descriptions for all 4 parameters, so baseline is 3. The description reinforces that models is optional and _apiKey is only needed for Anthropic, but adds no new syntax or format details 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 states a specific verb ('probe'), resource ('one or more LLMs'), and outcome ('score visibility 0-100 per model'). It distinguishes from siblings by focusing on quantitative visibility scoring rather than general Q&A or research, and lists concrete use cases like AI-marketing audits and pre-launch brand checks.

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

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

The description gives clear context for when to use: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains the default free model versus optional paid Anthropic key. However, it does not name alternative tools or explicitly state when not to use this tool over siblings like scan_competitor_ai_presence.

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 and non-destructive behavior. The description goes beyond this by disclosing that the tool routes to a large number of underlying sources, automatically fills arguments, returns citation URIs, and works on every tier with a single fast call. It does not mention rate limits or error handling, but the added behavioral context is substantive and non-contradictory.

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 is front-loaded with the most critical directive ('PREFER OVER WEB SEARCH') and organized with clear sections. It includes examples and alternatives without wasting words, though it could be trimmed slightly. Every sentence serves a purpose, earning a 4.

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

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

This is a complex router tool with no output schema, so the description carries the full burden of explaining behavior. It covers purpose, usage triggers, examples, alternative tools, citations, and performance characteristics, providing a complete picture for an agent to decide when and how to invoke it. The description is sufficiently comprehensive.

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 describes the 'question' parameter and documents all aliases, so schema coverage is 100%. The description adds some context about what kind of questions to ask and notes that the tool handles argument filling, but it does not provide additional parameter-level semantics beyond what the schema already offers. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: routes questions to one of 5,529 tools across 1,455 verified sources, fills arguments, and returns structured answers with citations. It distinguishes itself from siblings by explicitly naming alternatives like ask_pipeworx_grounded and deep_research, making its scope and unique role unmistakable.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases like 'what is', 'look up', 'find'. It names specific alternatives and the conditions for using them, such as ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad multi-part questions, effectively covering both inclusion 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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context about the beta status, current equivalence to ask_pipeworx, and the comparative evaluation process, which is beyond the annotations' scope.

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

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

Four sentences, each conveying necessary information: beta identity, current state, usage instruction, and functional reassurance. The specific details (5,529 tools, date) are relevant, though slightly verbose; still, the structure is well-organized and front-loaded.

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

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

Given the router's complexity and lack of an output schema, the description is complete: it explains what the tool does, its experimental nature, how to invoke it, and its relationship to the stable version. The mention of identical response shape covers return expectations.

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 provides 100% coverage with descriptions for all six parameters, including aliases. The description only mentions 'same arguments' without adding new semantic details, so the schema adequately handles 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 clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,529 tools. It distinguishes itself from the stable sibling by its experimental nature and current inactive candidate state, making its purpose explicit.

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

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

The description explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and clarifies it is a fully working router rather than a fallback. It contrasts with the stable router, providing clear contextual 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?

The description goes beyond annotations by detailing the grounding mechanism (extracts only from tool result), the extra LLM call cost, and the exact refusal_reason codes. It also clarifies the success return format including evidence and confidence. No contradiction with annotations, which are readOnly/idempotent.

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

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

The description is compact but dense, front-loading the core purpose and then layering details about routing, extraction, refusal behavior, and usage. Every sentence contributes meaningful information, though it could be slightly streamlined given its length.

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

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

Despite no output schema, the description fully specifies the return values for both success and refusal cases, explains the cost trade-off, and provides concrete usage examples (financial verdicts, legal claims). It is complete for the tool's complexity and integration needs.

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

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

Schema coverage is 100% with all six parameters being aliases for 'question.' The description does not add new parameter-level details, but the schema fully documents the natural language question parameter. Baseline of 3 is appropriate since the schema carries the informational 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 clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' that routes like ask_pipeworx but extracts answers only from tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded, evidence-based responses.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on...' and when not to: 'prefer ask_pipeworx for casual lookups.' Names the alternative tool directly, providing clear decision 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, idempotentHint=true, and destructiveHint=false, but the description adds extensive context: parallel fan-out to data sources, resolver contract with market_match_confidence, parent-event extraction, low-confidence short-circuit, closed-market status, wide-spread tradeability, and cancellation-rule risk. No contradictions with annotations; it goes far beyond what annotations convey.

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 extremely detailed and well-organized with sections, but it is overly long (over 500 words). While it front-loads the purpose clearly, it then dives into extensive specifics (e.g., fan-out examples, response field enumerations) that could be trimmed without losing critical value. It's not concise enough for a 5, but it's not vague enough for a 2.

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

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

With no output schema, the description fully compensates by explaining response shapes, evidence keying, resolver contract, parent_event extractor, news fallback fields, safety statuses, and resolution-rule risk. It covers all major aspects a user or agent would need to correctly interpret results for a complex research tool.

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

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

Schema description coverage is 100%, with clear explanations for market (slug/URL/question text), depth (quick/thorough enum), and include_raw (size impact). The description adds minimal additional parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It also provides concrete usage examples ("should I bet on X", "what does the data say about Y") that clearly distinguish it from sibling tools focused on arbitrage, edges, or visibility checks.

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

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

Explicitly states "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'" — clear when-to-use context. However, it does not mention when not to use the tool or name alternative tools, so it misses full exclusion guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds that the tool queries the PhishTank database and returns phish status, verification status, and a details URL, which provides useful behavioral context beyond the safety hints.

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

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

The description is concise, with two tightly worded sentences and a representative example. It front-loads the core purpose and avoids unnecessary details, making it easy for an agent to parse quickly.

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

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

For a simple, read-only lookup tool with one parameter and an output schema, the description fully covers what the agent needs to know: what it does, what it returns, and a usage example. No critical 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?

The schema provides full coverage of the 'url' parameter with a clear description and examples, so the description's example usage adds marginal value. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: checking a URL against the PhishTank database for phishing status. It uses a specific verb ('check') and resource ('URL'), and the example further clarifies usage. This distinguishes it from sibling tools, none of which are phishing-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?

The description provides clear context for when to use the tool (to determine if a URL is a known phishing site). It does not explicitly mention alternatives or exclusions, but given the narrow scope and no obvious overlapping siblings, the usage situation is clear.

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

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

The description adds substantial behavioral context beyond the readOnlyHint annotations, including data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data plus pipeworx:// citation URIs. 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 concise yet dense, packing trigger phrases, usage rules, data-source details, sorting behavior, and return format into a structured paragraph. Every sentence serves a purpose, and the critical 'ALWAYS PREFER' guidance is front-loaded.

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

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

Despite having no output schema, the description fully explains what the tool returns (paired data + citation URIs), covers both entity types, mentions edge cases (off-calendar fiscal years), and clarifies the sort order. It is complete for a tool with this complexity and parameter scope.

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 already provides 100% coverage of both parameters, so the baseline for value-add is 3. The description further enriches meaning by explaining what data each type pulls (company: 10-K revenue, net income, cash, long-term debt; drug: adverse-event counts, FDA approvals, trials) and clarifies the values array semantics with examples, justifying a 4.

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

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

The description explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, with specific trigger phrases ('X vs Y', 'which is bigger'). It distinguishes itself from sequential single-pack lookups, which are the clear alternative.

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

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

The description gives a direct usage directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' and specifies the contexts for company vs. drug types. It clearly tells the agent when to choose this tool over alternative approaches, though it does not name specific sibling 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?

Adds extensive context beyond the annotations: account/paid-tier requirements, grounding in structured sources (not open web), return format (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] for unanswered facets, contradictions[] for standard/thorough, the hop field, citation_uri only when resolvable, semantic excerpting, and latency expectations. No contradiction with annotations; openWorldHint is clarified as structured data only.

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

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

Although long, every sentence earns its place. The description front-loads the critical account requirement and alternative, then flows through purpose, use cases, depth semantics, output format, and performance expectations. Clear formatting with semicolons, parentheses, and structured clauses packs dense information without wasted words, making it 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?

Given no output schema, the description thoroughly explains the return packet: findings with evidence/confidence/source/fetched_at/citations, gaps[], contradictions[], hop field, and citation_uri resolvability. It also covers use cases, exclusions (breaking news), account requirements, depth variants, latency, and excerpting behavior, making it complete for an agent to select and invoke the tool correctly.

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

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

The schema provides 100% coverage for both parameters with detailed descriptions of depth levels and question semantics. The description adds the paid-plan requirement for depth:'thorough' and clarifies the behavior of each depth level (e.g., re-angles gaps, chases leads), going beyond the schema's enum labels to enrich the parameter meaning slightly.

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 performs grounded multi-source research across 1,455 structured data sources, decomposing questions into facets and routing to 5,529 tools in parallel. It highlights the 'findings packet' output and explicitly distinguishes itself from open-web search and from ask_pipeworx, making the purpose highly specific and differentiating.

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 it is best for broad/multi-part questions over structured data and directs users to ask_pipeworx for single lookups or breaking/current-news topics. It also provides an alternative if not signed in (use ask_pipeworx instead), covering when-to-use and when-not-to-use with named alternatives.

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

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

Annotations already cover read-only, idempotent, and non-destructive hints. The description supplements this by disclosing the output behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This adds valuable context about result format and readiness for direct invocation.

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 ('Find tools...') and is reasonably concise. The domain list is long but serves as useful scoping for an agent. Every sentence earns its place: purpose, usage, return format, and call-first guidance. Slightly longer than ideal but justified.

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

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

Given no output schema, the description adequately explains what is returned (top-N tools with schemas), when to use it, and how it behaves. It covers the necessary operational context for an agent to decide and invoke correctly. No critical gaps such as error handling or prerequisites are needed for this simple discovery tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond the schema. It mentions 'describing the data or task' which aligns with the 'query' parameter, but doesn't clarify the 'limit' or alias behavior beyond what the schema already provides.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It specifies the resource (tools) and the action (find/discover), and distinguishes itself from siblings by acting as a meta-tool that returns tool schemas. The list of domains reinforces scope and differentiates from research tools like deep_research or check_url.

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 when you need to browse, search, look up, or discover what tools exist for [domains]' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This also implies when not to use it (when you already have a specific tool), providing clear decision boundaries.

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, so the bar for added value is raised. The description goes beyond by disclosing the external data sources fanned out (SEC EDGAR, XBRL, USPTO, news, GLEIF), the fallback chain (GDELT→GNews), and a known service sunset (USPTO PatentsView API soft-fails). This is rich behavioral context that helps the agent set expectations.

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 but well structured: it opens with user-intent examples, states the core function, lists return sections, and closes with input format and a fallback reference. Every sentence contributes useful information, though the long chain of examples makes it slightly heavier than necessary. It is front-loaded and efficient enough to earn a 4.

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

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

This is a complex tool with no output schema, so the description carries the burden of explaining what the agent will get back. It covers the return fields (CIK, filings, fundamentals, patents, news, LEI), mentions the single-call parallel fan-out, and addresses edge cases (names not supported, patents soft-fail). This is a complete and self-sufficient description 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 description coverage is 100% with both parameters fully described: type ('company') and value (ticker or zero-padded CIK, names not supported). The description repeats this same information with examples ('Pass ticker "AAPL" or zero-padded CIK "0000320193"') without adding any new semantic detail. Baseline 3 is appropriate when the schema already does the heavy lifting.

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

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

The description clearly states 'full cross-source profile of a US public company in ONE parallel call' and enumerates what it returns (CIK, filings, fundamentals, patents, news, LEI). It distinguishes from sibling tools by explicitly telling the agent to prefer this over chaining single-pack lookups and to use resolve_entity when only a name is available.

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

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

The description provides explicit when-to-use guidance ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'), gives concrete user-intent examples ('Tell me about X' / 'research Acme'), and states the prerequisite for name-only inputs (use resolve_entity first). It also clarifies limitations like names not being supported.

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 destructiveHint=true and readOnlyHint=false. The description adds behavioral context by specifying the deletion targets ('previously stored memory') and the purpose (clearing stale or sensitive data), going beyond the annotation hints.

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

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

Two sentences; first delivers the core function, second provides usage context and related tools. No redundancy, well-structured for quick comprehension.

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 one-parameter tool with destructive annotations, the description covers function, usage timing, and related tools. No output schema is needed; the description fully complements the schema and annotations.

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

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

Schema coverage is 100%, with the 'key' parameter described as 'Memory key to delete.' The description restates 'by key' but does not add new details about key format, behavior for missing keys, or edge cases. 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 'Delete a previously stored memory by key,' which clearly states the verb (delete), resource (memory), and identifying mechanism (key). This distinguishes it from sibling tools like `remember` and `recall`.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also names related tools with 'Pair with remember and recall,' providing direct alternative guidance.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, and the description adds meaningful behavioral context: it fetches the page, extracts title/description/key links, and emits a standard markdown blob ready for deployment. This discloses the process, network dependency, and output format beyond the annotations, with 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 three sentences with the main purpose front-loaded in the first sentence. It explains process, output, and use cases without redundancy, every sentence earning its place.

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

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

For a simple two-param read-only tool, the description covers the function, process, output format, and practical use cases. Despite no output schema, it specifies the output as a single text blob in llms.txt markdown, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% (both url and max_links have detailed descriptions), so the baseline is 3. The description adds no specific parameter semantics beyond what the schema already provides, so it stays at baseline.

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

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

The description opens with 'Generate a production-ready llms.txt file for any URL', which states the exact action, resource, and input. It further details the process (fetches, extracts title/description/key links) and clearly distinguishes the tool from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on generating the llms.txt artifact.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context on when to use. It doesn't explicitly name alternatives or exclusion criteria, but the use cases are specific enough to guide selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds useful behavior details by listing the exact return fields and implying that cancelled subscriptions are excluded by default (consistent with the include_inactive parameter).

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

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

The description is two sentences: the first states exactly what the tool does and what it returns, the second gives practical use cases. It is compact, front-loaded, and every sentence earns its place.

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

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

The description is complete for this simple tool. It lists all return fields, covers the default exclusion of inactive subscriptions, and provides real-world usage context. Even without an output schema, the return fields are documented in the description itself.

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 description for include_inactive, so the description does not add much beyond what is already in the schema. 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 verb 'List' and the resource 'subscriptions', scoped to the caller's active subscriptions. It also distinguishes from sibling tools like subscribe/unsubscribe by specifying the read-only review purpose.

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

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

The description gives explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for when to use the tool, though it does not explicitly state 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 only state readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description goes far beyond by disclosing the claim_token workflow, the rate limit of 5/day per identifier, that it's free and doesn't count against quota, and that the team reads digests daily. This is substantial behavioral context not derivable from 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 dense with valuable information; every sentence earns its place. It front-loads the purpose and then covers use cases, exclusions, token flow, and operational details. However, it is a single run-on paragraph; formatting with line breaks or bullets would improve scannability, so it doesn't get 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 tool's complexity (feedback submission vs. claim_token checking) and no output schema, the description covers return values, rate limits, quota, scope, and follow-up behavior. It fully explains the claimed_token mechanism and the types of feedback, making the tool predictable without any additional documentation.

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

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

The input schema already gives rich descriptions for all four parameters, including enum meanings and claim_token behavior (100% coverage). The description adds extra semantics for the message parameter: don't paste user prompts, describe in terms of Pipeworx tools/packs. While not a huge lift, it does improve over schema-only understanding.

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

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

The description opens with a clear action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb and resource, then enumerates feedback categories (bug, feature, data_gap, praise), which fully defines the tool's scope. It also distinguishes from sibling research tools by explicitly limiting to feedback about Pipeworx's own connection.

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 guidance: for bugs (wrong/stale data), features, data gaps, or praise. It also provides an exclusion: do not report tools from other MCP servers; file those elsewhere. This directly addresses alternatives and boundaries, making it a model example of usage guidance.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context: data derives from CF analytics-engine, no PII is included, the output is (pack, tool, count), and caching depends on the window (5min-1h). 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 well-structured: a concise purpose statement, a numbered 'useful for' list, and a final note on data provenance and caching. Each sentence adds value without fluff.

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

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

For a low-complexity tool with one optional parameter and no output schema, the description thoroughly covers the output shape (pack, tool, count), the available time windows, and the use cases. It gives an agent enough 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% and the schema already describes the window parameter with enum values and meaning. The description repeats the options and adds a caching hint, but that is more behavioral than semantic. 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 it returns top tools, top packs, and total call volume over a selectable window. The opening phrase 'What other AI agents are calling on Pipeworx right now' gives a specific, distinct purpose that differentiates it from sibling tools like discover_tools.

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

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

It provides three explicit use cases: discovering hot data sources, confirming a canonical tool, and checking alignment with agent needs. This gives clear when-to-use context, but it does not explicitly mention alternatives or when not to use the tool.

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

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

Beyond the readOnly/idempotent annotations, the description discloses nuanced behavior including the fill check ('realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it'), semantic similarity thresholds, and placeholder filtering.

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

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

Though lengthy, the description is front-loaded with purpose and structured via labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), with each sentence adding operational detail—no filler.

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

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

Given the tool's complexity and no output schema, the description covers invocation modes, filters, response fields, failure conditions, and cross-references to related tools, making it self-sufficient.

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

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

Both event and topic are described in the schema, and the description adds richer semantics: event walks child markets and runs partition checks; topic searches related events and flattens them. This goes well beyond the schema's basic descriptions.

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

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

The description opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', a specific verb+resource+method, and clearly distinguishes it from siblings like polymarket_fill_risk and polymarket_edges by focusing on arbitrage detection.

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 invocation guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also names an alternative: '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?

With annotations already declaring read-only, open-world, and idempotent behavior, the description adds substantial detail: response structure (by_segment, fed_candidates, _diagnostics), caching ('Cached 1h at the KV level'), and limitations (Fed bets unreliable without paid data). It also reveals diagnostics and gate conditions, far exceeding the annotation baseline.

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 approximately 300 words, densely packed with model details, threshold values, and output field names. While the purpose is front-loaded, the extensive details about model families, gate tuning, and diagnostics are excessive for initial decision-making. The use of ALL CAPS and verbose parentheticals adds noise rather than structure.

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 must explain the return format. It does so in detail: top-level segments, per-opportunity fields, and diagnostics with filter counters. It also explains why segments might be empty and how knobs affect results. This is sufficient for an agent to invoke the tool and interpret responses, though a more organized layout would improve clarity.

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% description coverage, including defaults, effects, and examples for all 9 parameters. The description adds contextual notes about 'TRADEABLE-EDGE KNOBS' and edge realizability, but this largely echoes the schema. With such high schema coverage, the marginal value is minimal, aligning with the baseline.

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

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

The description opens with a clear, specific statement: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also identifies the intended use case ('what should I bet on today') and differentiates from sibling tools by focusing on Pipeworx-derived edges rather than pure arbitrage or market tracking.

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

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

The description provides a clear use case: agents looking for betting opportunities without manually paging through hundreds of markets. It doesn't explicitly name alternatives or state when not to use it, but the context is sufficient. The note about Fed candidates being excluded from ranking hints at boundaries, yet lacks direct comparison to sibling 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 extensively discloses behavior beyond the read-only annotations. It explains the response structure (tracked, expired, snapshot_dates), the meaning of expired (closed/resolved/arbed away), the signed nature of edge_pp_net (negative = SELL YES), and limitations (60-day TTL, daily closes not intraday). This goes well beyond the safety profile provided by the annotations.

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

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

The description is intentionally organized into purpose, args, response, and limits. It is dense but every sentence provides value. While slightly long, the structure and front-loading make it efficient. The response key explanations justify the length.

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

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

There is no output schema, so the description must fully explain the return format, which it does with field-by-field detail. It also covers edge cases (snapshot gaps, TTL bound) and the signed interpretation of the metric. For a complex telemetry tool, this is highly complete.

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

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

Both parameters have 100% schema coverage. The description reiterates defaults and adds 'snapshot family' context for window, but this is marginal. It does not significantly deepen the understanding beyond the schema, so the baseline of 3 is appropriate.

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

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

The opening sentence clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' The rhetorical question 'how long has this edge existed and is it shrinking?' sharpens the intent, and the contrast with sibling tools like polymarket_edges is implicit through its focus on historical time-series rather than current edges.

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

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

The description implies when to use the tool: to distinguish fresh edges from stale ones ('a fresh wide edge and a 3-week-old wide edge are different trades'). It also gives strategic context ('median lifespan is your competition clock'). However, it does not explicitly name alternative tools or state when not to use this one, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, which the description aligns with (it's an analysis/check, not a mutation). The description adds substantial behavioral context beyond annotations: walks the ladder, returns verdict statuses, identifies thin legs, forced direction risk, and explains the dominant loss mode (partial basket fills converting an arb into unhedged directional position). No contradictions with annotations.

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

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

The description is long, but every sentence carries operational information. It uses clear labels like 'SINGLE-MARKET' and 'BASKET' and ends with a usage directive. However, it is a dense wall of text without line breaks or bullet points, which slightly hurts scannability. It's appropriately sized for the tool's complexity, but could be structured better.

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 enumerates all return values in both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers parameter defaults, clamping, mode selection, and usage context, making it fully complete for an agent to invoke correctly.

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

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

Even though schema coverage is 100%, the description adds critical semantic meaning: clarifies that exactly one of `market` or `event` is required (REQUIRES one of), and explains how `size_usd` is interpreted differently in each mode ('max spend on buys, target proceeds on sells' for single-market vs 'settlement notional S (shares per leg)' for basket). This goes well beyond the schema's descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly explains two modes (single-market and basket) and explicitly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by placing itself as the pre-trade fill-risk check.

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

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

The description gives explicit, actionable guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk), providing both when-to-use and strong implied when-not-to-use context.

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

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

Annotations already declare this a read-only, idempotent operation, and the description adds valuable behavioral context: compatibility_warning triggers under two distinct conditions, temporal_alignment indicates when spreads are 'mathematically meaningless,' and skipped_cross_type counters reveal why comparisons were dropped. It also candidly states that 'pre-mapped ≠ tradeable,' which sets expectations beyond the schema.

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

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

The description is lengthy, but every sentence contributes unique information: purpose, modes, response structure, safety fields, and limitation warnings. It is front-loaded with the core definition and modes before diving into complexity, and the density is appropriate for a tool with this many capabilities.

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

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

With no output schema, the description carries the full burden of explaining return values, and it succeeds: it specifies leg-by-leg prices, the direction of top_spreads_pp (Kalshi − Polymarket), and detailed safety fields. It also covers edge cases for temporal misalignment and leg-pair skips, making it comprehensive for an analyst.

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

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

Although the schema documents all three parameters, the description adds crucial mode semantics that the schema alone cannot convey: how 'topic' maps to shortcuts, and how explicit kalshi_event_ticker and polymarket_event_slug override the mapped sides. It provides real examples like 'KXFED-26OCT' and 'fed-decision-in-june-825,' which enrich the parameter meanings.

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 crisp verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and explicitly naming the two participating venues.

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

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

The description clearly explains two invocation modes (topic shortcuts vs explicit ticker/slug) and when each is appropriate. It sets expectations by warning that most pre-mapped topics return compatibility warnings and that non-equivalent bet shapes mean no arb exists, giving users exclusion criteria. However, it doesn't name sibling tools as alternatives, so it falls short of explicit alternatives.

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

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

Annotations already claim readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable extra context: scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the list-all behavior, going beyond the structured 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 sentences, each earning its place: core action first, practical examples second, scoping third, complementary tools fourth. No fluff, well front-loaded.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and related tools. It lacks an edge-case explanation (e.g., behavior when key not found), but given the high-quality annotations and simple contract, this is nearly 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 a clear parameter description ('Memory key to retrieve (omit to list all keys)'). The description reinforces this but does not add substantial new semantic information about the parameter, so the 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 the core action 'Retrieve a value previously saved via remember, or list all saved keys', naming both primary and alternative behaviors. It clearly distinguishes from siblings by pairing with 'remember to save, forget to delete', positioning recall as the read path.

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

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

Provides concrete use cases ('the user's target ticker, an address, prior research notes') to signal when to invoke, and references complementary tools (remember, forget). However, it stops short of explicit 'use X instead' exclusions, so a small guidance gap remains.

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

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

Annotation Contradiction: The annotations declare readOnlyHint=true and idempotentHint=true, but the description states that setting mark_read:true flags returned events read, which mutates feed state and affects future calls. This contradicts the read-only hint. The description otherwise gives useful context (polling, payload details), but the contradiction forces a score of 1 per rubric.

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

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

The description is compact and front-loaded: the first sentence states the verb, resource, and return shape. It uses four purposeful sentences without padding, and each sentence adds distinct value (purpose, filters, mark_read, polling/alternative endpoint).

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

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

Despite having no output schema, the description explicitly states what each alert carries (source, citation_uri, raw event payload), covers filtering, read-state handling, and polling behavior. With five optional parameters and no required inputs, this is sufficient context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds operational meaning beyond the schema: it explains that 'since' takes an ISO timestamp, gives an example for 'type' (sec_8k), and clarifies the downstream effect of mark_read (next call only shows newer ones). This is meaningful added semantics, though it does not cover every parameter.

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

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

The description uses a specific verb ('Pull') with a clear resource ('fired events from your subscription feed') and immediately distinguishes this tool from siblings like list_subscriptions, which likely lists subscriptions rather than alerts. It also names the returned entities (source, citation_uri, raw payload), removing any 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 usage context: filtering by type and/or since, using mark_read for read-state management, and confirms polling is acceptable. It even points to an alternative raw endpoint for scripts/dashboards, though it does not explicitly contrast with sibling tools 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?

Beyond the readOnly/idempotent annotations, the description discloses parallel fan-out to multiple sources, the GDELT→GNews fallback on rate-limit/5xx, and the USPTO soft-fail due to API sunset. It also describes the return format, giving the agent a clear picture of performance and failure characteristics.

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-loaded with the core purpose, then sources, parameter details, return structure, and alternative tool. Every sentence provides necessary information with no fluff, making it an exemplar of concise yet comprehensive documentation.

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 outlining the return structure (changes[], total_changes, citation URIs). It covers all necessary aspects: sources, fallbacks, parameter formats, and usage boundaries, making it fully complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful value by giving concrete examples for `since` ('2026-04-01', '7d', '30d', '3m', '1y') and a recommendation for typical monitoring. This helps the agent pick appropriate values beyond the schema's generic description.

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

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

The description clearly defines the tool as a change feed for a company over a time window, explicitly naming the data sources (SEC EDGAR, GDELT/GNews, USPTO) and listing the return structure. It distinguishes itself from sibling entity_profile by stating that entity_profile is for static profiles, 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?

The description explicitly tells when to use this tool (for 'what's new' queries) and when not to, directing to entity_profile for static profiles. It also provides practical parameter guidance ('Use 30d or 1m for typical monitoring'), leaving no ambiguity about selection.

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

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

Annotations already declare non-read-only, idempotent, non-destructive behavior. The description adds meaningful context: storage scoped by identifier, persistence differences for authenticated vs. anonymous sessions, and key-value semantics. 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?

Five sentences, each earning its place: purpose, usage, storage scoping, retention policy, and companion tools. Front-loaded with the main verb and no wasted words.

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

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

For a simple 2-parameter write tool with annotations and no output schema, the description is complete. It covers purpose, when to use, storage mechanics, retention, and related tools. Possible overwrite behavior is not stated but is not critical given idempotentHint.

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

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

Schema covers both parameters with descriptions and examples at 100% coverage. The description reinforces the key-value nature but adds no syntax or format details beyond the schema, so baseline 3 applies.

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

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

The description states 'Save data the agent will need to reuse later' with explicit scope across conversations or sessions. It names the resource (key-value storage) and distinguishes from siblings by pairing with recall and forget.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward...' with concrete examples. It also names alternatives: 'Pair with recall to retrieve later, forget to delete.' This clearly positions the tool against its 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?

Beyond the readOnly and idempotent annotations, the description discloses graceful degradation ('LEI/FIGI enrichment degrades gracefully... still return'), explicit handling of unresolved identifiers ('stated explicitly under `unresolved`'), and the internal cascading behavior ('cascades through several lookup endpoints'). This adds valuable transparency beyond the structured annotations.

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

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

The description is lengthy but well-structured, opening with examples, then purpose, then detailed supported types. Every sentence adds substantive detail (sources, fallback behavior, output semantics), though the density could be slightly reduced. It is front-loaded with the core purpose and remains organized.

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 what is returned: identifiers with source labels, an `unresolved` field, and drug returns include RxCUI+ingredient+brand+citation. It covers input types and degradation behavior. Missing details like multiple-match handling or an exact output schema, but for a lookup tool it is sufficiently complete.

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

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

The schema already documents parameters with examples, so the baseline is 3. The description enhances this by providing additional context, such as accepted input forms for each type (e.g., 'ticker (AAPL), CIK (0000320193), or name') and emphasizing the source-labeling behavior. This added guidance warrants a 4.

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

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

The description explicitly states the tool's function with a specific verb-resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also provides concrete query examples and distinguishes itself from siblings by focusing on name-to-ID resolution.

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

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

The description says 'Use FIRST whenever you have a name but need an ID,' which clearly states when to use it. It does not explicitly mention when not to use it or name alternative tools like entity_profile, so there is clear context but no 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 the tool read-only, open-world, idempotent, and non-destructive. The description adds behavioral context beyond this: it orchestrates multiple ai_visibility_check calls, ranks results, and returns a structured list with score/confidence/signal density. This explains the aggregation behavior and expected output, which annotations do not cover.

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

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

The description is compact (three sentences) and front-loaded with the primary purpose. It efficiently covers mechanism, use case, and output format without redundant wording or restating annotations. Each sentence earns its place.

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

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

For an aggregation tool with no output schema, the description properly discloses the return type (ranked list with score, confidence, signal density) and the process (calls ai_visibility_check per entity). However, it omits potential time/cost implications of multiple probes and the need for an API key when using the 'anthropic' model, though these are captured in the schema. Overall, sufficiently complete for effective use.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal semantic value, only framing entities as 'your brand + N competitors' and noting the first is the subject — but this is also implied in the schema's entity description. No significant extra parameter-level meaning is provided.

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: 'Compare AI visibility across multiple entities side-by-side' and explicitly describes the mechanism (probes each entity with ai_visibility_check, ranks by score). It specifies the scope (your brand + N competitors) and output (most/least recognized), distinguishing it from single-entity sibling ai_visibility_check.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example query ('does Claude know about us as well as our competitors?'). It implies this tool is for multi-entity comparison while single-entity tools like ai_visibility_check are for individual probes, though it does not explicitly name alternatives or state 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals that the tool fans out to multiple sources, may take 5-30s on first bundlephobia measurement, and degrades gracefully with sources_failed listing timeouts. It also details the return structure, which is not covered by an output schema.

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

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

The description is well-structured and front-loaded with the primary purpose. Each sentence provides distinct value: use cases, return fields, ecosystem scoping, and failure modes. Although long, it is efficient for the tool's complexity, with no redundant filler.

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

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

Without an output schema, the description fully enumerates the return summary fields and other outputs (per-advisory detail, links, alternative versions). It also covers edge cases (timeouts, partial failures) and ecosystem limitations, making it complete for an agent to decide when and how to invoke the tool.

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

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

The input schema already covers both parameters completely (100% coverage): package is an npm package name, version defaults to latest. The description adds little new parameter-specific meaning; it mentions recent alternative versions and version history but these are behavioral outcomes, not parameter semantics. Baseline 3 is appropriate.

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

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

The description opens with a clear, specific verb+resource: it performs a composite safety/quality check for npm packages by fanning out to deps.dev and bundlephobia. It explicitly scopes to 'should I add this npm package' and lists the exact domains (license, advisories, bundle size, etc.), distinguishing it from sibling scanning tools like scan_competitor_ai_presence.

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

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

The description gives explicit when-to-use guidance ('Use whenever an agent asks...') and when-not-to-use with an alternative ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). It also discloses partial failure behavior, which helps the agent set expectations.

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 is rich in behavioral detail (embeddings, 500-char windows, 200K cap, truncation flag, output format). However, it contradicts the openWorldHint=true annotation: the tool is described as operating solely on the provided text, while the annotation implies access to external data. This is a direct contradiction, forcing score 1.

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, purposeful sentences with no filler. The first sentence is the core definition, followed by use case, pairing, and technical details. Every sentence earns its place, and the description is well 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 no output schema, the description explains return values (passages, character offsets, similarity scores), constraints (truncation, cap), and algorithmic behavior. It gives enough contextual detail for an agent to select and correctly invoke the tool, including example queries and a workflow with a sibling 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 already covers all parameters (100% coverage). The description adds value by explaining text as 'the text you already pulled,' giving example queries for the query parameter, and clarifying the limit via 'top-N.' It also ties the 200K char cap to the text parameter, enriching the schema 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 'Semantic search INSIDE a fetched record,' immediately clarifying the action and resource. It distinguishes itself from siblings like ask_pipeworx_grounded by specifying that it searches within already-fetched text, not external sources. The output (passages with offsets and scores) is also clearly stated.

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

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

Explicitly tells agent when to use: 'Use when the record is too big to cram into the prompt.' It also names the complementary tool ask_pipeworx_grounded and explains the workflow of fetching then grounding, providing clear usage guidance and 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 extensive behavioral details beyond the minimal annotations: it requires an OAuth account, returns the new subscription id, explains webhook HMAC signing and the 'whsec_' secret returned only once, describes automatic webhook disabling after 10 failures, SMS verification and a 10/day cap. This significantly exceeds the annotations' safety profile and provides actionable operational knowledge.

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 yet perfectly structured: it front-loads the core purpose, then logically proceeds through return value, prerequisites, types, and delivery channels. Every sentence carries essential information without repetition or filler, making it an efficient and well-organized explanation for a complex tool.

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

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

Given the tool's complexity (3 parameters, 5 types, nested delivery object, no output schema), the description is remarkably complete. It explains the return value, authentication requirements, all delivery channels including their restrictions, and even mentions how to pull from the feed via recent_alerts or GET registry. It leaves no critical operational question unanswered.

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

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

Schema coverage is 100% and already documents each parameter, but the description enriches semantics with concrete examples like 'items:["5.02"] = officer change' and delivery behavior (e.g., webhook auto-disable). It does not cover all five types in the description (patent_grant, clinical_trial are only in schema), but for the types it does cover, it adds 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 first sentence clearly states the action: 'Create a proactive monitoring subscription to a live-data event stream.' This specifies the verb (create), resource (subscription), and purpose (monitoring). It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on subscription creation rather than listing, removing, or reading alerts.

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

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

The description provides clear context for when to use the tool, including prerequisites ('Requires a Pipeworx OAuth account'), supported subscription types, and delivery channel options. However, it does not explicitly state when not to use it or mention alternatives (e.g., for managing existing subscriptions, use list_subscriptions/unsubscribe), so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description does not contradict them. It adds useful behavioral context by explaining that output includes category-bucketed examples with exact tool + argument shapes, drawn from the live catalog, and that calls can be scoped by topic or get the full spread.

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 front-loaded with example user phrasings and packed with non-redundant information about purpose, output, and usage. The length is justified for an onboarding tool that must communicate multiple entry points and tool relationships.

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

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

For a single-optional-param tool with no output schema, the description is remarkably complete: it explains purpose, output contents, argument semantics, and when to use it first. No important usage dimension is left unaddressed.

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

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

The schema already documents the optional 'topic' parameter with 100% coverage, so the baseline is 3. The description adds meaning with concrete examples ('finance', 'pharma', 'betting') and clarifies the no-argument 'full spread' behavior, going slightly beyond the schema.

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

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

Description uses a specific verb ('returns') and resource ('category-bucketed example questions...') and explicitly frames the tool as an onboarding entry point. It clearly distinguishes from sibling tools like ask_pipeworx by focusing on surfacing suggestions rather than answering directly.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools,' which is clear when-to-use guidance. It does not explicitly state when not to use it, but the context and reference to meta-tools imply alternatives.

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

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

Annotations already indicate non-destructive (destructiveHint=false) and idempotent, but the description adds valuable context: ownership restriction and that the row is deactivated (not deleted), preserving history. This goes beyond annotations.

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

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

Two sentences, front-loaded with the key action and resource, then concise supporting details. Every word earns its place.

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

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

For a single-parameter mutation with no output schema, the description explains the effect (deactivation) and consequence (history preserved). It does not mention success/error responses, but given the simplicity, it is adequately 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 has 100% coverage with a clear description of the id parameter ('Subscription id (uuid) returned by subscribe'). The description adds no new parameter information, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id'. It distinguishes from siblings by focusing on the unsubscribe action, complementing subscribe and list_subscriptions.

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

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

Provides clear context: ownership enforcement and deactivation behavior. Does not explicitly name alternatives, but the description implies this is the correct tool for canceling subscriptions and clarifies the effect (historical events remain).

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, and idempotentHint, but the description goes far beyond them by explaining the two routing paths, the exact percent-delta math, and the return verdict list. Critically, it discloses the nuanced meaning of 'could_not_verify' (the check did not happen, not evidence) vs 'unsupported' (no source exists), which is essential for correct interpretation. This is exceptional behavioral disclosure.

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 relatively long (about 150 words) but every part contributes: examples for purpose clarity, routing logic, return values, and the error distinction. It is front-loaded with 'Use whenever' and the main purpose, then dives into mechanics. While it could be trimmed (e.g., the example phrasings are a bit redundant), 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?

With no output schema, the description must explain return values, and it does thoroughly: it lists the six verdicts, mentions the grounded/structured actual value with a pipeworx:// citation, and describes reasoning. It also covers the error semantics (verification_error with stage/detail) and distinguishes 'could_not_verify' from 'unsupported.' This is a complete and self-contained description for the tool's complexity.

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

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

The input schema covers both parameters (claim and tolerance_pct) with 100% descriptive coverage, including examples and the tolerance override semantics. The description adds no new parameter-level details beyond what the schema already states (it mentions 'percent-delta math' but that is not a parameter clarification). Baseline 3 applies because 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 the tool's purpose: natural-language claim verification against authoritative sources. It provides concrete example phrasings ('fact check', 'verify the claim that...') and explicitly names the two processing paths (SEC EDGAR fast path for company-financial claims, grounded pipeline for others). This strongly distinguishes it from siblings like ask_pipeworx or ask_pipeworx_grounded, which are general Q&A tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving clear context for deployment. It also notes that it replaces 4–6 sequential calls, implying it is the consolidated choice. However, it does not explicitly name alternative tools to avoid (e.g., ask_pipeworx) or state when not to use it (e.g., for open-ended research), 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.