Hex Pm

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

Annotations already mark it read-only/idempotent, and the description adds important behavioral context: the default model is free, calling Anthropic requires a BYO API key and costs money, and the response structure is per-model plus combined. This exceeds the annotation baseline with cost and authentication 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?

Three sentences cover purpose, model selection/cost, return shape, and use cases without waste. The most important information is front-loaded, and every sentence adds distinct value.

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

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

With no output schema, the description clearly describes the return format (per-model {score, confidence, signals, raw_response} + combined view). It covers the main parameters and contextualizes the tool's purpose. Minor gaps like the structure of the combined view or what 'signals' contain prevent a 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% description coverage, but the description adds value by explaining that _apiKey is only needed if 'anthropic' is in models and is passed through to api.anthropic.com, and clarifies the default model behavior. This goes beyond the schema.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource (LLMs) and the scope (business/brand/product/topic). It distinguishes itself by describing a 0-100 visibility score per model, which is unique among the sibling tools, and lists concrete use cases.

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

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

It states when the tool is useful ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the choice of models (default free Workers AI vs BYO Anthropic key). However, it doesn't explicitly compare with sibling tools like scan_competitor_ai_presence or mention when not to use it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable context: routes to 5,347 tools across 1,393 sources, fills arguments, returns stable pipeworx:// citation URIs, and mentions 'one fast call' / 'works on every tier' — behavioral traits beyond what annotations provide.

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

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

The description is long but every section earns its place: routing preference, domain coverage, examples, default-status guidance, step-up alternatives. It's front-loaded with the most critical instruction. Slightly verbose toward the end ('For "what's the world saying about X"/breaking-news...') but overall dense with high-value information.

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

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

For a single-parameter question-routing tool with rich annotations (readOnly, openWorld, idempotent) and no output schema, this description is remarkably complete. It covers what the tool does, when to use it vs four alternatives, what sources it draws from, output format (structured with citation URIs), and performance characteristics. Minimal gaps.

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

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

Schema coverage is 100%, and the question parameter has a clear description plus five documented aliases. The schema does the heavy lifting here. The description adds domain examples but doesn't add new parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description starts with a highly specific statement: 'PREFER OVER WEB SEARCH for questions about current or historical data' and enumerates concrete domains (SEC filings, FDA, FRED/BLS, patents, real estate, etc.). It gives concrete example queries and explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Exceptionally clear guidance: 'START HERE for most questions — this is the default entry point' and explicit step-up rules for when to use ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part questions). Also covers breaking-news routing. Tells the agent when NOT to use 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds valuable context: it's a full working router (falls back to nothing), current state (no candidate active, retired 2026-07-26), and that results are compared against the stable router. It doesn't describe response format or any rate limits, but with annotations covering safety and the description clarifying the experimental nature, this is solid.

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

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

Two well-structured sentences with zero wasted words. It front-loads the core purpose (beta version, identical router), then explains the current operational state, usage direction, and fallback behavior. Every clause earns its place, and the temporal context (retirement date, comparison process) is dense with useful information without bloat.

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 universal router with full schema coverage and strong annotations, the description is nearly complete. It explains the beta status, current state (no active candidate), usage directive, and fallback semantics. The one gap is that it doesn't describe the response shape or return format, but given it mirrors ask_pipeworx exactly and the tool is a routing tool, this is reasonably covered by implication.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description adds no parameter-specific semantics beyond what the input schema provides. Baseline 3 is appropriate since the schema handles the heavy lifting, and the description's lack of param detail is acceptable given full 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 this is the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It explicitly differentiates itself from siblings (ask_pipeworx, ask_pipeworx_grounded) by clarifying it's the experimental variant with routing improvements. The scope is precise: same 5,347 tools, same response shape.

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

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

The description says 'Use it exactly like ask_pipeworx when you want the newest routing' which gives clear when-to-use guidance. It omits explicit when-not-to-use or alternative-naming beyond mentioning it matches ask_pipeworx exactly and is compared against the 'stable router'. It doesn't explicitly name ask_pipeworx_grounded as an alternative for grounded use cases, which would strengthen the 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=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral detail: it explains the refusal mechanism with explicit refusal_reason enum values and the extra LLM call cost ('Costs one extra LLM call vs ask_pipeworx'). This exceeds what annotations provide.

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

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

The description is dense but front-loaded with the core value proposition first. It packs return format, refusal types, cost tradeoff, and use cases in efficient prose. Slightly long, but every sentence earns its place — no filler or repetition.

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

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

Despite having no output schema, the description fully specifies the return structure including success and error variants with exact field names and enum values. The behavior (grounded extraction, refusal logic, cost) is comprehensively documented. Complete for a tool of this complexity.

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

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

