Retractions

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable context beyond annotations: the default model is free, passing `_apiKey` invokes Anthropic and caller pays directly, and per-model response shape includes score/confidence/signals/raw_response. It avoids contradicting annotations and offers useful operational detail.

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

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

The description is compact and front-loaded: it begins with the primary action and then efficiently covers defaults, key requirements, return format, and use cases. No redundant phrases or filler; every sentence contributes useful 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?

Given the tool's moderate complexity and lack of output schema, the description covers the essential aspects: what it does, how parameters work, return structure per model, and typical applications. The main gap is the 'combined view' mentioned but not detailed, and the absence of cost/rate-limit caveats for the free tier, but this is acceptable given annotations and concise scope.

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

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

Schema coverage is 100%, so baseline is 3. The description adds contextual meaning by explaining the default model (workers-ai) and the interplay between `models` and `_apiKey`, including cost implications. It also implies that `context` helps disambiguation, already in schema, but the narrative around defaults and key requirements adds value above the schema.

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

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

The description clearly states the tool probes one or more LLMs about a business/product/topic and scores visibility per model. The verb+resource+output are specific and well-defined. However, it does not explicitly distinguish from the sibling tool 'scan_competitor_ai_presence' which likely serves a similar purpose, so it misses full sibling differentiation.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also clarifies the default model and when to pass an API key. However, it does not mention when not to use this tool or name specific alternative tools to consider for exclusion, stopping short of full 'when/when-not' 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 cover read-only, idempotent, and non-destructive nature. The description adds valuable behavioral context: it routes across 5,578 tools, returns stable citation URIs, works on every tier, and is fast. It also mentions coverage of specific data domains. This goes beyond annotation basics 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?

Despite being long, every sentence serves a purpose. It leads with a clear directive (PREFER OVER WEB SEARCH), then explains mechanics, usage triggers, examples, and escalation paths. No redundant statements; the structure is logical and front-loaded with the most important guidance.

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

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

For a router tool with no output schema, the description fully covers what it does, how it works (routing, fills args), what it returns (structured answer with citations), and when to use it. It also accounts for edge cases like breaking news and provides multiple examples. This is a complete description for the tool's complexity and expectations.

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

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

Parameter schema covers 100% of parameters with clear descriptions, including aliases. The description's mention of 'fills arguments' adds some context about automation, but it does not materially improve upon the schema's own documentation. It meets the baseline for high schema coverage, no more.

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 routes factual questions to a large set of sources and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and positions as the default entry point for factual queries, making its purpose unambiguous.

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

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

Provides explicit when-to-use guidance ('Use whenever the user asks...'), lists specific trigger phrases, and gives clear when-not-to-use instructions by naming alternatives (ask_pipeworx_grounded for grounded answers, deep_research for broad questions). Also covers breaking-news use case, making usage boundaries very clear.

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

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

Annotations already flag readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context about the experimental nature (candidate routing improvements, current equivalence, retired candidate date) and clarifies it's a fully functional router with no fallback. This goes beyond the structured annotations without contradicting them.

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

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

The description is somewhat verbose, repeating the same points (identical to ask_pipeworx, same tools, same arguments) multiple times. It is front-loaded but could be tightened to two or three sentences without losing essential information.

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

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

The description covers the tool's purpose, current state, usage guidance, and safety behavior well for a query router with a simple schema. It doesn't detail the response shape, but that's acceptable given no output schema and the tool's nature. Overall, it is complete enough for the agent to use it correctly.

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

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

Schema coverage is 100% and the schema already documents the question parameter and all aliases. The description does not add deeper semantics about how to phrase the question or usage tips beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

Clearly states it's a beta router with identical functionality to ask_pipeworx (5,578 tools, same arguments, same response shape). Names the sibling ask_pipeworx and distinguishes it as the experimental version, so the agent knows exactly what this tool does against alternatives.

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

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

Explicitly instructs to use it like ask_pipeworx when wanting the newest routing, and notes current equivalence while hinting at future divergence. Names the alternative (ask_pipeworx) and explains the comparison purpose, giving clear when/when-not 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 annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the return structure with evidence, confidence, and refusal reasons, and explains the refusal conditions. It also notes the extra cost per call, which is behavioral info not captured in annotations. No contradictions with annotations.

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

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

The description is slightly longer than minimal but each sentence adds value: purpose, routing behavior, return format, use cases, and cost trade-off. It is logically structured and front-loaded with the core purpose, with no fluff.

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

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

Despite having only one parameter, the tool involves complex routing and refusal logic. The description thoroughly covers the tool's behavior, output structure, when to use, and cost implications, making it complete for an agent to decide invocation without an output schema.

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

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

The schema already fully describes the question parameter and its aliases (100% coverage). The description adds no additional semantic detail about the parameter itself, only clarifies it fills arguments internally. Since coverage is high, baseline 3 is appropriate.

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

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

