Ons Uk

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: the default model is free (Workers AI Llama-3.3-70b), using Anthropic requires a BYO API key and direct payment to Anthropic, and it explicitly lists the return structure. This gives the agent full awareness of cost and auth requirements.

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: the first gives the main action and scoring output, the second explains model options and cost, and the third lists use cases. Every sentence earns its place, and the most important information is front-loaded. No fluff or repetition.

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

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

With no output schema, the description compensates by explicitly stating the return format: 'per-model {score, confidence, signals, raw_response} + a combined view.' It also covers default behavior, optional parameters, and relevant use cases. For a tool with only 4 parameters and no nested objects, this is complete and gives an agent everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces key details (e.g., default model, _apiKey for Anthropic) but does not significantly extend beyond what the schema provides. It adds a helpful example for `entity` and clarifies the default model behavior, but this is marginal value, keeping it at the baseline 3.

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

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

The description clearly states the verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on per-model visibility scoring with a specific output format.

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

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

The description provides clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains how to enable Anthropic via `_apiKey`, giving context for when to use that parameter. However, it does not explicitly mention when not to use this tool or name alternative tools for exclusions, so it falls short of a 5.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. Description adds valuable context: routes across 5,529 tools, stable pipeworx:// citation URIs, one fast call, works on every tier, and live news handling. Minor gaps like failure modes or rate limits are not disclosed, but the annotation coverage lowers the burden.

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

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

The description is long but every sentence earns its place: it front-loads the key directive ('PREFER OVER WEB SEARCH'), provides categories and examples, and clearly delineates when to escalate. No fluff or tautology.

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 broad routing complexity and no output schema, the description is remarkably complete. It covers purpose, usage triggers, examples, alternatives, output format (structured answer with citations), and operational traits (fast, all tiers). Annotations handle safety; description handles semantics.

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

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

Schema fully documents the 'question' parameter and aliases with 100% coverage. Description adds semantic richness by listing question types and examples that clarify what kinds of natural-language queries to pass. This goes beyond the schema's basic 'Your question or request in natural language'.

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

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

Description clearly defines tool as a question-answering router that returns structured answers with citations from verified sources. It explicitly positions itself as the default entry point and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit usage guidance: prefer over web search, trigger phrases ('what is', 'look up', 'find'), concrete examples, and clear step-up alternatives for grounded answers or broad research. No ambiguity about when to use this tool.

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

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

Beyond the annotations, the description discloses that candidate routing improvements are 'enabled live whenever one is under test,' and reports that the last candidate was retired on a specific date. It also explains that results are compared against the stable router, and reassures the agent that this is a fully functional router, adding important behavioral context.

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

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

The description is front-loaded with the beta purpose and each sentence provides relevant caveats and usage context. It is slightly repetitive (e.g., 'identical' and 'routing' appear multiple times), but the length is justified by the need to explain experimental status and current equivalence.

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

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

For a tool with a simple input (one required string) and no output schema, the description covers the essential context: beta status, current behavior, usage intent, and how it relates to the stable router. It references the same response shape as ask_pipeworx, which suffices given the sibling context, though it does not describe return value details.

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

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

The input schema fully documents all six parameters (question and its aliases) with 100% coverage. The description adds no parameter-specific information, so the baseline of 3 is appropriate; the schema handles semantic explanation.

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

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

The description clearly states the tool is a 'Beta version of ask_pipeworx' and an 'identical universal router' with the same tools, arguments, and response shape. It distinguishes from the stable sibling by emphasizing the experimental routing edge and explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing.' The verb+resource is specific and the relationship to ask_pipeworx is clarified.

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

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

The description gives explicit guidance: use it 'when you want the newest routing,' and notes that currently no candidate is active, so it 'matches ask_pipeworx exactly.' It also clarifies that this is a full working router and not a fallback, helping the agent decide when to invoke it over alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: the tool routes like ask_pipeworx, fetches data, extracts answers only from the result, returns verbatim evidence and confidence, and returns explicit refusal reasons on failure. This enriches transparency well beyond annotations and does not contradict them.

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

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

The description is long but every sentence is informative: it states the purpose, details the process, enumerates the return/refusal schemas, lists use cases, and notes the cost trade-off. Information is front-loaded with the core purpose and then logically details behavior, making it dense and well-structured.

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

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

Despite lacking an output schema, the description fully specifies the success response structure and the alternative refusal structure, including all refusal reason codes. It also explains the underlying routing scale (5,529 tools across 1455 sources) and the extra LLM call cost. This makes the tool's behavior and consequences clear for an agent to invoke confidently.

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

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

The input schema is fully described (100% coverage), with all aliases for 'question' documented. The description itself does not add parameter-level details, but the schema already handles this. Baseline 3 is appropriate since the description adds no extra semantic nuance over the schema.

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

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