Schema coverage is 100% with the question parameter well documented including all five aliases. The description reinforces natural-language input and explains the structured return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}), which adds meaning beyond the schema alone.

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 this is a 'hallucination-resistant answer mode for high-stakes reads' that 'EXTRACTS the answer using ONLY what the tool result contains.' It distinguishes from the sibling ask_pipeworx by positioning this as the grounded variant. The purpose is specific and clearly differentiated from its closest sibling.

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 ('whenever an answer will be quoted, cited, or acted on') with concrete high-stakes examples (financial verdicts, legal claims, medical lookups, public statements). Explicitly names the alternative: 'prefer ask_pipeworx for casual lookups.' This is exemplary 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 the read-only/idempotent annotations, the description discloses extensive behavior: low-confidence matches short-circuit with status:'low_confidence_match', closed markets return status:'market_closed_or_inactive', wide-spread markets carry tradeability:'illiquid_wide_spread', and news fallback fields (_fallback_attempted/_fallback_failed_reason) are documented. It also explains blocking routes and resolution-rule risk. This far exceeds the annotation baseline and adds critical 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?

Despite being long, the description is meticulously structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose. Each section contains dense, non-redundant information that an agent needs for correct invocation and interpretation. No sentence is wasted.

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

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

Given the tool's complexity, 3 parameters, and no output schema, the description is exceptionally complete. It covers input formats, classification taxonomy, fan-out examples, response shapes, resolver contract, parent event extraction, news fallback, safety statuses, and resolution-rule risk. This provides sufficient context to invoke the tool correctly and interpret results even 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 covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description's first sentence repeats the market parameter's accepted formats (slug, URL, question text), which is already present in the schema. It adds no extra meaning for depth or include_raw parameters, so it does not exceed the baseline.

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

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

The description names a specific verb and resource ('Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call') and clearly distinguishes from sibling tools like polymarket_arbitrage or validate_claim by targeting 'should I bet on X' queries. It also details the fan-out and response shapes, leaving no ambiguity about what the tool does.

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 provides usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly name alternatives or exclusions, but the provided guidance is clear and context-rich. It also gives examples of when to check resolution-rule risk, adding practical usage nuance.

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

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

Annotations cover read-only, idempotent, and non-destructive behavior. Description adds significant context: data sources (SEC EDGAR/XBRL, FAERS, FDA), fiscal-year handling, sorting by primary metric, and citation URIs in results—far exceeding the annotations.

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

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

The description is dense but every sentence earns its place—trigger patterns, data specifics, sorting behavior, performance benefit. It is well-structured and front-loaded with the most important usage 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?

Despite no output schema, the description explains return format (paired data + citation URIs), sorting order, entity count limits, and the distinction between company and drug types. It fully prepares the agent for invocation and interpretation.

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

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

Schema already has good coverage with enum and descriptions, but description elevates it by explaining what each type pulls (10-K financials, FAERS counts, trial counts) and gives concrete examples for values. It also clarifies constraints (2–5 entities) and distinct behavior per type.

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

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

Description explicitly defines the tool as a side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific query trigger patterns. It clearly distinguishes itself from sequential single-entity lookups by noting it replaces 8–15 such 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?

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lists concrete user intents (compare, vs, versus, which is bigger) and entity types, making the appropriate invocation 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial value beyond these: it explains the parallel 5,347-tool routing, the findings packet structure (verbatim evidence + confidence + source + fetched_at + citations), the never-invented gaps[] guarantee, second-hop iteration behavior by depth tier, contradictions[] flagging, semantic excerpting (not head-truncation), and expected latency (15-90s). This is rich behavioral context well beyond what annotations provide, and it does not contradict them.

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

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

The description is lengthy but every section earns its place given the tool's complexity. The structure flows logically: account requirements, what it does, when to use vs alternatives, tier mechanics, output format, performance. However, it could be tightened — the depth-tier mechanics are described twice (in prose and in the schema), and the pricing/account block at the start could be condensed. It's comprehensive rather than concise.

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

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

For a tool with no output schema and complex behavior, this description is a model of completeness. It specifies expected latency, output packet structure, gap-handling behavior, quoting/citation format, hop fields, contradiction detection, and semantic excerpting behavior. Nothing meaningful is left unexplained, and the description even handles the edge case where the topic isn't in the structured catalog (returns mostly empty gaps[]).

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

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

Schema covers 100% of parameters with descriptions. The tool description adds meaning beyond the schema: it explains what the depth parameter's values actually do behaviorally (quick=1 hop, standard=gap recovery+contradictions, thorough=paid+full iteration) and clarifies the question parameter's suitability (broad/multi-part questions are the intended use, single lookups should go elsewhere). This is genuine value-add, though the schema already does the heavy lifting.

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

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

The description is exceptionally specific: it names the verb (grounded multi-source research), the resource (1393 STRUCTURED data sources), and explicitly distinguishes from open-web search. It differentiates from siblings by naming ask_pipeworx directly and contrasting the one-call-parallel-tools architecture versus single-LLM-call alternatives. The 'compare X and Y' and 'ACME' examples make the purpose unmistakable.

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

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