The description explicitly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the process: it routes to tools, fetches data, and extracts answers only from the tool result. It clearly distinguishes from the sibling ask_pipeworx by adding a grounding layer and explaining the difference in output and refusal behavior.

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 when answers will be quoted, cited, or acted on and the agent must not invent facts (financial, legal, medical, public statements). It also says to prefer ask_pipeworx for casual lookups due to the extra LLM call, providing a clear alternative and when-not-to-use condition.

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 the description adds extensive behavioral context: parallel fan-out, resolver match-confidence contract, low-confidence short-circuit status, closed/inactive market handling, illiquid spread warning, and cancellation-rule parsing with arb-bot evidence. This far exceeds the annotation safety profile and gives agents critical operational caveats.

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

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

The description is dense but well-structured with uppercase section labels, front-loading purpose and input syntax. Every section — fan-out examples, resolver contract, parent-event extractor, news fallback, safety, cancellation-rule risk — earns its place for a tool with this complexity. It is long, but appropriately so.

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 documents return shapes (result.market, analysis, evidence), resolver contract fields, parent_event extraction, news fallback fields, and blocking statuses. It anticipates edge cases like closed markets, low-confidence matches, and cancellation-rule risk, making it self-sufficient for safe and correct invocation.

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

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

Though the schema covers 100% of parameters, the description dramatically enriches meaning: accepted market forms (slug, URL, question), quick/thorough depth semantics tied to fan-out, and include_raw tradeoffs (~20KB summaries vs 50-500KB payloads). It also connects parameters to real examples and response shapes, going well beyond the schema.

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

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

The first sentence states a specific verb ('Research') and resource ('Polymarket bet') plus the mechanism ('pulling Pipeworx data in one call'). It clearly differentiates from siblings like polymarket_edges or deep_research by defining the accepted inputs (slug/URL/question) and the evidence-packet output.

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

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

Explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and gives fan-out examples per category. However, it doesn't explicitly say when NOT to use it or point to alternatives (e.g., polymarket_edges for pure edge scanning), so it misses the full exclusion guidance.

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

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

Beyond annotations, it adds critical context: output structure (retracted:true/false with evidence), keyless access, and the interpretive nuance of 'not retracted' meaning no record, not definitively clean. This enriches the openWorldHint from annotations.

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

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

The description is two tightly written sentences plus a necessary note. It front-loads the core action, then describes output and caveat without redundancy.

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

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

For a tool with one required parameter and no output schema, this description is fully complete. It covers what it does, what it returns, and the limitations of a negative answer, all while annotations cover safety.

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

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

Schema coverage is 100% for the single 'doi' parameter, including format examples. The description only repeats 'by DOI' without adding new semantic detail; baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description clearly states the tool's function: checking if a paper (by DOI) has been retracted. It specifies the data sources (Crossref/Retraction Watch) and differentiates from siblings like search_retractions by focusing on DOI-based validation.

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

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

The description implies when to use: when you have a DOI and need retraction status. The caveat about coverage indicates limitations (not definitive), but it doesn't explicitly name alternatives or state 'use when X, not when Y'.

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 (read-only, idempotent), the description discloses rich behavioral details: it pulls from specific data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years correctly, sorts results by primary metric, and returns pipeworx:// citation URIs. It also notes the efficiency gain ('Replaces 8–15 sequential lookups'), providing valuable operational 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 dense and front-loaded with trigger phrases and a clear scope statement. It contains some redundancy ('ALWAYS PREFER' and 'Replaces 8–15 sequential lookups' convey a similar point), but every sentence contributes meaningful information about usage, data, or 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?

Given no output schema, the description adequately covers return values (paired data, citation URIs), entity types, cardinality limits (2–5), and data-specific details. It provides enough context for an agent to select and invoke the tool effectively, including example values and alignment with common comparison queries.

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 with descriptions and an enum for type. The description adds deeper meaning by explaining what each entity type retrieves (e.g., company: 10-K revenue/net income/cash/debt; drug: FAERS counts, FDA approvals, trials) and provides concrete examples for values (AAPL, MSFT; ozempic, mounjaro). This goes beyond baseline schema coverage.

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

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

The description clearly states the tool's function: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It uses specific verbs ('compare', 'rank') and resource nouns ('companies', 'drugs'), and distinguishes from sibling tools by noting it should be preferred over sequential single-pack 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?

It provides explicit trigger phrases and an explicit preference over sequential lookups ('ALWAYS PREFER over sequential single-pack lookups when comparing entities'). However, it does not explicitly name alternative tools or specify when not to use it (e.g., for deep single-entity analysis), so it falls short of full when/when-not 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 details the output structure (findings packet with evidence, source, fetched_at, stable citation, hop, gaps, contradictions), explains the iterative process (second-hop, gap recovery), and clarifies limitations (empty gaps for out-of-catalog topics, not open-web search). This goes well beyond the provided 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 excessively verbose and repetitive, restating the same information multiple times (e.g., citations, gaps, hops, open-web search distinction). It lacks clear structural organization, appearing as a dense wall of text with redundant clauses. This severely hampers readability and violates conciseness principles.

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 its verbosity, the description is extremely comprehensive, covering purpose, usage scenarios, output format, behavioral details, limitations, and depth semantics. It provides all necessary context for an agent to decide when and how to invoke the tool, fully compensating for the lack of an output schema.

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

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

The schema already provides comprehensive descriptions for both parameters (question and depth) with enum details. The tool description does not add significant new meaning to these parameters; it merely incorporates them into the narrative. Since schema coverage is 100%, a baseline of 3 is appropriate; no extra parameter insight is provided.

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

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