The description clearly states a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly contrasts with the sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' and then detailing the extraction/refusal behavior, which distinguishes it from other tools. The purpose is unambiguous and tied to a concrete use case.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also gives a clear exclusion: 'prefer ask_pipeworx for casual lookups' and cites the extra LLM call cost as a trade-off. This goes beyond mere context and directly guides selection.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false, but the description adds a wealth of behavioral nuance far beyond that: low-confidence resolution short-circuiting, closed-market status, wide-spread illiquidity flag, resolution-rule risk with cancellation parsing, 24h-move warnings, and news fallback behavior (_fallback_attempted, retry_after_sec). These are critical runtime behaviors the agent must know, and none contradict 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 long, but every section earns its place: CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK. It is front-loaded with the core purpose and usage, then systematically adds detail in clearly labeled blocks. The use of ALL-CAPS headers and concise bullet-style examples makes dense information scannable and efficient for an agent to parse.

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

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

This tool has no output schema, so the description carries full responsibility for explaining return values. It comprehensively describes result.market, result.analysis (including the 24h-move warning), result.evidence, the resolver contract fields, parent_event structure, news fallback metadata, and special statuses (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread). It also covers resolution-rule risk and safety mechanisms, making it remarkably complete for a tool with this complexity.

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

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

Schema coverage is 100% (all three parameters have clear descriptions), so the baseline is 3. However, the description significantly extends parameter meaning: it details how depth ('quick' vs 'thorough') changes fan-out, how include_raw affects response size and downstream recomputation, and how the market parameter is resolved by the resolver contract (market_match_score, alternatives, suggestions). This goes far beyond what the schema states, adding both semantics and operational context.

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

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

The description opens with a precise verb+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then clarifies the input forms (slug, URL, or question text), the classification step, and the output (evidence packet + market-vs-model comparison). This clearly distinguishes it from sibling tools like validate_claim or polymarket_edges, and the detailed classifier list and fan-out examples solidify its scope.

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

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

Explicit usage guidance appears in the sentence 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This is supplemented by multiple concrete fan-out examples (BTC, Fed, Hormuz, Yankees, hottest-year, NVDA-vs-AAPL) that illustrate when the tool is appropriate. While it doesn't formally list exclusions relative to siblings, the examples and focus make the intended usage unmistakable.

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

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

The description goes well beyond the annotations, explaining data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and the return format including citation URIs. This adds significant behavioral context not captured in the readOnly/openWorld/idempotent hints, and no contradictions exist.

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

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

The description is dense but well-organized: trigger phrases first, then a clear statement of function, then per-type details, sorting behavior, and output format. Every sentence adds value, and the use of dashes and line breaks (in the original) makes it scannable despite its length.

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

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

Given no output schema, the description fully covers return values ('paired data + pipeworx:// citation URIs per entity'). It also explains sorting, fiscal year handling, and the data source for both entity types. The tool has moderate complexity, and the description addresses all key aspects an agent needs to invoke it correctly.

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

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

Although schema coverage is 100%, the description adds substantial meaning: type='company' vs 'drug' is elaborated with the specific metrics each pulls, and the values parameter is explained with examples (tickers/CIKs for companies, drug names). It clarifies that values is 2–5 items and how it maps to the two types, enriching the schema description significantly.

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's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It uses specific verbs like 'compare' and 'rank,' names the resource types (companies/drugs), and distinguishes from sequential lookups by stating 'ALWAYS PREFER over sequential single-pack lookups.' It also lists concrete trigger phrases, making it easy for an agent to recognize when this tool is suitable.

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

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

The description explicitly states when to use the tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' and provides direct usage examples like 'X vs Y' and 'rank these companies.' It also clarifies the distinction between type='company' and type='drug' with what data each pulls, giving clear contextual guidance without needing to reference sibling tools explicitly.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses substantial behavioral traits: question decomposition, parallel routing to 5,529 tools, the findings packet structure, explicit gaps[] and contradictions[], never-invented guarantee, semantic excerpting behavior, latency expectations (15-90s), and hop/re-iteration mechanics. This far exceeds what annotations provide.

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

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

The description is long but every sentence carries informational weight: account requirements, alternatives, scope, output format, edge cases, latency, and iteration semantics. It is front-loaded with the critical account sign-in warning and structured logically from high-level purpose to specific behavioral details, with 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?

With no output schema, the description fully describes the return value: a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri. It also covers edge cases like empty gaps for out-of-catalog topics and large-record excerpting, making the tool behavior fully predictable for an agent.

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

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

Although schema description coverage is 100%, the description adds meaningful semantics for both parameters: it explains what 'question' should look like (broad/multi-part is fine) and clarifies the behavioral differences and use cases for each 'depth' value ('quick', 'standard', 'thorough'), including gap-recovery, contradiction scanning, and paid-tier implications. This goes well beyond the schema's raw enum definitions.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources in a single call, with a specific verb (research) and resource (1455 structured data sources). It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, making its purpose unmistakable.

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

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

Usage is explicitly framed: 'Best for broad/multi-part questions over structured data' with concrete examples, and clear exclusion criteria: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also provides account-tier guidance and alternative tool for unauthenticated users, leaving no ambiguity about when to invoke this tool.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context: it returns top-N tools with names, descriptions, full input schemas, and curated examples, and each result is 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations by specifying the exact return content and the 'ready to call' behavior, though it doesn't mention rate limits or edge cases.

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

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