The description provides explicit when-to-use AND when-not-to-use guidance: best for broad/multi-part questions over structured data, and explicitly states to use ask_pipeworx for single lookups or BREAKING/current-news topics. It even names the specific alternative (ask_pipeworx) and explains why (routes to live news APIs). It also discloses the account-tier dependency (paid needed for thorough) with a fallback ('use ask_pipeworx instead').

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: it returns top-N relevant tools with names, descriptions, and full input schemas including curated examples, and states results are ready to call directly without a second schema lookup. This goes beyond basic 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 well-structured with four purposeful sentences: purpose, when-to-use, return format, and strategic advice. The domain list is long but informative and earns its place by scoping the tool's coverage. No redundancies 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?

No output schema exists, so the description must explain return values and does so explicitly: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' Combined with the rich input schema and annotation coverage, this is complete for a discovery tool with a simple query parameter.

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

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

The input schema covers 100% of parameters with detailed descriptions, including the query aliases and limit. The tool description adds no additional parameter detail beyond restating that users describe data/task, which mirrors the query parameter. Baseline 3 is appropriate since 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 'Find tools by describing the data or task' with a specific verb and resource, and the domain list (SEC filings, FDA drugs, FRED, etc.) distinguishes it from action-focused sibling tools. It positions itself as a meta-tool for discovery, which is distinct from tools like ask_pipeworx or bet_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?

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use and when-not-to-use guidance, effectively differentiating it from tools that answer specific queries directly.

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

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

Annotations already mark readOnly/openWorld/idempotent/non-destructive, and the description adds valuable behavioral context beyond that: it fans out across multiple sources in one parallel call, limits recent filings to 5, soft-fails on the sunset USPTO PatentsView API, falls back from GDELT to GNews, and returns a structured set of fields. 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?

Although longer than minimal descriptions, every clause earns its place: user triggers, preference guidance, fan-out sources, return fields, limits, fallbacks, and input constraints. It is front-loaded with example phrasings and uses semicolons to compress structured return details without wasted words.

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

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

For a complex tool with no output schema, the description is remarkably complete: it enumerates the return categories (CIK, filings with URIs, fundamentals sorting, patents, news fallback, LEI), states limits (up to 5 filings), flags the soft-fail condition, and clarifies input constraints. An agent has enough to select, invoke, and interpret results.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces the value format (ticker vs zero-padded CIK) and the 'names not supported' constraint, but it does not add material semantics beyond what the schema already provides for the two parameters.

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

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

The description opens with concrete user phrasings and a crisp definition: 'full cross-source profile of a US public company in ONE parallel call.' It clearly specifies the verb (profile/brief/research) and resource (US public company via ticker or CIK), and differentiates itself from sibling tools by instructing to prefer it over chaining single-pack lookups and by deferring name resolution to resolve_entity.

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

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

The description explicitly states when to use the tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'), provides example triggers, and gives an exclusion: names are not supported, so use resolve_entity first. This gives clear decision guidance relative 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 doesn't need to repeat those. It adds minor context about clearing sensitive data, but goes no further in describing side effects, error behavior, or requirements. This is adequate given the annotation coverage, but not exceptional.

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

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

Two sentences, front-loaded with the action, then providing usage context. Every word earns its place with no redundancy or filler.

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

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

The tool is simple (one required parameter), has a full schema, and the description covers purpose, usage conditions, and relations to siblings. No output schema is present, but for a destructive delete operation the description plus annotations give sufficient context for an agent to use it safely.

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% ('Memory key to delete'), so the schema fully explains the only parameter. The description's mention of 'by key' adds no meaningful information beyond the schema. Baseline 3 is appropriate because the schema carries the burden.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly stating the action. It distinguishes from sibling tools like 'remember' and 'recall' by focusing on deletion/removal rather than storage or retrieval.

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 context is stale, the task is done, or you want to clear sensitive data') and advises pairing with 'remember' and 'recall', providing clear usage context and sibling relationships. It effectively guides selection among related 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 and destructiveHint=false. The description adds the operational detail that it fetches the page and extracts content, plus the exact output format (standard llms.txt markdown). This goes beyond the annotation hints 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 three tight sentences covering purpose, process, output, and use cases. No filler, front-loaded with the key verb and result.

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

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

The tool is simple (2 params, no output schema). The description compensates for the lack of output schema by describing the output as a single text blob ready for site-root placement. It could add error handling or limitations, but it's adequate for the tool's complexity.

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

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

Both parameters are fully described in the schema (100% coverage), so the description does not need to add much. The description implies the core parameter (url) but does not mention max_links; baseline 3 is appropriate since the schema carries the load.

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 the verb 'Generate' and the resource 'llms.txt file', with a specific scope ('for any URL'). Distinguishes from sibling tools by focusing on the llms.txt format and output, unlike other AI visibility/scanning tools.

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

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

The description provides three concrete 'Useful for' scenarios, giving clear context for when to use the tool. However, it does not explicitly name alternative tools or state when not to use it, which is a minor gap given the sibling list includes similar AI visibility 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, idempotentHint, and non-destructive. The description adds that the response is scoped to the caller's subscriptions, defaults to active only, and lists the exact fields returned. This goes beyond the annotations and explains what the agent can expect.

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

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