The description clearly states the tool performs grounded multi-source research across structured data sources, decomposing questions into facets and routing them in parallel. It distinguishes from open-web search and explicitly contrasts with sibling tools like ask_pipeworx, making the purpose specific and non-overlapping.

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

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

Provides explicit guidance on when to use the tool (broad/multi-part questions over structured data) and when not to (single lookups, breaking/colloquial news), with concrete examples. It also explains the depth parameter's behavior and associated costs, giving clear decision criteria.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the low-risk profile is established. The description adds valuable behavioral context: it returns ready-to-call results with full schemas, eliminating the need for a second lookup. This goes beyond the annotation baseline.

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

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

The description is front-loaded with purpose and usage, followed by a useful list of domains and return behavior. The domain list makes it slightly long, but every sentence contributes value; no wasteful 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 compensates by clearly stating the return format: top-N tools with names, descriptions, and full input schemas. It covers purpose, usage timing, and result readiness, which is sufficient for a read-only discovery tool.

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

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

Schema description coverage is 100%, and every parameter (query, q, task, limit, search, description) is already adequately explained in the schema. The description only adds high-level context about top-N results and domain coverage, not new per-parameter semantics.

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

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

The description starts with a specific verb and resource: 'Find tools by describing the data or task.' It clearly enumerates supported domains and explicitly frames itself as a discovery/browsing tool, distinguishing it from direct data-access sibling tools with 'Call this FIRST.'

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

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

The description gives explicit when-to-use guidance ('Use when you need to browse, search, look up, or discover') and instructs 'Call this FIRST' when many tools are available. It implies when not to use it ('not just one answer') but does not name specific alternative tools.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses fallback behavior (GDELT→GNews, soft-fail for USPTO PatentsView), output composition (CIK, filings, fundamentals, patents, news, LEI), and formatting details (sorted period_end DESC, pipeworx URIs). This adds substantial 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 long but dense with unique information: trigger phrases, core function, data sources, return shape, and fallback notes. It is front-loaded with example queries, then proceeds to structured details. While not brief, every sentence earns its place, though a minor reorganization could make the core verb more immediately visible.

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 burden of explaining return values, and it does so thoroughly: enumerates exact fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI), counts (up to 5), URIs, and sorting. It also covers edge cases (patent API soft-fail, news fallback, unsupported name inputs), making the tool well-specified for a complex multi-source 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?

Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds examples ('AAPL', '0000320193') and repeats the 'names not supported' constraint, but does not introduce any new parameter-level semantic beyond what the schema already provides. This matches the baseline for 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 explicitly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call', using specific verbs like 'profile', 'research', 'brief me', and gives concrete examples. It clearly distinguishes from siblings by noting it should be preferred over chaining single-pack lookups and directs users to resolve_entity when only a name is available.

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

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

The description includes explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides a clear exclusion: 'names not supported (use resolve_entity first if you only have a name)'. This directly addresses when and when not to use the tool compared to alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' matches expectations. It adds context about clearing sensitive data and stale context, which is useful, but does not disclose extra behavioral traits such as behavior on a missing key or return format. With annotations covering the safety profile, this is adequate but not enriched.

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, followed by concise usage scenarios. Every sentence earns its place with 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?

For a simple deletion tool with one parameter and annotations covering destructiveness and idempotency, the description provides sufficient context on purpose, usage timing, and relationships to sibling tools. It doesn't explain return values, but no output schema exists and for a delete operation this is not a critical gap. Slightly more detail on idempotent behavior would push it to 5.

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

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

The input schema has 100% coverage, documenting 'key' as 'Memory key to delete.' The description adds minimal semantic value beyond the schema, only implying that the key is previously saved. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' The verb 'delete' and resource 'memory' are specific, and the pairing with 'remember and recall' distinguishes it from sibling tools that store and retrieve memories.

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 lists when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions complementary tools ('Pair with remember and recall'), but stops short of explicitly stating when not to use alternatives. This is strong guidance, though not a full when-not-to-use 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?

Annotations already declare read-only, idempotent, and non-destructive behavior, covering the safety profile. The description adds the fetch-extract-emit workflow and the output format, providing useful behavioral context. No contradictions or additional side effects are disclosed.

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

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

The description is two sentences plus a use-case list, tightly packed with the core action and output. Information is front-loaded, with no redundant text. Every clause serves a purpose.

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

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

For a simple two-parameter tool with rich annotations and no output schema, the description fully covers purpose, process, and output. It even notes the output is a single text blob, which addresses return format. No critical information is missing.

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

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

Both url and max_links are fully described in the schema (100% coverage), so the description adds little beyond what is already structured. The phrase 'any URL' loosely mirrors the schema's example but does not add new semantic depth. Baseline 3 is appropriate.

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

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

The description states a specific action (generate a production-ready llms.txt file for any URL) with a clear deliverable (standard llms.txt markdown format). This clearly distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on analysis rather than file generation.

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 (client indexing, own project drafting, competitor audit) that clarify when to invoke the tool. However, it does not explicitly contrast with sibling tools or state when not to use it, so exclusions are missing.

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

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