The description is three sentences with a clear progression: what it does, when to use it, what it returns, and an explicit 'call this FIRST' directive. The list of domains is long but informative and directly relevant for matching the right tool. Every sentence earns its place; there is no fluff or redundancy.

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

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

This is a discovery tool with no output schema, yet the description compensates fully: it states the return type (top-N tools), the included fields (names, descriptions, full input schemas with curated examples), and the self-contained nature ('no second schema lookup needed'). The companion schema fully documents parameters, making the description complete for understanding the tool's behavior and context.

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

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

Schema description coverage is 100% for all 6 parameters, including detailed descriptions and alias list for the query parameter. The description provides no additional parameter semantics beyond the schema; it merely restates that the query is a natural language description. Baseline 3 is appropriate because 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 opens with 'Find tools by describing the data or task,' which clearly specifies the verb (find/browse/search/discover) and the resource (tools). It enumerates specific domains (SEC filings, FDA drugs, etc.) and contrasts with sibling tools by being the only discovery/meta tool. This fully distinguishes it from the sibling list.

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 guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly tells the agent when to invoke it, including the 'first' priority and the 'not just one answer' exclusion.

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

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

The description discloses significant behavioral traits beyond the readOnlyHint and idempotentHint annotations. It reveals the USPTO PatentsView API sunset (May 2025) and the soft-fail behavior, the GDELT→GNews fallback chain, and the requirement for zero-padded CIK. These details inform the agent about potential failures and internal fan-out behavior.

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

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

The description is dense and front-loaded with example user intents, immediately followed by the core function. While every sentence adds information, it is long and lists many output details in a single paragraph. The structure is logical, but a slight trimming or bulleted format could improve scannability.

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

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

For a tool with no output schema, the description is remarkably complete. It specifies input types, supported sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), fields returned (cik, company_name, recent_filings, fundamentals, patents, news, LEI), sorting behavior, and even API sunset caveats. This covers both invocation and expected results comprehensively.

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

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

The input schema already provides 100% coverage with descriptions for both 'type' and 'value'. The description adds concrete examples ('AAPL', '0000320193') and reinforces the name restriction, which helps the agent construct valid inputs. This extra context is valuable but not essential given the schema quality, hence 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 clearly states the tool's purpose with a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It immediately provides example queries ('Tell me about X', 'research Acme') that make the intent unmistakable, and it distinguishes from siblings by explicitly preferring this over chaining single-purpose lookups.

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

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

Usage guidance is explicit: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear alternative when the user only has a name: 'use resolve_entity first if you only have a name.' This covers both when-to-use and when-not-to-use scenarios.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the core safety profile is known. The description adds that it affects 'previously stored memory' and can be used to 'clear sensitive data,' but these are more about usage context than new behavioral details. 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?

Two sentences, front-loaded with the action verb, direct, and no filler. The second sentence efficiently covers usage scenarios and related tools.

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 delete tool with strong annotations, the description adequately covers purpose, usage, and related tools. No output schema exists, so return values don't need explanation.

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 parameters, and the single 'key' parameter is described as 'Memory key to delete.' The description's 'by key' adds no additional semantic meaning 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 begins with 'Delete a previously stored memory by key,' which clearly states the action (delete) and resource (memory by key). It distinguishes itself from siblings like remember and recall by explicitly mentioning pairing with them.

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 'Use when...' conditions covering three scenarios: stale context, task complete, and clearing sensitive data. It also suggests pairing with remember and recall, indicating related tools. However, it does not explicitly state when not to use this tool.

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

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

Annotations declare readOnlyHint and idempotentHint, covering the safety profile. The description adds behavioral context: fetching the page, extracting title/description/key links, and emitting markdown. It omits edge cases like unreachable URLs, but the annotations lower the bar, and the added process detail is valuable.

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

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

The description is three sentences, front-loaded with the main purpose, followed by concise process and use cases. Every sentence contributes value with no redundancy or filler.

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

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

The tool is simple with two parameters and no output schema. The description fully explains what it does, how it works, what output to expect ('single text blob'), and when to use it, making it 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?

The input schema covers 100% of parameters with descriptions. The description adds minimal extra meaning beyond the schema's parameter details, only implying 'any URL' flexibility. Baseline 3 is appropriate since 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 uses a specific verb ('Generate') and resource ('llms.txt'), and clearly outlines the process (fetches, extracts, emits). It distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on producing the file rather than analyzing 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 provides explicit use cases: getting a client's site indexed, drafting for a project, or auditing competitor visibility. It does not explicitly state when not to use it or name alternative tools, but the context is clear enough to guide the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds valuable behavioral detail by listing the return fields (id, type, params, created_at, last_fired_at, fire_count), which is not otherwise specified since there's no 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 two sentences, front-loaded with the action and output fields, followed by a single usage pointer. Every word earns its place with no filler or repetition.

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

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

For a simple read-only listing tool with one optional parameter, the description fully covers the return value and usage context. The annotations handle safety, and the schema handles parameters, so no critical gaps remain.

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

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

The sole parameter include_inactive is fully described in the schema ('Include cancelled subscriptions in the response (default false).'), so the schema already provides complete semantics. The description adds no additional parameter information, which matches the baseline for 100% schema coverage.

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

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