Two sentences with no redundancy. The first sentence states purpose and output, the second gives usage guidance. Well front-loaded.

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

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

The tool is simple with one optional parameter and rich annotations. The description provides return fields which substitutes for an output schema, and gives context for use with subscription management. Complete for this level of complexity.

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

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

The only parameter include_inactive is fully described in the schema with 100% coverage, including default behavior. The description does not mention the parameter, so no additional semantics are added.

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 lists the caller's active subscriptions, specifying the resource and scope. Distinguishes from sibling subscribe/unsubscribe by being the read-only listing tool. Also enumerates return fields.

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 to use this to review existing subscriptions before adding more or to find an id to cancel. This directly ties to sibling subscribe/unsubscribe actions, though it doesn't name them. Provides clear context for when this tool is appropriate.

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

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

Annotations provide no hints (all false), so the description carries the burden. It discloses rate limiting (5 per identifier per day), that it's free and doesn't count against tool-call quota, and that the team reads digests daily and uses signals for roadmap. This is useful behavioral context beyond structured metadata, though it could specify what 'identifier' means.

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

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

Every sentence earns its place: purpose in the first sentence, usage criteria, content guidelines, and operational details (rate limit, quota). No redundant or vague phrasing. The information is front-loaded and scannable.

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 feedback tool with no output schema and only three parameters, the description covers purpose, usage scenarios, behavioral constraints, and content expectations. It provides enough context for an agent to decide when to invoke and how to fill parameters correctly.

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

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

Schema coverage is 100% with clear descriptions for all three params, so baseline is 3. The description adds extra guidance on message content ('Describe the issue in terms of Pipeworx tools/packs, don't paste the end-user's prompt'), which goes beyond the schema by showing how to frame feedback. This pushes it 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?

The description states a specific action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates distinct use cases (bug, feature/data_gap, praise). It clearly differentiates from sibling research tools by describing a feedback channel that doesn't overlap with any other listed tool.

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also provides a negative guideline ('don't paste the end-user's prompt') and mentions rate limit/quota, giving complete context for when and how to use.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses meaningful behavioral traits: it is self-aggregating, derived from CF analytics-engine, contains no PII, returns (pack, tool, count), and is cached 5min-1h depending on window. This adds value by explaining data provenance, privacy, output shape, and caching behavior.

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

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

The description is well-structured and front-loaded. It opens with the core purpose, then provides a numbered list of use cases, followed by three short clauses on data source, PII, and return format, and ends with caching. Every sentence earns its place; no filler.

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

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

The tool has a single optional parameter, no output schema, and strong annotations. The description fully compensates by explaining the return content ('top tools, top packs, and total call volume'), the data format ('pack, tool, count'), and caching behavior. This gives an agent enough context to invoke it correctly and interpret results.

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

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

The schema already covers 100% of the parameter (window) with an enum and description. The tool description reinforces the meaning by embedding the window options and adds behavioral context: 'Cached 5min-1h depending on window.' The schema comment also explains shorter vs. longer windows, so the description and schema together provide rich semantic meaning.

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

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

The description clearly states the tool's function with a specific verb and resource: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This distinguishes it from siblings like discover_tools or recent_changes by focusing on aggregated agent call patterns.

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: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' It also contrasts window durations ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), but does not explicitly name alternatives or exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context: the partition filter for placeholder slugs, the semantic similarity threshold (≥0.30 Jaccard), the fill check against live CLOB depth, and the explicit warning that a realizable edge ≤0 means the overround is not tradeable. This goes far beyond the annotations and makes the tool's behavior fully transparent.

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

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

The description is long but every sentence earns its place. It uses clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose in the first sentence. Structure is logical: mode selection followed by operational details, response format, and risk caveats. No filler or repetition.

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

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

Given the tool's complexity (multiple modes, thresholds, placeholder filtering, fill checking) and lack of an output schema, the description is remarkably complete. It specifies the return structure (opportunities[], partition_check{...}), the fill check details, the semantic anchor threshold, and the partition filter behavior. It even mentions a sibling tool for custom sizing, covering the full decision 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?

Although schema coverage is 100%, the description enriches both parameters with examples and mode-specific semantics. It explains that `event` is for a specific Polymarket event slug, walks child markets, and computes a partition check, while `topic` is a seed question for cross-event scanning. It even provides example values ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal') and explains the difference between the two modes, adding meaning beyond the schema's basic 'single-event mode' and 'cross-event mode' descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (no-args scan, event, topic) and explains what each does, differentiating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance is given: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also recommends `event` for a specific market, explains why cross-event mode catches patterns single-event misses, and directs custom sizing to polymarket_fill_risk. This fully covers when and how to use each mode.

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, non-destructive), the description discloses many behavioral traits: the five model families, the 24h-move warning, the caching at KV level keyed on knobs, limitations of the Fed signal, and the 'rare-by-design' nature of concentrated longshots. This goes far beyond what annotations indicate, providing rich 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 long but every sentence carries unique information. It is well-structured with headings for segments and knobs, and the core purpose is front-loaded. However, the density and wall-of-text format make it slightly less scannable than ideal, warranting a 4 rather than a 5.

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

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