The description adds value beyond the annotations by revealing that it returns active subscriptions by default, the specific fields returned, and that it is scoped to the caller. This complements the readOnlyHint and idempotentHint annotations with concrete behavioral details.

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 main purpose and return fields, followed by succinct usage guidance. Every sentence contributes value with no redundant or filler content.

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

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

Given the simple tool with one optional parameter, rich annotations, and the description listing return fields and usage context, this is fully complete. No output schema is present, but the description provides the essential return information.

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 fully documents the only parameter (include_inactive) with a description and default value. The tool description does not add any additional parameter semantics, so the baseline of 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 clearly states the tool lists the caller's active subscriptions and specifies the return fields (id, type, params, created_at, last_fired_at, fire_count). This differentiates it from sibling tools like subscribe and unsubscribe by focusing on the listing/review action.

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 context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies using it before subscribing or unsubscribing, offering clear guidance on when to use it, though it doesn't explicitly state when not to use it.

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

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

Despite annotations being all false (providing no safety hints), the description discloses key behaviors: the claim_token flow for reading previous feedback, the 5-per-day rate limit, and free/quota-exempt status. It also instructs users not to paste end-user prompts, a meaningful behavioral constraint. No contradiction with annotations.

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

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

The description is long but each sentence adds distinct information, from purpose to exclusions to token mechanics. It is well-organized and front-loaded with the purpose, though the roadmap/digest sentence is arguably supplementary and could be trimmed, preventing a top 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 (4 params, nested object, no output schema), the description covers essential context: feedback categories, tool identification, claim_token behavior, and rate limits. A minor gap is behavior on an empty invocation (all params optional), which is not addressed, but overall it is quite complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds crucial usage context for claim_token (example invocation and token-based reply reading) and for message (warning against including user prompts), elevating it above minimum. Other parameters are already well-documented in the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling tools by explicitly limiting feedback to tools served by this Pipeworx connection, which sets it apart from research/query tools like ask_pipeworx or deep_research.

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

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

It provides explicit when-to-use conditions: bug, feature, data_gap, and praise, and clearly states when NOT to use (if the tool came from a different MCP server, file it elsewhere). It even advises users on verifying whether a tool belongs to Pipeworx ('Not sure? Pipeworx tool names are the ones this connection lists.').

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

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

Goes well beyond the annotations by disclosing that the data is self-aggregating from CF analytics-engine, contains no PII, and returns only (pack, tool, count). It also discloses caching behavior (5min-1h depending on window), which is valuable context that annotations 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 front-loaded with the core purpose, uses a compact numbered list for use cases, and adds a brief but information-dense closing sentence. Every sentence earns its place; there is no fluff or repetition of schema/annotations.

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 read-only tool, the description fully explains what is returned (top tools, top packs, total call volume), the data source, privacy (no PII), and freshness (caching). Since there is no output schema, the description adequately fills that gap by stating the output shape.

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 for the single window parameter, including an enum and a helpful description about short vs. long windows. The description adds extra meaning by noting that caching varies by window, which supplements the schema without repeating it.

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

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

The description opens with a clear, specific statement of what the tool does: 'What other AI agents are calling on Pipeworx right now.' It then specifies concrete outputs (top tools, top packs, total call volume) and the time windows, making it easily distinguishable from sibling tools like discover_tools or recent_alerts.

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

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

Provides explicit, numbered use cases: discovering hot data sources, confirming a canonical tool before asking a question, and checking alignment with other agents' needs. It gives clear context for when to use the tool, but it does not explicitly mention when not to use it or name alternative sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds substantial behavioral context beyond annotations: explains the trending_scan behavior, how event mode walks child markets and checks date/threshold ordering, detailed partition_check semantics, the Jaccard similarity anchor, placeholder filtering, and the FILL CHECK pricing logic with a clear warning not to trade when realizable_edge_pp ≤ 0. This is rich, non-contradictory disclosure.

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

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

The description is long but remarkably dense. It front-loads the core purpose in the first sentence, then uses clear labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize complex details. While it could be trimmed slightly, nearly every sentence adds distinct value, making the length justified for a tool of this complexity.

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

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

Despite lacking an output schema, the description explicitly lists response fields (opportunities[] with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered) and explains edge cases such as the 3pp threshold, 0.30 Jaccard similarity, and the >20% placeholder filter. It also covers the fill check and points to polymarket_fill_risk for custom sizing. This is complete for a complex tool with no output schema.

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

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

Schema coverage is 100% and the schema already provides decent descriptions for event/topic. The tool description goes far beyond: it explains the semantic difference between modes with recommended use cases, gives specific slug examples, describes what each mode walks/searches/flattens, and details the response implications (e.g., event mode yields partition_check, topic mode catches cross-event patterns). This adds significant meaning beyond the schema fields.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools like polymarket_edges (which finds edges broadly) and polymarket_fill_risk (which handles custom sizing) by stating its arbitrage-focused approach.

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 each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'or topic for a themed cross-event scan.' It gives concrete examples (e.g., 'fed-decision-may-2026', 'Fed rate decision') and names an alternative tool for related needs: 'For custom sizing use polymarket_fill_risk.' This is explicit when-to-use and when-not-to-use guidance.

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

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