The description states exactly what the tool does: 'List the caller's active subscriptions.' The verb 'List' is specific and the resource is clear. It distinguishes from siblings like subscribe and unsubscribe by focusing on retrieving existing subscriptions.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly tells the agent when to use it relative to subscribe and unsubscribe.

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

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

Annotations carry no hints (all false), so the description carries the full burden. It discloses claim_token behavior (returns a token, can be passed back to check status), rate limiting (5/day), that it's free and doesn't count against quota, and that the team reads digests daily. This greatly exceeds annotation coverage and contradicts nothing.

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 adds value: purpose, usage, exclusions, token workflow, rate limits. It is front-loaded with the core action, then branches into context and constraints. Slightly verbose but appropriately so given the tool's nuanced behavior.

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 both the initial filing behavior (returns claim_token) and the subsequent lookup behavior (returns status and changes). It also covers scope limitations, rate limits, and cost, making the tool fully understandable for an agent without reference to additional docs.

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

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

Schema coverage is 100% with each parameter described. The description adds meaningful nuance beyond the schema: claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and message guidelines ('describe in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This elevates it above the baseline 3 without being fully exhaustive about all parameters.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete feedback categories (bug, feature, data_gap, praise), and is distinct from all sibling tools, which are research/subscription-oriented.

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

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

Explicit usage conditions are given: when a tool returns wrong data (bug), when a tool is missing (feature/data_gap), or for praise. It also explicitly advises against reporting tools from other MCP servers and directs to file with that server instead, providing a clear alternative and boundary.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This explains data sourcing, privacy, and caching beyond the annotations.

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

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

The description is compact yet information-dense. The main purpose is front-loaded in the first sentence, followed by a brief 'Useful for' list. No wasted words; every sentence contributes meaning.

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 a single optional parameter and no output schema, the description fully covers what is returned ('top tools, top packs, total call volume'), data source, caching, and use cases. It is complete for an agent to invoke and interpret results.

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

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

The schema already defines the 'window' enum, but the description adds valuable semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This directly informs parameter choice, exceeding the schema's baseline.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It names the specific resource (Pipeworx trending) and the exact output, distinguishing it from siblings like discover_tools by focusing on current demand rather than discovery.

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

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

The 'Useful for' section provides three concrete use cases, including discovering hot data sources and validating whether a tool is canonical. It does not explicitly name sibling alternatives or exclusions, but the context is clear enough to guide an agent on when to call this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, and the description adds rich behavioral context: the partition filter (drops placeholder slugs, >20% placeholder returns null), semantic anchor (Jaccard ≥0.30), and fill check (realizable_edge_pp ≤0 means don't trade). It also explains the output structure and potential fields like skipped_low_similarity. This goes well beyond the annotations and fully discloses operational behavior.

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

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

The description is lengthy but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Each sentence carries actionable information, though the extreme density and detail could be overwhelming. It earns its place but slightly sacrifices brevity for completeness, making it a 4 rather than a 5.

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

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

The tool is complex, has no output schema, and relies on annotations for safety. The description compensates fully by detailing the expected response structure (opportunities[], partition_check fields, fill_check fields), explaining edge cases (thin legs, placeholder thresholds), and providing examples. This gives an agent everything needed to understand inputs, outputs, and failure modes.

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

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

The input schema already has descriptions for both parameters (event and topic), with 100% coverage. The description adds substantial meaning beyond the schema: it explains the difference between single-event and cross-event modes, provides concrete slug examples ('fed-decision-may-2026'), and clarifies the type of data each expects. This is a case where description elevates parameter understanding far beyond the schema.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this tool from siblings like polymarket_fill_risk by naming the alternative for custom sizing. The modes (trending_scan, event, topic) are described with concrete examples, making the tool's function unmistakable.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event for the strongest per-event partition_check', and 'topic for a themed cross-event scan.' It explains the rationale for choosing cross-event mode (catches May 31 vs Jun 30 patterns) and explicitly points to a sibling tool: 'For custom sizing use polymarket_fill_risk.' This exceeds basic 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 readOnly/idempotent/non-destructive, and the description adds extensive behavioral detail: response segments (by_segment), model-family logic, edge calculations (net of slippage), Kelly caps, diagnostics, 24h-move warning, KV caching, and rationale for excluding Fed bets. This far exceeds what the 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 dense and front-loaded with purpose, but the rest is an uninterrupted wall of text mixing model details, response fields, knobs, and caveats without structural breaks. While every sentence adds information, it could be organized under headings or bullets for easier scanning; it is not 'appropriately sized' in a concise sense.

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

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

For a complex tool with 9 parameters and no output schema, the description covers response structure, diagnostics, edge formulas, Kelly sizing, slippage, liquidity filters, caching, and limitations. It even explains expected frequencies (concentrated_longshot is rare-by-design) and why certain signals are unreliable, making it fully adequate for invocation.

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

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

Schema covers all 9 parameters, but the description enriches them with rationale and guidance—e.g., slippage_pp references Polymarket's zero fees and 20-50bp bid/ask costs, min_partition_leg_kelly explains why partition arbs have parent-level kelly_fraction_half=0, and tradeable-edge knobs are grouped and explained. This goes well beyond the schema descriptions.

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

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

The first sentence clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case. It distinguishes itself from siblings like polymarket_arbitrage or polymarket_edge_tracker by covering three model families and positioning as a daily discovery tool.

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

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

States 'Built for "what should I bet on today"' and explains that agents discover opportunities without paging hundreds of markets, giving clear context. Does not explicitly name alternatives or provide when-not-to-use scenarios, though it notes Fed bets are excluded from ranking, which is a limitation.

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

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

Even with readOnlyHint and other annotations, the description adds significant context beyond them: it explains the snapshot-driven data source, cache-miss behavior causing gaps, the 60-day TTL limiting history depth, and how decay is computed from daily closes. It also clarifies the signed nature of edge_pp_net. This is rich behavioral disclosure that the 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 long and dense, but every section earns its place, front-loading the purpose and then structuring args, response, and limits with clear labels. It could be tightened by trimming some prose, but given the complexity and lack of an output schema, the length is largely 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?

With no output schema, the description fully explains the return structure (tracked[], expired[], snapshot_dates[]), including field semantics, examples, and handling of edge cases like gaps. It also covers limitations and computation methodology, making it complete for an agent to invoke and interpret results.

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

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

The input schema already provides 100% coverage with descriptions for both parameters (days, window) including defaults and clamps. The description adds narrative context by introducing the concept of 'snapshot family' for window and explaining the lookback semantics, which slightly enhances the schema's meaning without redundancy.

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

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

Description clearly identifies the tool as providing 'edge persistence and decay telemetry' from daily snapshots, answering the specific question 'how long has this edge existed and is it shrinking?' This is a specific verb+resource pair that distinguishes it from siblings like polymarket_edges, focusing on temporal analysis rather than current edge discovery.

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

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

The description strongly implies when to use the tool by framing the scenario: 'a fresh wide edge and a 3-week-old wide edge are different trades'. It provides clear context, but it does not explicitly name alternative tools for comparisons or state when not to use it, so it stops short of 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 readOnlyHint, idempotentHint, and non-destructive behavior, but the description adds rich behavioral context: it walks the order-book ladder, reports slippage and partial fills, names 'thin_legs[]' and 'forced_directional_risk,' and describes the dominant loss mode. No contradiction exists with the annotations.

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

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

The description is dense and front-loaded with the core purpose, but it is one long paragraph mixing mode details, return-value lists, and risk warnings. Every sentence carries useful information, so the length is justified for this complex tool, though clearer sectioning would improve scannability.

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 disclose return values, and it does so extensively: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, capture_ratio, profit_usd, per-leg fill detail, and more. It also covers prerequisites, failure modes, and the practical reason for using the tool, making it complete for an agent.

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

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

Schema coverage is 100%, but the description goes beyond simple field names by explaining mode-dependent semantics: size_usd means max spend on buys vs target proceeds on sells vs settlement notional in basket mode, side defaults differ per mode, and clamping range is specified. This adds substantial meaning beyond the schema.

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

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

The description opens with a specific verb+resource phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' and then clearly distinguishes single-market and basket modes. This uniquely positions it against siblings like polymarket_arbitrage and polymarket_edges, so the purpose is unmistakable.

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

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

It explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why thin-book theoretical edge is not capturable and warns that partial basket fills create unhedged directional risk, giving clear exclusion criteria for 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?

Despite annotations already indicating read-only, idempotent, and non-destructive behavior, the description adds substantial behavioral detail: it explains matching logic, skipped cross-type/subtype comparisons, compatibility warning conditions, temporal alignment semantics, and the surprising fact that most pre-mapped topics return warnings. This goes far beyond the annotations and gives critical insights into the tool's behavior.

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

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

The description is long but structured into clear sections (modes, response, safety fields). It is front-loaded with the core purpose and each subsequent sentence adds unique information. It could be tightened slightly, but for a complex tool with safety caveats, the length is justified and there is no redundancy.

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

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

With no output schema, the description carries the full burden of explaining the return values. It does so comprehensively: leg-by-leg prices, spread calculation, compatibility_warning triggers, temporal_alignment fields, and skipped-cross counters. It also covers edge cases and caveats, making the tool's behavior fully understandable even for a first-time user.

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

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

Schema coverage is 100%, and the description largely mirrors the schema's parameter descriptions (e.g., listing topic shortcuts, explaining override behavior for ticker/slug). While it adds the conceptual framing of two modes, it doesn't introduce new parameter-level semantics beyond what the schema already provides. 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 states a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and even details the two modes of operation. The scope and uniqueness are unambiguous.

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

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

The description explains when to use each mode: pre-mapped 'topic' shortcuts for quick macro events and explicit ticker/slug for custom pairings. It also warns about misleading situations with compatibility_warning and temporal_alignment, and explicitly notes that 'pre-mapped ≠ tradeable.' It doesn't explicitly name alternative tools, but the context of when and how to use the tool is clear enough.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds valuable context: storing is scoped to an identifier (anonymous IP, BYO key hash, or account ID), and the 'omit the key argument' behavior is disclosed. These go beyond the annotations and help the agent understand the tool's operational boundaries.

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 serving a purpose: first defines the action, second provides usage examples and rationale, third explains scoping and relationships. No wasted words, front-loaded with the main functionality. This is appropriately concise.

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 tool with one optional parameter and no output schema, the description covers all essential aspects: purpose, usage pattern (with examples), scoping, and relationship to sibling tools. It does not need to detail return values or error handling given the simplicity of the operation.

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 fully documents the single 'key' parameter with a clear description ('Memory key to retrieve (omit to list all keys)'). The tool description reinforces this with 'omit the key argument' and adds scoping context, but does not add significant new semantic detail beyond what the schema already provides. Baseline 3 applies due to high schema coverage.

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

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

The description uses a specific verb ('Retrieve'/'list') with a clear resource ('a value previously saved via remember'), and explicitly distinguishes from siblings by naming 'remember' and 'forget'. It also clarifies the dual behavior of retrieving a single key or listing all keys.

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 states when to use it ('Use to look up context the agent stored earlier') and gives concrete examples of use cases. It mentions the omit-key behavior for listing all keys and pairs with remember/forget, but does not explicitly state when not to use it or name alternative lookup 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 annotation declares readOnlyHint: true, implying no state changes. However, the description explicitly describes a mutating side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the annotation. No credit is given for other disclosed traits because the contradiction invalidates the safety profile.

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

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

The description is efficient, with each sentence providing a distinct piece of information: what it returns, how to filter, side effect of mark_read, and alternative access. It's slightly verbose but every sentence earns its place, making it well-structured for an agent.

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 listing return fields ('source, citation_uri... raw event payload'). It also covers filtering, pagination via limit (implicitly), and polling semantics. It doesn't mention error cases or rate limits, but for a read-style list tool with rich annotations, it's reasonably 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 input schema already covers all parameters with descriptions (100% coverage). The description adds valuable context beyond the schema by explaining how 'type' and 'since' work together, and clarifying the effect of 'mark_read' on subsequent calls, which is not obvious from the raw schema.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed' and specifies the resource (persisted feed) and the type of data (alerts). It distinguishes itself from siblings like list_subscriptions by focusing on fired events rather than subscription management.

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 direct usage context: 'Filter by type... and/or since', 'Set mark_read:true to flag returned events read', and mentions polling suitability. It also offers an alternative access method ('same feed is also at GET...') which implies when this tool is preferred (programmatic polling). However, it doesn't explicitly contrast with sibling tools beyond implying it's for recent fired events.

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

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

Beyond the read-only/idempotent annotations, the description discloses multi-source fan-out, GDELT→GNews fallback under rate limits/5xx, USPTO soft-fail due to PatentsView sunset, and the structured return shape (changes[] grouped by source, total_changes, citation URIs). This is rich behavioral context that 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 dense but every clause earns its place: user intent phrasing, source list with fallback logic, date format rules, return structure, and alternative tool. It is front-loaded with natural-language queries and remains a single coherent paragraph with 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 (multiple upstream APIs, fallback chains, temporal windowing, structured output), the description covers all necessary aspects: what it does, how it behaves under failures, how parameters work, and what the response contains. No output schema exists, so the explicit mention of changes[] and total_changes is essential and delivered.

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

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

Although schema coverage is 100%, the description adds practical semantics: `since` accepts ISO or relative shorthand with concrete examples ('7d', '30d', '3m', '1y') and recommends '30d'/'1m' for monitoring. It also clarifies that `type` only supports 'company' and that `value` accepts ticker or CIK, reinforcing schema descriptions with usage context.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It uses specific verbs and intent phrases ('What's new', 'latest on', 'what happened to', 'updates on') and distinguishes itself from entity_profile by contrasting static vs. dynamic profiles.

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 provides an alternative tool ('Use entity_profile instead when you want the static profile...') and gives a typical usage recommendation ('Use "30d" or "1m" for typical monitoring'). It also explains source fallback behavior, helping the agent decide when results may be incomplete.

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 convey idempotency and non-read-only status. The description adds valuable behavioral context beyond annotations: persistence differs for authenticated vs. anonymous sessions (24-hour retention) and storage is scoped by identifier. It does not contradict annotations.

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

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

Three sentences, front-loaded with the core action. Every sentence earns its place: purpose, when-to-use, storage semantics, pairing with recall/forget. No redundancy or filler.

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

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

For a simple two-parameter storage tool with no output schema, the description covers purpose, use cases, persistence behavior, and related tools. It is fully adequate for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% with both parameters described. The description adds semantic color beyond the schema by giving real-world usage examples ('a resolved ticker, a target address') and key naming patterns, helping the agent understand how to structure key-value pairs.

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: 'Save data the agent will need to reuse later.' It clearly distinguishes from sibling tools by explicitly pairing with recall (retrieve) and forget (delete), making its role unique among memory-related 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?

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward (a resolved ticker, a target address...)' with concrete examples. It mentions complementary tools (recall, forget) but does not explicitly state when not to use it, so it lacks full 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 mark this as read-only and idempotent, but the description adds significant behavioral context: graceful degradation of LEI/FIGI enrichment when external APIs are unavailable, explicit labeling of identifiers by source, and the guarantee that unresolved identifiers are stated under 'unresolved' rather than omitted. These traits go well beyond the annotations and help set agent 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 long but well-structured: it opens with concrete example queries, states the core purpose, then breaks down supported types with nested details. While every sentence adds value, the numerous example phrasings (even though helpful) make it somewhat verbose, preventing a perfect score.

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

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

Given the tool's complexity (multiple entity types, multiple identifier sources) and the absence of an output schema, the description thoroughly explains what the tool returns for each type, including source-labeled identifiers, unresolved handling, and degradation behavior. This makes it fully self-contained for an agent to understand inputs and outputs.

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

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

The schema already provides 100% descriptive coverage for both parameters, including enums and examples. The description reinforces the same input formats (e.g., ticker, CIK, name for company; brand/generic for drug) but does not add meaningful new parameter semantics beyond what the schema already states. The additional detail is mostly about output behavior, not parameter meaning.

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

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

The description precisely states the tool resolves user-spoken names to canonical/official identifiers, with concrete example queries like 'What's the ticker for…' and 'find the CIK for…'. It clearly differentiates itself from siblings by asserting 'Use FIRST whenever you have a name but need an ID' and details the two supported types (company and drug) with their specific output identifiers.

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 this tool 'FIRST whenever you have a name but need an ID', which is a clear usage trigger. It also notes that using it replaces 2-3 manual lookups, conveying efficiency benefits. However, it does not name alternative tools or provide explicit 'when not to use' exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable behavioral context: it details the internal probe via ai_visibility_check and the output structure (ranked list with score, confidence, signal density). This goes beyond the annotations without contradicting them.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value. It includes a use case and return format in two sentences, achieving high information density without verbosity.

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 explicitly specifies the return format (ranked list with score, confidence, signal density). It covers input semantics, use case, and underlying mechanism, making it complete for a comparison tool with good 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 description coverage is 100%, so the baseline is 3. The description does not add significant parameter-specific meaning beyond the schema; it mentions 'your brand + N competitors' which is already captured in the entities parameter description. No extra syntax or format details are 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 uses a specific verb 'Compare' with a clear resource 'AI visibility across multiple entities side-by-side'. It explicitly mentions the mechanism (probes with ai_visibility_check), ranks by score, and surfaces most/least recognized, distinguishing it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 ('competitive AI-marketing audits') and an illustrative example ('does Claude know about us as well as our competitors?'). It positions this tool as a multi-entity wrapper around ai_visibility_check, but does not explicitly state when not to use it or compare with other 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 annotations (readOnly, idempotent, non-destructive), the description discloses important behavioral traits: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts. This is exactly the kind of contextual behavior an agent needs to 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?

Despite being long, the description is efficiently structured: purpose, use case, return summary, ecosystem limitation, and failure behavior. Every sentence adds a distinct piece of information, and the most important info 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?

The tool is complex (multiple external sources, no output schema), yet the description covers the full return shape (summary fields, per-advisory details, links, recent versions), the partial failure mode, and the ecosystem scope. No critical behavioral gaps remain.

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

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

The input schema already provides 100% coverage for both parameters, including the default behavior for 'version' and scoped package support for 'package'. The description does not add substantive parameter-level information beyond what the schema states, so the baseline score of 3 applies.

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

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

The description clearly states the tool's function: a composite 'should I add this npm package' check combining deps.dev and bundlephobia data. It specifies the exact resources (license, advisories, version history, bundle size, etc.) and distinguishes it from any sibling tool by naming the data sources and ecosystem.

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 when to use this tool ('whenever an agent asks "is X safe / popular / small"...') and when not to use it, naming the alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This is model 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?

Beyond the read-only/idempotent hints, the description discloses the 200K character truncation with flagging, the BGE-base-en embedding and cosine method over 500-char overlapping windows, and the return format with offsets and scores. These are behavioral details not captured in annotations.

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

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

The description is about 100 words but efficiently covers purpose, usage, pairings, and technical details in just four sentences. It is front-loaded with the core action and contains no filler or redundancy.

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

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

With no output schema and only basic annotations, the description fully covers the return format, truncation behavior, embedding approach, and usage context. It even references a sibling tool to show integration, making it complete for agent decision-making.

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

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

The schema already has 100% coverage with examples, so the baseline is 3. The description adds value by framing text as already-fetched content and emphasizing that query is natural language, though it repeats the character cap. This slight additional framing justifies 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 clearly states a specific verb and resource: semantic search inside a fetched record. It differentiates from siblings by focusing on already-pulled text and returning passages with offsets, and it explicitly references ask_pipeworx_grounded as a complementary tool.

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

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

It explicitly says when to use: when the record is too big to cram into the prompt, and explains context-saving benefits. It also names ask_pipeworx_grounded as a natural counterpart for grounding over passages, giving clear workflow 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 discloses extensive behavioral traits beyond the annotations: authentication requirements, delivery channel behaviors (sms verification, 10/day cap, webhook signing secret, auto-disable after 10 failures), and return value. This richly supplements the basic readOnly/idempotent/destructive hints provided in annotations.

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

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

The description is compact yet comprehensive, front-loading the core purpose and then organizing details by subscription type and delivery channel. Every sentence adds value, and the structure makes it easy to scan even with high information density.

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 three parameters with nested objects, multiple subscription types, and no output schema, the description covers all necessary aspects: return value, supported types with examples, delivery options, account requirements, and limitations. It fully prepares the 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?

While the input schema has 100% coverage, the description adds significant practical examples and constraints (e.g., sec_8k item codes, polymarket topic 'fed', fred_series series_id, email/sms/webhook specifics such as phone verification and HMAC signing). This adds real-world meaning beyond the schema's enumerations and descriptions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes from sibling tools like list_subscriptions by focusing on creation and returning the new subscription id.

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 prerequisites ('Requires a Pipeworx OAuth account', 'anonymous + BYO cannot persist subscriptions') and context on when to use vs alternatives (e.g., feed retrieval via recent_alerts or GET registry.pipeworx.io/alerts.json). This gives clear guidance not just on what the tool does but how and when 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?

The description goes beyond the annotations by explaining the output characteristics: category-bucketed example questions, each with exact tool and argument shape, drawn from the live catalog. It also notes that the result varies based on the optional topic parameter and emphasizes the tool's role as a learning aid. This adds substantial context not provided by the readOnly/openWorld/idempotent hints.

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

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

The description is well-structured and front-loaded with example questions, but is somewhat lengthy. The list of example queries is useful but could be condensed. Still, every sentence contributes to understanding the tool's purpose and usage, so it earns a solid score.

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

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

Given the tool's moderate complexity, the description is complete. It explains what the tool returns, how to invoke it, when to use it first, and how to focus it. The lack of an output schema is compensated by the description's detail about category-bucketed questions and tool/argument shapes. No gaps are evident.

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

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

The schema already covers the 'topic' parameter with a description listing valid values. However, the tool description adds examples ('finance', 'pharma', 'betting') and explains behavior when omitted (cross-category spread) and when provided (focus). This improves the parameter's semantics beyond the schema, though not dramatically.

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: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from sibling tools by explicitly mentioning it should be used FIRST when unfamiliar with Pipeworx and by naming the meta-tools it teaches how to call.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains how to call it (no arguments for full spread, optional topic to focus) and references alternative tools like ask_pipeworx, entity_profile, and compare_entities, giving clear context for when this tool is appropriate.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description adds crucial behavioral details: ownership enforcement and that the row is deactivated rather than deleted, preserving historical events in recent_alerts. This fully discloses side effects and access rules, exceeding what annotations provide.

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

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

Two sentences, front-loaded with the core action, and every sentence adds value (ownership and deactivation behavior). No redundancy or irrelevant information.

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

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

For a simple unary-parameter mutation tool with strong annotations and full schema coverage, the description covers purpose, side effects, and constraints. No output schema is present, but the description does not need to explain return values for this operation. It is complete.

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

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

Schema description coverage is 100% with id described as 'Subscription id (uuid) returned by subscribe.' The description does not add further parameter detail, but the schema already provides complete semantics, so the baseline score of 3 is appropriate.

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

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

Description clearly states the action ('Cancel a subscription by id') and specifies the resource (subscription). It distinguishes itself from sibling tools like subscribe and list_subscriptions by mentioning ownership enforcement and deactivation behavior, making its scope unambiguous.

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

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

Provides clear context: ownership is enforced and only your own subscriptions can be canceled. It implies appropriate use (when canceling a subscription) and gives relevant constraints, though it does not explicitly name alternative tools or state when-not-to-use. This is sufficient for the tool's simple role.

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 discloses critical behavioral nuances: the special meaning of 'could_not_verify' (check did not happen, carries verification_error, must not be shown as evidence), 'unsupported' (no source covers it), the routing logic between SEC EDGAR/XBRL and grounded pipeline, and the return format with pipeworx:// citations. This is rich, non-obvious behavioral context that annotations alone do not 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 dense but every sentence earns its place. It front-loads with intuitive query examples, then explains the routing, return values, and critical caller caveats in a logical sequence. Despite its length (~150 words), it avoids fluff and covers essential operational details, including edge-case semantics and the value proposition of replacing multiple calls.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It enumerates the verdict enum (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), mentions the grounded or structured actual value with citation, and provides reasoning. It also explains error scenarios and the single-call replacement benefit, making it fully self-contained for callers despite 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 already has 100% coverage with good descriptions for both 'claim' and 'tolerance_pct'. The description adds semantic depth beyond the schema, especially for 'tolerance_pct': it explains the override behavior, the cap at 5, and recommends 1–2 for hallucination detection. It also clarifies that 'claim' is natural-language and gives examples. This goes beyond the schema, but since schema coverage is high, the added value is incremental rather than essential.

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, with explicit example phrasings. It distinguishes itself from sibling tools by highlighting the structured SEC EDGAR path for financial claims and the fallback grounded pipeline for other facts, plus the fact that it replaces 4–6 sequential calls. This is a specific verb+resource with clear scope.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context. It differentiates between the structured fast path for company-financial claims and the grounded pipeline for other claims, but it doesn't explicitly name when to use alternative tools (e.g., deep_research or ask_pipeworx_grounded) instead. No exclusions are stated, making this a clear context with no when-not guidance.

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