With no output schema, the description compensates by explaining the response top-level structure (by_segment, fed_candidates, _diagnostics) and why segments may be empty. It covers all 9 parameters, the model families, the caching, and the tradeable-edge logic. For such a complex tool, this is complete.

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

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

Despite 100% schema coverage, the description adds significant meaning. The TRADEABLE-EDGE KNOBS section explains why min_partition_leg_kelly exists (partition arbs always return parent-level kelly 0) and how min_liquidity/max_spread_pp should be used. Slippage_pp gets context about Polymarket's zero fees and typical 20-50bp costs. This clearly exceeds the parameter descriptions 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 opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes the tool from siblings like polymarket_arbitrage by emphasizing the Pipeworx data disagreement core. The 'built for' phrasing further clarifies its intended use case.

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

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

The description gives a clear when-to-use context ('what should I bet on today') and provides detailed knob guidance (e.g., 'Set to 5000 to drop thin-book opportunities'). However, it lacks explicit alternative-tool comparisons or when-not-to-use exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial context beyond these: snapshot data gaps, TTL limits, computation on daily closes, and the full response structure. There is no contradiction with annotations.

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

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

The description is dense but every sentence earns its place. Purpose is front-loaded, followed by clear sections for arguments, response structure, and limits. It is well-organized and contains no filler.

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

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

Even without an output schema, the description thoroughly documents the response fields (tracked[], expired[], snapshot_dates[]), their semantics, and edge cases (gaps, TTL). It covers calculation details and practical implications, making it fully usable by an agent.

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

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

Schema description coverage is 100%: both parameters (days with default/clamp, window with allowed values) are fully described. The description repeats defaults and calls window a 'snapshot family' but adds no new meaning beyond the schema. Baseline 3 is appropriate when the schema carries full descriptive weight.

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?

Purpose is unambiguous: the first sentence states it provides 'edge persistence and decay telemetry built from daily polymarket_edges snapshots' and the description answers a specific analytical question. It clearly distinguishes from sibling tools like polymarket_edges by focusing on historical time-series rather than current edge values.

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: to understand edge persistence and decay, with a concrete example. It also documents history limits (60-day TTL) and data gaps. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of 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 the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses critical behavioral traits: it 'walks the ladder', returns a verdict (clean|degraded|cannot_fill), and warns that partial basket fills 'convert an arb into an unhedged directional position (the dominant loss mode)'. It also explains how size_usd is interpreted differently per mode. This adds substantial context that annotations do not provide.

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

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

The description is long (~200 words) but front-loaded with the core purpose and logically structured via 'SINGLE-MARKET:' and 'BASKET:' delineations. Every sentence adds necessary detail for a tool with two modes and rich return fields. It is not bloated, though it could be slightly trimmed without losing essential information. Thus a 4, not a 5, reflecting that it is appropriately sized for complexity but not minimalist.

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 takes on full responsibility for explaining return values, which it does comprehensively: single-market returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket returns (theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers parameter semantics, mode selection, and practical usage guidance, making it a complete picture for a 4-parameter 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?

Input schema covers all 4 parameters with descriptions (100% coverage), setting a baseline of 3. The description goes beyond by explaining mode-specific meanings: e.g., size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg; each share pays $1)' in basket mode. It also clarifies side options and defaults in each context, adding genuine value over the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by positioning this as the fill-risk validation step before executing arb signals. The two modes (single-market and basket) are explicitly named and explained.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (thin books are not capturable, partial fills create directional risk), giving clear context for when this tool is needed over alternatives. The mode-selection rule (market vs event) is also specified.

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 readOnly/idempotent/non-destructive behavior, which the description aligns with. The description adds substantial behavioral context: compatibility_warning triggers and their two distinct cases, temporal_alignment semantics, and skipped_cross_type/subtype counters. It transparently warns about the rarity of genuine cross-venue spreads, going well 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 long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every sentence contributes information, and there is no fluff. It could be slightly trimmed on advanced counter details, but the structure earns its length for a complex tool.

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

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

Given the absence of an output schema, the description thoroughly documents the response shape (leg-by-leg prices, spread in pp, safety fields), edge cases (compatibility_warning cases), and an honest caveat about pre-mapped topics. It covers all necessary context for an agent to select and invoke the tool correctly, including when results may be meaningless.

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 all 3 parameters with descriptions and examples (100% coverage), establishing a baseline of 3. The description enriches parameter semantics by explaining how topic mode auto-fetches events, how explicit IDs override mapped ones, and how the modes interact. This adds meaning beyond the raw schema definitions.

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

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