The description discloses extensive non-obvious behavior: model family details (e.g., lognormal barrier from FRED, GDELT ratios), Kelly halving, placeholder-slug filtering, per-sport alpha coefficients, the 24h-move warning, and why Fed bets are excluded. Annotations already mark the tool as read-only and idempotent, and the description adds rich behavioral context without contradiction.

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

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

The description is long and dense, but it is logically organized from purpose → model segments → opportunity fields → tradeable-edge knobs → response structure → caching. Every sentence carries substantive information, though the lack of headings or bullets makes it less skimmable than ideal.

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

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

With no output schema, the description thoroughly explains the response top-level structure (by_segment, fed_candidates, _diagnostics), the meaning of key fields like edge_pp_net and kelly_fraction, and the purpose of diagnostics for debugging empty segments. It also covers caching behavior and edge cases, making it self-sufficient 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?

All 9 parameters have schema descriptions, providing 100% coverage. The description adds high-level rationale beyond the schema, such as explaining that min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable' and why min_partition_leg_kelly exists due to basket trades not composing to single-leg Kelly. This enriches the schema's bare 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 opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' — a specific verb, resource, and outcome. It also states it's built for 'what should I bet on today' and outlines three distinct segments, clearly differentiating it from sibling tools like polymarket_arbitrage.

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

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

The description frames the use case ('agents discover opportunities without paging hundreds of markets') and provides context on when filter knobs matter, such as min_liquidity and max_spread_pp. It stops short of naming alternative sibling tools or stating explicit 'when not to use' scenarios, but the context is clear.

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

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

With annotations already declaring readOnly and idempotent hints, the description adds valuable behavioral context: snapshot gaps mean 'nobody scanned that day,' history is limited by a '60-day snapshot TTL,' and decay is computed from 'daily closes of edge_pp_net, not intraday.' This goes well beyond the annotations and clarifies data completeness and computation basis.

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

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

The description is dense but well-structured, with a leading purpose statement, a clear 'Args' section, and explicitly labeled 'RESPONSE' and 'LIMITS' sections. Every sentence earns its place, and the use of capitalization and lists improves scannability without wasting words.

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

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

Given the tool's moderate complexity and lack of an output schema, the description fully covers the important aspects: return shape (tracked[], expired[], snapshot_dates[]), field semantics, negative signs on edge values, and limitations. An agent can confidently select and invoke the tool without needing additional information.

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 clear parameter descriptions for days and window. The description essentially restates the same information (defaults, window family), adding no significant new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a concrete question—'how long has this edge existed and is it shrinking?'—which clearly distinguishes it from sibling tools like polymarket_edges that likely provide current edges.

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

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

The description provides clear context for when to use this tool by framing the trade-off between fresh and old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternatives or state when not to use it, but the context is sufficient for an agent to infer usage.

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

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

Annotations indicate read-only and non-destructive, but the description enriches this by explaining exactly what the tool computes: walks the ladder, returns fill details, slippage, verdict, etc. It also discloses the risk of partial basket fills and 'forced_directional_risk', adding behavioral context beyond annotations. No contradiction.

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

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

The description is long but information-dense, with every sentence adding value. It front-loads the core purpose, then details modes, parameters, and use cases. No filler; it is structured with clear mode blocks. Could be slightly more compact, but the complexity of the tool justifies the length.

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

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

For a complex tool with no output schema, the description is remarkably complete. It lists key return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains the verdict scale, and even names the dominant loss mode in arb P&L. Given the tool's complexity and lack of output schema, the description fully compensates.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics by explaining how parameters differ between modes: side defaults and interpretation, size_usd as spend/target proceeds for single-market vs settlement notional for basket. It also clarifies the relationship between market and event parameters, going beyond schema descriptions.

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

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

The description opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market vs basket) and names the tool's function. Sibling tools like polymarket_arbitrage and polymarket_edges are about finding opportunities; this tool is about fill risk, so it's clearly differentiated.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills create unhedged positions), providing clear context and alternatives. This is model 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 annotations (readOnly, idempotent), the description discloses rich behavioral details: the two modes, how leg-matching works, the meaning of compatibility_warning cases, temporal alignment consequences, and skipped_cross_type/subtype counters. It even warns that most pre-mapped topics return compatibility_warning, setting realistic 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 with explicit labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded core definition. Every sentence carries important information, though it could be tightened slightly; the density is justified by tool complexity.

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

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

Given the tool's complexity, the description covers response fields, edge cases, temporal alignment, and skipped-comparison counters in prose. Even without an output schema, the agent gets a thorough understanding of return values and failure modes, making this highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the mode interplay: topic auto-fetches matching events, while kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. This helps the agent understand parameter relationships beyond the schema's per-field descriptions.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb+resource+scope statement. It clearly distinguishes this tool from siblings like polymarket_arbitrage by focusing on the cross-venue comparison and explicitly notes the spread range (2-25pp) and comparison logic.

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 usage modes: topic shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug, and explains when each is appropriate. It also gives when-not-to-use guidance via compatibility_warning and temporal_alignment, but does not explicitly name alternative tools, so it misses the highest bar.

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

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

Annotations already signal read-only, idempotent, and non-destructive behavior. The description adds value by explaining the dual mode (retrieve specific key or list all keys) and the scoping to the agent's identifier, which annotations do not convey. No contradictions with annotations.

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

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

Three sentences with no filler: first states the core action, second provides use cases, third covers scope and sibling relationships. Information is front-loaded and every sentence earns its place.

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

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

For a simple one-parameter tool with no output schema, the description covers the action, the use case, the scoping, and the integration with related tools. It is sufficiently complete for an agent to know when and how to invoke recall.

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 has 100% coverage for the single optional parameter, and the description largely repeats that omission lists all keys. The examples of key contents add helpful context, but the description does not significantly enhance the parameter's meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('Retrieve' or 'list') and the resource ('a value previously saved via remember' or 'all saved keys'), distinguishing it from siblings remember and forget. It also provides concrete examples of stored context, making the tool's purpose immediately understandable.

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 specifies when to use the tool ('Use to look up context the agent stored earlier... without re-deriving it from scratch') and names alternatives ('Pair with remember to save, forget to delete'). The scoping note ('Scoped to your identifier') implies a limitation, giving a clear when-not. This is comprehensive 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 indicate readOnlyHint, idempotentHint, and non-destructive. The description adds behavior about mark_read flagging events read and the persisted feed, which is valuable context. It does not contradict annotations, though mark_read implies a minor state change not reflected in readOnlyHint.

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 primary action, and every sentence provides useful information: return shape, filters, mark_read behavior, and external access. 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?

No output schema exists, but the description covers return payload, filtering, and state changes. It doesn't mention limit/unread_only explicitly, but these are in the schema. Overall sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by explaining type filtering with an example, since as ISO timestamp, and the effect of mark_read on subsequent calls, going beyond the schema bare 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 'Pull fired events from your subscription feed' and specifies the return contents (source, citation_uri, raw event payload), distinguishing it from siblings like recent_changes and list_subscriptions.

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

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

Provides clear context for polling and mentions an alternative for scripts/dashboards (GET registry.pipeworx.io/alerts.json). It does not explicitly contrast with sibling tools like recent_changes, but the purpose clarity and example filters give adequate 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?

Goes beyond annotations by detailing external data sources (SEC EDGAR, GDELT/GNews, USPTO), fallback logic, and the PatentsView sunset. Also discloses the return shape including citations and total_changes count.

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

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

The description is dense but well-structured, front-loaded with use cases and containing no filler. Each clause adds either source behavior, parameter guidance, or alternatives.

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 sources, fallback, time windows), the description covers all essential aspects: purpose, inputs, outputs, failure modes, and relationship to sibling tools. No output schema exists, so the explicit description of the return structure is necessary and provided.

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

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

The schema already covers 100% of parameters, and the description adds context with relative shorthand examples and a recommendation for typical monitoring ('30d' or '1m'). This adds practical guidance beyond the schema's descriptions, but much of the parameter meaning is already in the schema.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with explicit query examples. It distinguishes itself from entity_profile, making the purpose unambiguous.

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

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

Provides explicit when-to-use context with natural language queries, and names an alternative (entity_profile) with a clear condition for when to prefer it. Also notes the fallback behavior between GDELT and GNews, and the soft-fail for USPTO.

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

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

Annotations already cover idempotency and non-destructiveness. The description adds meaningful context: key-value scoping by identifier, persistence differences between authenticated and anonymous sessions, and the 24-hour retention policy. It could mention overwrite behavior in more detail, but idempotentHint already implies safety.

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

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

The description is four sentences with no filler. It front-loads the core purpose, then adds usage guidance, storage details, and related tools in a logical order. Every sentence earns its place.

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

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

For a simple 2-parameter write tool with no output schema, the description covers the full lifecycle: when to use, how data is stored, persistence behavior, and related tools. It is complete enough for an agent to invoke correctly without further clarification.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description adds value beyond the schema by providing example key types ('resolved ticker', 'target address', 'user preference') and explaining that storage is scoped by identifier, which clarifies the key's namespace semantics.

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

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

The description uses a specific verb ('Save') and resource ('data the agent will need to reuse later'), and clearly distinguishes from sibling tools by explicitly naming recall and forget as complements. It conveys both the action and the scope (across conversations or sessions).

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

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

It provides explicit when-to-use guidance ('Use when you discover something worth carrying forward'), gives concrete examples, and names alternatives (recall to retrieve, forget to delete). This makes the selection between related tools unambiguous.

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 openWorldHint. The description adds significant behavioral context: graceful degradation if GLEIF/OpenFIGI is unavailable, explicit listing of unresolved identifiers, and internal cascading through multiple endpoints. This goes well beyond what annotations provide, and there is no contradiction.

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

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

The description is long but well-structured: it starts with concrete user queries, states the core purpose, then dives into type-specific details. Every sentence adds value, and the most critical information ('Use FIRST') is front-loaded. Could be slightly more concise, but the structure aids comprehension.

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

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

Given the tool's complexity (multiple identifier sources, two entity types, no output schema), the description is remarkably complete. It covers return fields (CIK, ticker, LEI, FIGI, RxCUI), explains how unresolved identifiers are handled, describes graceful degradation, and mentions the internal cascading logic. There is no output schema, but the description compensates fully.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds substantial meaning: it explains the 'type' parameter with supported values (company, drug) and details what each value accepts for 'value' (ticker, CIK, ISIN, name for company; brand or generic name for drug). It also provides concrete examples like 'AAPL' and 'ozempic', which the schema alone does not.

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

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