The description clearly states the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It scopes the comparison to 'the same resolving question' and differentiates from sibling tools by focusing on cross-venue analysis. The two operating modes are explicitly laid out, leaving no ambiguity about what the tool does.

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 guidance through two modes (topic shortcuts vs explicit identifiers) and includes a strong caveat: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It also explains when spreads are meaningful (temporal_alignment required) and when they are not. However, it does not explicitly name alternative tools for comparison, relying instead on implicit differentiation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extra scoping context (anonymous IP, BYO key hash, account ID) beyond the structured annotations, which is valuable. It does not describe the return format, but the safety profile is already covered by annotations.

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

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

The description is two sentences, front-loaded with the main action and directly supported by examples. Every sentence contributes meaning, with no filler or redundant detail.

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

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

The tool is simple with one optional parameter, and the description covers purpose, usage, scoping, and relationships to sibling tools. Annotations and schema provide the remaining context, so the description is fully complete for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter ('Memory key to retrieve (omit to list all keys)'), so the description adds little extra semantic value. It reinforces the omit behavior but does not deepen the understanding beyond what the schema already provides.

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

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

The description clearly states the tool retrieves saved values or lists keys, using specific verbs and a clear resource. It distinguishes from siblings by mentioning 'remember' and 'forget' and provides concrete examples of what can be retrieved.

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

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

The description explicitly says 'Use to look up context the agent stored earlier' and shows when not to re-derive information. It also names alternatives ('Pair with remember to save, forget to delete'), giving clear usage context and relationship to sibling tools.

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

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

The description states that setting mark_read:true 'flag returned events read' and 'the next call only shows newer ones', which implies a mutating side effect. This directly contradicts the readOnlyHint annotation that declares the operation as read-only. Therefore, the description contradicts the annotation, warranting a score of 1.

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

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

The description is three sentences, front-loaded with the main purpose, and every sentence provides useful information without redundancy. It efficiently covers output fields, filtering, stateful behavior, and an alternative access method.

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 5 optional parameters and no output schema, the description sufficiently explains the return payload (source, citation_uri, raw event payload) and key behaviors. It does not mention unread_only and limit, but those are well-covered in the schema. The external endpoint note adds completeness. Minor gap: no mention of pagination or what happens with mark_read when combined with unread_only.

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 all parameters with descriptions (100% coverage), so baseline is 3. The description adds value by providing a concrete type example ('sec_8k'), explaining the ISO timestamp for 'since', and clarifying the effect of mark_read on subsequent calls, which adds meaning beyond the schema.

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

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

The description uses a specific verb 'Pull' and resource 'fired events from your subscription feed', clearly distinguishing it from sibling tools like list_subscriptions or recent_changes. It explains the returned payload and filtering capabilities.

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 use: retrieving alerts from the feed, support for polling, and filters. It also offers an alternative endpoint for scripts/dashboards. However, it does not explicitly name when NOT to use this tool or compare it to sibling tools like recent_changes.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), the description discloses substantial operational behavior: fan-out to SEC EDGAR, GDELT→GNews fallback, and USPTO patent search with known sunset that causes a soft-fail. It also notes parallel execution and structured returns, which are not inferable from annotations alone.

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?

Six sentences efficiently cover purpose, data sources, fallback behavior, parameter syntax, return shape, and sibling differentiation. Every sentence contributes new information with no redundancy or filler, making it easy for an agent to parse in one pass.

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

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