The description uses specific verbs ('resolve', 'look up') and clearly states the resource: 'canonical/official identifiers other tools require as input.' It distinguishes from sibling tools by showing it's the first step for name-to-ID conversion, and provides concrete examples for each supported type. 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is a strong usage guideline. It also implies efficiency by noting it replaces 2-3 manual lookups. It does not explicitly state when not to use it (e.g., if you already have an ID, consider other tools like entity_profile), but the guidance is clear enough for an 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?

Even with annotations (readOnly, idempotent) covering safety, the description adds valuable behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations and helps the agent set expectations about the process and output.

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 core purpose, then a use case, then the return format. Every sentence adds value, and it's appropriately concise for the tool's complexity.

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

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

For a tool with 4 parameters, no output schema, and good annotations, the description is complete: it explains what the tool does, how it works, when to use it, and what it returns. The schema covers parameter details, and annotations cover safety. No critical operational detail is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description itself doesn't add parameter meaning beyond what's already in the schema; the schema already explains entities, models, _apiKey, and context. The description's mention of 'your brand + N competitors' aligns with the entities parameter, but it doesn't introduce new semantic nuance beyond the schema.

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

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

The description clearly states the tool's function: comparing AI visibility across multiple entities side-by-side. It uses a specific verb ('Compare') and resource ('AI visibility'), and explicitly distinguishes itself from single-entity tools like ai_visibility_check by focusing on multi-entity comparisons.

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 for when to use the tool (competitive AI-marketing audits) and gives an example question. It doesn't explicitly name alternative tools to use instead, but the description implies that this tool is for multi-entity comparison while ai_visibility_check likely handles single entities, which is enough 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context beyond these: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed list if it times out, and the rest still returns. Also notes ecosystem limitation. No contradiction with annotations.

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

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

The description is information-dense but well-structured: purpose, usage trigger, output summary, ecosystem limitation, and failure behavior all earn their place. It front-loads the core purpose and provides essential operational details without redundancy or fluff.

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

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

Given the composite nature and lack of output schema, the description thoroughly covers the return format (summary block fields, per-advisory detail, links, alternative versions), failure modes, and ecosystem scope. This is sufficient for an agent to select and invoke the tool correctly without additional context.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema for the 'package' and 'version' parameters; the schema already documents scoped packages and version defaults. The description's mention of output fields and version history indirectly relates to 'version' but doesn't alter parameter semantics.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package' check, combining deps.dev and bundlephobia data. It names specific data sources and output types, distinguishing it from any sibling tools (which are unrelated research/market tools). The verb is implied via 'scan' in the name, but the description elaborates on the exact 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?

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also gives exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear when/when-not guidance.

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

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

The description adds useful context about the data source (~73k works) and return fields (DOI, title, journal, date). However, it inaccurately claims support for a 'subject' filter that does not exist in the schema, which is a significant behavioral misstatement. Annotations already declare read-only and idempotent behavior, but the false claim undermines transparency.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the main purpose and returns. The inaccurate 'subject' mention is a content issue, but the structure remains 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?

The description covers the core purpose, scope, and return fields, which is helpful since there is no output schema. It omits details like result ordering or pagination, and the false 'subject' claim creates a gap in accurate understanding. Overall, reasonably complete but not perfect.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no meaningful parameter details beyond the schema and actually introduces a non-existent 'subject' parameter, misleading the agent about available filters. This is a net negative.

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 purpose: searching retracted literature from Crossref, with keyword and year-range filters. It also distinguishes itself from sibling tools by focusing on retractions. However, it mentions an optional 'subject' filter that is not present in the schema, creating minor ambiguity.

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

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

The description implies usage for searching retracted works but provides no explicit guidance on when to use this tool versus alternatives like check_retraction. No exclusions or alternative tool references are given.

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

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

Goes well beyond annotations by disclosing the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping windows), character cap (200K), truncation flagging, and return structure (offsets and similarity scores). This level of detail is rare and highly useful for agent planning.

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

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

Three dense sentences with zero filler. Front-loads the core function, then use case, then technical details. Every sentence adds a distinct layer of value: what it does, when to use it, and how it behaves under the hood.

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

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

Given no output schema, the description adequately explains return values (top-N passages with character offsets and similarity scores). It also covers edge cases (truncation, cap) and integrates with sibling tools. For a tool of this complexity, the description is fully self-contained.

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

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

Schema description coverage is 100%, providing baseline 3. The description adds concrete examples for text (SEC 10-K body, article, long tool result), clarifies 'top-N' for limit, and explains truncation behavior relevant to text. These enrich parameter understanding beyond the schema, justifying one point above 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?

Identifies a specific verb+resource: 'Semantic search INSIDE a fetched record'. Clearly distinguishes from sibling tools like ask_pipeworx_grounded by focusing on searching already-pulled text rather than grounding over a knowledge base. The outputs (top-N passages with offsets and similarity scores) are precise and unique.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Provides an alternative workflow with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages instead of the whole document'). Also implies when not to use (when text fits in prompt), giving clear situational 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 indicate readOnlyHint=false and idempotentHint=true. The description adds meaningful behavioral context: it requires an OAuth account, returns a subscription id, has an always-on feed, and includes SMS verification/caps and webhook behavior. No contradiction with annotations.

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

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