Even though there is no output schema, the description specifies the return format (structured changes[], total_changes count, pipeworx:// citation URIs) and explains parameter syntax, source behavior, and failure modes. This is complete for a tool of this moderate complexity.

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

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

The input schema already fully describes all three parameters (100% coverage), so the baseline is 3. The description adds meaningful semantics for `since` by enumerating accepted formats (ISO date vs relative shorthand like '7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring—value that goes 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 explicitly states the tool is a 'change feed for a company in the last N days/weeks/months in ONE parallel call', with concrete example queries like 'What's new with X'. It also distinguishes itself from sibling `entity_profile` with a direct pointer to when the sibling should be used instead.

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

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

The description provides explicit usage context through example queries and clearly names an alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This gives the agent solid guidance on when to select this tool over a sibling.

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, the description reveals important behavioral details: scope ('scoped by your identifier'), persistence ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'), and cross-session behavior. These are not available in annotations and materially affect usage. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

The description is efficiently structured: first the core action, then when to use, then storage mechanics, then persistence, then related tools. Four sentences, no redundancy, all information 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 two-parameter key-value save tool, the description covers purpose, usage conditions, storage semantics, persistence, and related tools. With no output schema needed and annotations covering safety, this description is complete and self-sufficient.

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

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

While schema coverage is 100%, the description adds substantial semantic context by giving concrete examples of what to store ('a resolved ticker, a target address, a user preference, a research subject') and explains the key-value pairing. This goes beyond the schema's generic descriptions and helps the agent choose appropriate keys and values.

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: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It uses a specific verb ('save') and resource ('data for reuse'), and distinguishes itself from sibling tools by mentioning 'Pair with recall to retrieve later, forget to delete.'

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

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

Explicit when-to-use guidance is provided: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names alternatives and complements: 'Pair with recall to retrieve later, forget to delete.' This clearly differentiates from siblings and gives practical context.

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

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

Beyond the annotations (readOnly, non-destructive), the description discloses internal cascading through multiple lookup endpoints, auto-disambiguation, and specific return fields (ticker, CIK, RxCUI, etc.) with citation URIs. This adds significant behavioral context.

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

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

The description is somewhat lengthy but well-structured with examples and supported types. It is front-loaded with the core purpose and immediately differentiates sibling usage. Slight verbosity prevents a 5.

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

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

The description is complete given no output schema: it explains exactly what is returned for each type, mentions input formats, and notes it replaces multiple manual lookups. It fully satisfies the complexity of the tool.

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

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

Schema description coverage is 100% and parameter descriptions are already detailed. The description adds examples and return types but doesn't meaningfully enhance the existing parameter semantics; hence baseline 3.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It provides specific verbs and resources (e.g., company, drug) and differentiates from siblings by emphasizing it returns IDs that other tools require.

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 FIRST whenever you have a name but need an ID.' This clearly indicates when to use the tool, though it doesn't explicitly name alternative tools or when-not-to-use scenarios.

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

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

With annotations (readOnlyHint, idempotentHint, openWorldHint) already covering safety, the description adds process details: it probes each entity via ai_visibility_check, ranks results, and surfaces most/least recognized. It also discloses output fields (score, confidence, signal density). This provides useful behavior beyond the annotations, though it does not mention potential external API calls or cost implications.

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

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

The description is three sentences, front-loaded with the core purpose, then expands with process, use case, and output details. Every sentence contributes substance 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?

For a tool with no output schema and moderate complexity, the description covers what it does, how it works (via ai_visibility_check), what it returns (ranked list with specific fields), and when to use it. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds critical semantic context for the 'entities' parameter: the first entry is treated as the 'subject' and the rest as competitors. This clarifies how the tool interprets the array, which is valuable beyond the schema's basic type 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 uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishing it from the single-entity 'ai_visibility_check' sibling. It explains the process (probes with ai_visibility_check, ranks by score) and the intended outcome, making the tool's purpose unambiguous.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with a concrete example, and implies that this is for multi-entity comparison versus the single-entity ai_visibility_check. It does not explicitly mention when not to use it or name alternatives, but the context is strong enough for an agent to infer appropriate usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: possible 5-30s delay on first bundlephobia measurement, graceful partial-failure behavior with sources_failed, and the combined-output nature of the tool. 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 compact relative to the tool's complexity; it front-loads purpose, then delivers usage, output fields, ecosystem limitations, and failure behavior without filler. Every sentence contributes actionable 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?

No output schema is present, but the description compensates by naming the full set of return fields, per-advisory details, links, alternative versions, and failure behavior. It fully covers the composite nature, latency, and scope, making the tool 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?

The input schema already fully documents both package and version, including that version defaults to latest when omitted. The description does not add new parameter-level meaning beyond the schema, so the high-coverage 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 identifies the tool as a composite npm dependency vetting check, enumerating the exact data sources (deps.dev and bundlephobia) and the question it answers (should I add this package). It distinguishes itself from direct deps.dev lookups by noting when the direct tool applies instead.

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

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

Explicit usage triggers are given, such as 'is X safe / popular / small' or 'what does adding lodash cost me'. The description also provides an exclusion: non-NPM ecosystems should go to deps.dev:version directly, which is clear 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals algorithm details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K character cap with truncation flagged. It also describes the output structure (passages with offsets and scores), which is not in annotations or an output schema.

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

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

The description is densely informative yet compact. Every sentence earns its place: purpose, parameter guidance, use case, companion tool, and technical constraints are packed into four sentences without redundancy. Main purpose is front-loaded with 'Semantic search INSIDE a fetched record'.

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

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

Even though there is no output schema, the description explains return values (passages, offsets, scores), limitations (200K cap, truncation flag), use cases, and integration with a sibling tool. This is complete for an agent to select and invoke the tool correctly.

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

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

The input schema already covers 100% of parameter descriptions, so baseline is 3. The description adds useful semantics: examples of what 'text' should contain (SEC 10-K body, article), example queries, and the default/range context for 'limit'. This is above baseline but not exhaustive.

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

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

The description clearly states a specific action: semantic search inside an already-fetched record, returning passages with offsets and scores. It distinguishes itself from siblings by emphasizing 'inside' and explicitly positioning 'Pairs with ask_pipeworx_grounded' rather than searching the whole document.

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 use guidance is provided: 'Use when the record is too big to cram into the prompt — search_within saves context...'. It also names a complementary tool (ask_pipeworx_grounded) and contrasts with whole-document grounding, giving clear when-to-use and alternative context.

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

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

The description adds substantial behavioral context beyond annotations, such as requiring a Pipeworx OAuth account, SMS verification and 10/day cap, and the always-on feed. Annotations indicate a write operation (readOnlyHint=false) and non-destructive behavior, which the description aligns with while adding operational 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 long but well-structured, starting with the purpose and account requirement before listing types and delivery options. It is front-loaded and each sentence provides necessary information, though it could integrate webhook details from the schema to avoid omission in the main text.

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

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

The description covers the essential aspects: return value, authentication, type-specific params, and delivery details. However, it omits webhook as a delivery channel in the main description (present only in the schema), which is a minor gap given the absence of an output schema. Overall, it is sufficiently complete for a complex subscription tool.

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

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

The schema already provides 100% coverage with detailed descriptions and examples for all parameters. The description adds semantic value by explaining the meaning of item codes (e.g., items:['5.02'] = officer change) and giving concrete examples for certain types, enhancing understanding beyond the structured schema.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream', which is a specific verb+resource statement. It clearly distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation and noting the returned subscription ID.

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

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

The description provides clear context on when to use the tool, including account prerequisites and type-specific examples, but does not explicitly name alternatives or exclusions. It implies usage by detailing supported subscription types and delivery channels, which is sufficient given the 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, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context: results are 'drawn from the live catalog of thousands of tools,' are category-bucketed, and can be filtered by topic. This enriches the model 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 verbose but every part earns its place: it opens with realistic example queries, then explains the purpose, return structure, categories, and usage. It is front-loaded with the most important info (what it returns, when to use it) and avoids filler, though it could be slightly tightened without loss.

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 only one optional parameter, full annotations, and no output schema, the description provides everything an agent needs: what it returns (category-bucketed example questions with tool + argument shape), how to call it (no args or topic), and when to use it (first-time onboarding, learning meta-tools). It is complete for selection and 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?

The input schema provides 100% coverage for the single `topic` parameter, including the enumerated list (finance, pharma, economics, etc.) and the omit-for-default behavior. The description's mention of `topic` with examples (e.g. 'finance', 'pharma') closely mirrors the schema, adding no significant new semantics. The baseline of 3 is appropriate.

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

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

The description clearly defines the tool as 'the onboarding entry point for an agent that just connected and wants to know what is worth asking,' with a specific verb (returns) and resource (category-bucketed example questions with tool + argument shape). It effectively distinguishes itself from siblings by positioning as the 'FIRST' tool to use when unfamiliar with Pipeworx, and it explicitly lists the meta-tools it helps learn.

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

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

It gives an explicit directive: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides a clear when-to-use and an implicit when-not-to-use (when you already know). It also specifies two invocation patterns: no arguments for the full spread, or pass a `topic` to focus.

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, the description explains a key side effect: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This complements the destructiveHint=false annotation and adds the non-obvious behavior of logical deactivation. Ownership enforcement is also a behavioral trait not in annotations. No contradiction found.

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 brief (three sentences) and front-loaded with the core action. Every sentence adds value: purpose, ownership constraint, and behavioral consequence. 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?

For a simple one-parameter tool with rich annotations, the description covers the essential aspects: what it does, who can use it (ownership), and the deactivation behavior. It does not mention return values, but given the tool's simplicity and absence of an output schema, this is not a critical gap. Slight room for noting error behavior, but overall complete.

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

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

The input schema describes the sole parameter 'id' as 'Subscription id (uuid) returned by subscribe.' The description adds no new parameter meaning beyond saying 'by id'. Since schema coverage is 100%, the description's contribution is minimal; baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Cancel a subscription by id.' The verb 'Cancel' and resource 'subscription' are specific, and it distinguishes from sibling tools like subscribe and list_subscriptions by focusing on cancellation.

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 context: 'Ownership is enforced — you can only cancel your own subscriptions.' This is an exclusion that guides when the tool can be used. It also hints at the alternative of keeping history via recent_alerts, but does not explicitly name an alternative tool. Overall, context is clear with one 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: it discloses the two-path routing (SEC vs. grounded pipeline), the exact verdict types returned, and the inclusion of citations and reasoning. This is useful behavioral transparency 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?

Despite being a single dense paragraph, every sentence contributes: trigger phrases, usage directive, routing logic, return format, and efficiency claim. It is front-loaded with natural-language examples and immediately explains the tool's purpose. No filler or redundant 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?

With no output schema, the description compensates by explicitly listing verdict types, the citation format (pipeworx://), and that reasoning is included. It also explains the difference between the two verification paths. It could mention edge cases or what happens with unverifiable claims, but 'unsupported' is already a listed verdict so it is fairly complete.

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

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

Schema coverage is 100%, so the description does not need to explain parameters in depth. It adds minor context around tolerance via 'exact percent-delta math' and 'tolerance implied by the claim wording', but these are already reflected in the parameter descriptions. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a claim-verification function with specific verbs like 'fact check' and 'verify', and explicitly states it checks factual correctness against authoritative sources. It also distinguishes itself by mentioning the SEC EDGAR/XBRL fast path and the fallback grounded pipeline, setting it apart from general Q&A siblings like ask_pipeworx.

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' and provides a clear routing rule for company-financial claims vs. other claims. It implies this replaces multi-step processes but does not explicitly name when not to use or list alternative tools, so it misses the top score.

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