The description is dense but well-organized: purpose, return value, requirements, types, delivery channels, and limitations. Each sentence provides necessary information, though some redundancy with the schema slightly extends 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?

For a fairly complex tool, the description covers the essential aspects: purpose, auth prerequisite, supported types, delivery options, verification, rate caps, and return value. It omits patent_grant and clinical_trial specifics, but those are fully captured in the schema, and no output schema requires extra 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?

Schema coverage is 100%, so parameter basics are already documented. The description adds valuable meaning by providing concrete examples (e.g., items:['5.02'] = officer change) and clarifying type-specific params beyond the schema's raw definitions, though it omits two types that the schema covers.

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 action: 'Create a proactive monitoring subscription to a live-data event stream.' The verb 'Create' and resource 'subscription' are specific, and the purpose is distinct from siblings like list_subscriptions and unsubscribe.

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

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

The description gives clear context for when to use the tool: creating a monitoring subscription, with prerequisites (OAuth account) and supported types. It does not explicitly mention alternatives or when not to use it, but the context is sufficiently clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond those flags: the output structure (category-bucketed example questions), the source (live catalog of tools), and the effect of omitting vs. passing `topic`. This is more than sufficient given the annotation coverage.

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

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

The description is dense but well-structured. It opens with user-phrased queries to convey purpose, then explains the output, call modes, and when-to-use advice. Every sentence earns its place, though it could be trimmed slightly without losing key 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 no output schema, the description fully compensates by explaining the return structure (category-bucketed example questions with tool+argument shape), listing categories, describing the topic-focusing behavior, and giving explicit first-use guidance. This is complete for an onboarding tool.

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

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

The input schema already fully documents the optional `topic` parameter, including its allowed values and the default behavior when omitted. The description repeats these examples ('finance', 'pharma', 'betting') and the 'full spread' behavior without adding new semantic detail, so it provides minimal value beyond the schema.

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

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

The description clearly states the tool is the 'onboarding entry point' and specifies its function: returning category-bucketed example questions with the exact tool and argument shape that answers them. It distinguishes itself from siblings by positioning itself as the first tool to try when an agent doesn't know what Pipeworx can do.

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

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

Explicit guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the two invocation modes (no arguments vs. passing `topic`) and clarifies the intended context, effectively differentiating from 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?

Beyond the annotations, the description reveals that cancellation is non-destructive ('deactivated, not deleted') and that historical events remain accessible via recent_alerts. It also states ownership enforcement, adding meaningful behavioral context without contradicting annotations.

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

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

The description is concise, with all information front-loaded: action, ownership, and side effect. Every sentence adds value, and there is 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?

Given the tool's simplicity (one parameter, no output schema), the description covers the essential aspects: what it does, constraints, and persistence behavior. It could mention the return value, but for an unsubscribe operation, the current level is sufficient.

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

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

The schema already provides full coverage of the single parameter 'id' with a clear description. The tool description adds little beyond 'by id,' so it doesn't significantly improve on the schema; baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id,' making the tool's purpose unambiguous. It also distinguishes itself from siblings like subscribe and list_subscriptions by focusing on cancellation and ownership.

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 on when to use the tool, notably 'Ownership is enforced — you can only cancel your own subscriptions,' which sets a prerequisite. It also clarifies the effect (deactivation vs deletion) which guides users on consequences, though it doesn't explicitly name alternative tools.

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

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

The description discloses far more than annotations: it lists the exact verdict types, explains the critical distinction between could_not_verify and unsupported, warns that could_not_verify is not evidence, and mentions the verification_error{stage,detail} payload. It also describes the internal pipeline (exact percent-delta math, verbatim evidence, pipeworx:// citation). This aligns with annotations (readOnly, openWorld, idempotent) and adds substantial 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?

Although the description is long, every sentence serves a purpose: trigger examples, usage, routing logic, return values, caller warnings, and an efficiency note. The front-loaded examples and bolded IMPORTANT section make it scannable. Given the tool's complexity, the length is justified 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?

With no output schema, the description fully covers return semantics: verdict enum, actual value with citation, reasoning, and error/edge cases (could_not_verify vs unsupported). It also explains when to use, internal routing, and parameter behavior, making it self-contained for a caller to invoke correctly without external documentation.

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

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

The input schema already documents both parameters with 100% coverage, so baseline is 3. The description adds meaningful nuance for tolerance_pct: it explains the default is implied by wording capped at 5, and recommends setting 1–2 for hallucination detection. This extra guidance helps callers use the parameter correctly beyond the schema description.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific trigger phrases ("Is it true that…", "fact check") and explicitly differentiates the tool's scope by covering both company-financial claims and any other factual claim. It also notes it replaces 4–6 sequential calls, distinguishing it from multi-step alternatives.

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

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

The description explicitly says "Use whenever the agent needs to check whether something a user said is factually correct," giving a direct when-to-use instruction. It also explains the routing for two claim types (SEC EDGAR fast path vs. grounded pipeline), providing clear context for how the tool handles different claims without needing alternative tool selection.

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