postcodes

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 meaningful behavioral context: per-model response structure ({score, confidence, signals, raw_response} + combined view), the default free Workers AI model, and the BYO-key payment model for Anthropic calls. No contradictions with annotations.

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

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

The description is four sentences, each serving a purpose: core function, default/optional behavior, return format, and use cases. It is front-loaded with the most critical information and avoids fluff or redundancy.

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

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

Given the lack of an output schema, the description adequately explains the return value ('per-model {score, confidence, signals, raw_response} + a combined view') and the 0-100 scoring range. It also covers the Anthropic key requirement and common use cases, making it complete for an agent to select and invoke the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantics beyond the schema by explaining the default model ('Workers AI Llama-3.3-70b (free)') and the payment implication of `_apiKey` ('BYO key — you pay Anthropic directly'), which enriches the parameter understanding.

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

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

The description clearly states a specific verb ('probe') with a resource ('LLMs for what they know about a business / brand / product / topic') and an outcome ('score visibility (0-100) per model'). It distinguishes itself from siblings by focusing on AI visibility scoring rather than general Q&A or research, and even mentions concrete use cases like AI-marketing audits.

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 usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and when to pass `_apiKey` to probe Anthropic. However, it does not explicitly contrast with similar-looking siblings like `scan_competitor_ai_presence`, so exclusions are missing.

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

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

The description adds valuable context beyond annotations: it mentions routing, filling arguments, returning structured answers with pipeworx:// citation URIs, and that it works on every tier and is fast. It does not contradict the readOnly, openWorld, idempotent, or non-destructive hints. However, it does not describe limitations like error handling or what happens if the tool cannot find a match, keeping it from a 5.

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

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

The description is front-loaded with 'PREFER OVER WEB SEARCH' and organized into clear sections: what it does, when to use, examples, and when to step up to alternatives. It is longer than typical but every sentence adds value, including examples and explicit exclusion criteria. A sentence on return format is present, making it well-structured, though slightly verbose.

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

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

Given the tool's complexity and lack of an output schema, the description provides sufficient context for an agent to select and invoke it correctly: it covers usage triggers, examples, alternatives, and mentions the structured answer with citation URIs. It does not detail response morphology or error behavior, but for a routing tool this is acceptable. It is more complete than a minimal description.

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

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

The input schema fully describes all six parameters (all aliases), with 100% coverage, so the description does not need to add parameter-level detail. The description provides examples of valid question values, which helps illustrate usage but does not add meaning beyond the schema's description of the 'question' parameter. 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 what the tool does: it routes questions to appropriate tools across 5,529 sources and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point. Specific verbs like 'routes,' 'fills arguments,' and 'returns' make the purpose unambiguous.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and lists trigger phrases like 'what is,' 'look up,' 'find,' etc. It provides clear direction to use alternatives only when needed: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. It also covers edge cases like breaking news, stating the tool already handles live news.

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, and open-world hints in annotations, the description adds important experimental context: it may have candidate routing improvements enabled, results are compared for merge decisions, and it is a full working router that falls back to nothing. This fully discloses the behavioral nature of the beta tool 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 efficient and front-loaded with the key identity ('Beta version of ask_pipeworx'). Each sentence adds necessary context (identical router, candidate status, usage instruction, comparison purpose), though the final 'Falls back to nothing' sentence could be tighter. Still, it is well-structured and not wasteful.

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 compensates by referencing the same response shape as ask_pipeworx. It covers current behavior, active candidates, usage, and the comparison mechanism. This is complete for a query-routing tool with strong annotations and a simple parameter set.

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 description does not add parameter-level detail, but the input schema has 100% coverage with six well-documented aliases for the 'question' parameter. Since the schema fully explains parameters, the baseline of 3 applies; the description contributes no extra semantic information.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements, so the purpose is specific and differentiated.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no candidate active, matches ask_pipeworx exactly) and explains why results are compared against the stable router. This gives clear context and effectively points to the alternative (ask_pipeworx).

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), the description discloses the refusal behavior with specific reason codes, the exact return format, and the cost of one extra LLM call. It explains that the answer is extracted only from the tool result, which is critical behavioral context not captured in annotations.

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

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

The description is dense but well-structured, front-loading the core purpose, then mechanism, return shape, and usage guidance. Every sentence contributes value, though it's longer than ideal; the complexity justifies the length.

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

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

The description is exceptionally complete for a complex tool with no output schema. It specifies the return shape, refusal reasons, cost tradeoff, and usage scenarios, covering all essential aspects an agent needs to invoke it effectively and interpret its results.

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

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

The input schema has 100% description coverage, with all parameters documented as aliases for 'question' and the main parameter described. The description adds no parameter-specific meaning beyond that, but given the high schema coverage, a baseline of 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which is a specific verb+resource+scope statement. It explicitly contrasts with ask_pipeworx by detailing the grounded extraction and refusal behavior, distinguishing it from the sibling 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?

The description explicitly directs use for 'high-stakes' or quoted/cited/acted-on answers, and tells the agent to 'prefer ask_pipeworx for casual lookups,' citing the extra LLM call cost. This provides clear when-to-use and when-not-to-use guidance, naming the alternative tool.

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

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

Beyond the readOnly/idempotent annotations, the description discloses a wealth of behavioral nuance: resolver confidence levels, fan-out logic, low-confidence short-circuiting, closed-market handling, wide-spread tradeability warnings, and even cancellation-rule risk like flat-50¢ void settlements. This is far more than the 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?

The description is lengthy but well-organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY). It front-loads the core purpose and packs dense, valuable details into every sentence. Slightly over-long, but the structured format keeps it navigable.

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 high complexity and lack of an output schema, the description covers the full response contract: resolver match confidence, parent_event extractor, news fallback fields, safety statuses, and resolution-rule risk. It effectively substitutes for a missing output schema and leaves no critical usage aspect unexplained.

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?

With 100% schema description coverage, the baseline is 3. The description adds practical meaning beyond the schema by explaining acceptable market input varieties, showing fan-out examples that illustrate depth levels, and clarifying include_raw's size trade-off. These additions go beyond simple field definitions.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states accepted input formats and target use cases ('should I bet on X'), distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context but does not explicitly state when not to use the tool or compare it to alternative approaches, falling just short of full exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds rich behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, return of paired data plus citation URIs, and efficiency benefit (replaces 8–15 lookups). These go well beyond the annotations.

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

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

The description is dense but well-organized, starting with trigger phrases, then core function, data details, output behavior, and efficiency. Every sentence adds value, though it is somewhat long; a slight trim would make it more concise without losing 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?

With no output schema, the description adequately covers return values (paired data + pipeworx:// URIs), input semantics, data sources, sorting, and edge cases (off-calendar fiscal years). For a tool with only two parameters and moderate complexity, it is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant meaning: it explains what each 'type' value pulls (10-K metrics for company, adverse-event/trial counts for drug) and provides examples for 'values'. This enriches the schema definitions meaningfully, though it doesn't add format details beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with specific trigger phrases like 'Compare X and Y' and 'rank these companies'. It distinguishes itself from sequential single-pack lookups, making it unique among siblings such as entity_profile.

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

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

Explicitly provides when-to-use examples ('X vs Y', 'which is bigger', 'head to head') and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', which is a clear alternative/exclusion. It also differentiates between company and drug types, giving context for each.

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, but the description adds rich behavioral context: account requirements (paid for thorough), expected latency (15-60s, up to ~90s), gaps[] 'never invented' policy, contradictions[] availability, semantic excerpting, and citation_uri resolvability. No contradiction with annotations.

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

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

The description is long but optimally structured—every sentence conveys a distinct operational constraint or behavior. It is front-loaded with account prerequisite, alternative tool, mechanism, use cases, depth options, output format, and performance, with no filler.

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

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

With no output schema, the description fully explains the return payload (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop) and operational expectations (time, edge cases like empty gaps[] for non-catalog topics). It covers prerequisites, alternatives, and limitations, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: 'thorough needs a paid plan', time expectations, and elaborates on the second-hop iteration. It reinforces that 'question' can be broad/multi-part, which is already in schema, but the additional operational details justify a 4.

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

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

The description states a specific action: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with decomposition into facets and parallel routing to 5,529 tools. It clearly distinguishes from siblings by noting 'this is NOT open-web search' and contrasting with ask_pipeworx's single-lookup behavior.

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

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

Explicitly provides when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not-to-use with named alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also covers account prerequisites and fallback behavior if not signed in.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral details beyond that: returns top-N tools, includes full schemas with curated examples, and eliminates the need for a second schema lookup. This gives the agent confidence in what to 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?

The description is front-loaded with the core purpose, then gives usage context and return details. It is three sentences long; the middle domain list is long but purposeful as it sets expectations for what can be searched. No redundant fluff, but slightly wordier than necessary.

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

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

There is no output schema, so the description carries the burden of explaining return values. It does so well by stating that it returns 'names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly'. It also covers 'no second schema lookup needed', making the tool's behavior clear for an agent.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and aliases. The tool description doesn't add significant parameter-specific semantics beyond the schema; it merely lists example domains, which helps formulate queries but doesn't explain parameter syntax or edge cases.

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

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

The description opens with 'Find tools by describing the data or task', which is a specific verb+resource statement. It clearly differentiates from siblings by positioning itself as the meta-search/discovery tool, listing concrete domains and return format.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. It implies when not to use it (when you already know the exact tool), providing clear actionable guidance.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by detailing the cross-source fan-out (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific return fields, and known limitations (e.g., patents soft-fails until reactivated, GDELT→GNews fallback, up to 5 filings, LATEST 10-K only). It also notes the parallel-call behavior. No contradiction with annotations.

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

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

The description is dense but packed with necessary information: examples, usage guidance, data sources, return structure, and limitations. It is front-loaded with user query examples and the core purpose. Though longer than ideal, every sentence earns its place and the structure is logical. Slight deduction for length and the run-on feel of the return list.

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 thoroughly covers what the tool returns: CIK, recent filings with URIs, fundamentals fields, patents status, news fallback chain, and LEI. It also explains the input constraints and the one-call parallel behavior. This is complete for a complex tool with multiple data sources.

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

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

The input schema already provides full documentation for both parameters (type and value), including the enum for company and the ticker/CIK format. The description restates these constraints ('Pass ticker ... or zero-padded CIK ... names not supported') without adding new semantics beyond the schema. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly defines the tool's purpose with specific verbs ('tell me about', 'research', 'brief me on') and a concrete deliverable: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools by explicitly stating it should be preferred over chaining single-pack lookups when a holistic view is requested, and it references resolve_entity as a fallback for name inputs.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when the tool is NOT appropriate ('names not supported') and directs users to an alternative (resolve_entity). This is a model example of usage guidelines.

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. The description adds behavioral nuance by highlighting the purpose of clearing sensitive data, which goes beyond the bare delete action. No contradiction; it reinforces the destructive nature without redundancy.

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 concise sentences, front-loaded with the action, followed by when-to-use and pairing advice. Every sentence provides value with no extraneous 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?

A simple one-parameter, no-output-schema tool with strong annotations. The description is fully self-contained: it states the action, the trigger conditions, and related tools, making it complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with the 'key' parameter clearly described as 'Memory key to delete'. The description does not add new meaning beyond the schema, but there is no gap, 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 uses a specific verb 'Delete' and a clear resource 'previously stored memory by key', making the action unambiguous. It also implicitly distinguishes from sibling tools like 'remember' and 'recall' by stating it deletes rather than stores or retrieves.

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'. It also tells the user to pair with 'remember and recall', providing clear context for use 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 readOnlyHint=true and destructiveHint=false, establishing a safe read operation. The description adds process details (fetches the page, extracts title/description/key links) and mentions output format (standard llms.txt markdown), but it doesn't disclose edge behaviors like timeout handling or errors. With strong annotation coverage, a 3 is appropriate as the description adds some context beyond the structured data.

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 long, front-loaded with the core purpose, and every sentence adds value. It avoids fluff and repetition, efficiently covering purpose, process, output, and use cases in a compact format.

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

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

For a simple tool with 100% schema coverage, useful annotations, and no output schema needed (since output is a text blob), the description covers the essential context: what it does, how it works, and when to use it. It's slightly incomplete in terms of edge-case behavior, but it's well-suited to the tool's simplicity.

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

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

Schema description coverage is 100%, so both parameters (url and max_links) are fully documented in the schema itself. The description does not add extra parameter-specific context, such as how max_links interacts with pagination. Baseline 3 is correct since the schema carries the heavy lifting and the description adds no extra semantic value.

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 ('Generate') and a concrete resource ('a production-ready llms.txt file for any URL'), clarifying both the action and the target. It distinguishes itself from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on producing the actual llms.txt markdown, not just analyzing visibility.

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

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

The description explicitly lists three practical use cases: getting a client's site indexed, drafting llms.txt for your own project, and auditing a competitor. While it doesn't state when to avoid this tool or mention alternatives by name, the use-case list provides clear context for when it is appropriate, earning a 4.

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 and idempotent, and the description adds useful context about scope (caller's subscriptions) and default behavior (active only, with the include_inactive parameter). It doesn't contradict annotations and provides meaningful behavioral detail beyond safety flags.

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

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

Two sentences: first states action and return fields, second gives usage context. No fluff, front-loaded, every word earns its place.

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

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

With no output schema, the description explicitly names return fields. The single optional parameter is explained in the schema, and the tool's role relative to subscribe/unsubscribe is clearly stated. The description is complete for an agent to select and call the tool correctly.

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

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

The input schema covers the single parameter include_inactive with a clear description. The tool description does not need to add more, as schema coverage is 100%; baseline 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, params, etc.). This specific verb+resource combination distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description gives explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This differentiates it from subscribe/unsubscribe and covers the main use cases.

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 context by specifying what data is returned (coordinates, region, district, ward, constituency), going beyond the annotation-level information without contradicting it.

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

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

The description is two sentences, front-loaded with the primary action, and includes an example and return fields. Every sentence earns its place with no fluff or repetition.

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

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

The tool has a single parameter, comprehensive annotations, and an output schema. The description fully covers the tool's purpose and return values, making it complete for a simple lookup tool. No additional behavioral context is needed given the simplicity and rich structured metadata.

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

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

Schema coverage is 100%, and the schema already provides a clear description and examples for the postcode parameter. The description repeats an example ('SW1A 1AA') but adds no new semantic information beyond what the schema documents, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'geographic details for a UK postcode', and it lists specific return fields (coordinates, region, district, ward, constituency). This distinguishes it from sibling tools like validate_postcode or random_postcode by focusing on retrieval of geographic details for a given postcode.

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

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

The description implies usage when geographic details for a UK postcode are needed, but it does not explicitly state when to use this tool versus alternatives like validate_postcode or nearest_postcodes. No exclusions or alternative tool mentions are provided.

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

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

Annotations already declare the operation read-only, non-destructive, and idempotent. The description adds useful behavioral details beyond annotations, such as sorting by distance and returning coordinates, which helps set expectations without contradiction.

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

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

The description is one concise sentence, front-loaded with the main purpose ('Find nearby UK postcodes'), followed by the sorting and output details. Every word earns its place with no redundancy.

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

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

For a simple read-only tool with one parameter, an output schema, and rich annotations, the description is completely adequate. It specifies the input, the sorting behavior, and the return shape, leaving no critical gaps for an agent to misuse 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 coverage is 100% with the single 'postcode' parameter fully described. The description only repeats the example and adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Find') with a clear resource ('nearby UK postcodes') and distinguishing behavior (sorted by distance from a given postcode). This clearly separates it from sibling tools like lookup_postcode, random_postcode, and validate_postcode.

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

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

The description clearly implies when to use the tool: when you need nearby postcodes for a given postcode. It does not explicitly mention alternatives or exclusion cases, but the context is clear enough for an agent to select it over related 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?

Extends far beyond the annotations: explains the claim_token workflow for anonymous reports and later follow-up, daily rate limit of 5 per identifier, free/no quota impact, and that the team reads digests daily. These are non-obvious behaviors the agent needs to invoke and set expectations correctly.

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

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

The description is long but information-dense; every sentence carries operational instructions (routing, claim_token, rate limits). It is front-loaded with purpose and use cases, though the volume of detail is higher than strictly necessary, so it doesn't earn a top conciseness score.

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

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

With four optional params and no output schema, the description covers all key context: when to file, how to identify Pipeworx tools, the claim_token lifecycle, rate limiting, and cost. It is sufficient for an agent to select and invoke the tool correctly without further clarification.

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

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

The schema already describes all four parameters (100% coverage), so the baseline is 3. The description adds value by explaining the claim_token round-trip ('Filing without an account returns a claim_token; pass it back later...') and by advising message specificity and 1-2 sentence typical length, which goes beyond schema constraints.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete report types (bug, feature/data_gap, praise), making the tool's role unmistakable and clearly distinct from 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?

Explicit when-to-use guidance is provided for each category ('Use when a tool returns wrong/stale data (bug)...'), along with a clear exclusion: reports must be for tools served by this Pipeworx connection, not other MCP servers. This tells the agent exactly when to choose this tool over alternatives.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds valuable context: caching behavior ('Cached 5min-1h depending on window'), data provenance ('derived from CF analytics-engine'), and privacy ('no PII, just (pack, tool, count)'). These details disclose how the data is gathered and its freshness.

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

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

The description is well-structured: a hook, output summary, numbered use cases, and data provenance/caching notes. Every sentence contributes value, and the numbered list makes the use cases easy to scan. No redundant or fluff 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 tool with one optional parameter and no output schema, the description covers the output contents, use cases, data source, privacy, and caching. It is fully self-contained and leaves no critical gaps for an agent to resolve.

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

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

The schema already provides full parameter coverage with an enum and semantic explanation ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description repeats the window options but adds no new parameter semantics beyond what the schema already states.

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

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

The description opens with a clear question 'What other AI agents are calling on Pipeworx right now' and enumerates exact outputs: top tools, top packs, and total call volume over a recent window. This clearly distinguishes it from siblings like discover_tools and ask_pipeworx, which serve different purposes.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming a canonical tool, checking alignment with user needs). It does not mention alternatives or when not to use, but the use cases are specific enough to guide appropriate selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false. The description goes far beyond this by disclosing specific behavioral quirks: placeholder slug filtering, the >20% placeholder fraction returning null, the Jaccard similarity threshold (≥0.30), and the fill-check mechanism that can override a signal. It also explains what happens when realizable_edge_pp ≤ 0, which is critical for safe use. No contradictions with annotations.

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

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

Although lengthy, every sentence carries operational value. The description is organized with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and uses imperative guidance like 'do not trade it.' It front-loads the core usage pattern ('Call with NO args...') and structures detail logically. 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?

No output schema exists, so the description must explain return values—and it does: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), and in event mode partition_check{...}'. It also covers edge cases (placeholder filtering, low similarity), pricing depth checks, and cross-event mode benefits. For a tool with two optional parameters and complex internal logic, this is fully complete.

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

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

Schema coverage is 100% with both event and topic having descriptions. The description adds substantial meaning beyond the schema: concrete slug examples, seed question examples, the fact that full Polymarket URLs are accepted, and the exact behavior of each mode. It also clarifies that zero arguments are valid, which is not obvious from 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from sibling tools like polymarket_edges (which likely focuses on edges) and polymarket_fill_risk (which the description explicitly differentiates for custom sizing). The three modes (trending_scan, event, topic) are precisely described.

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

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

Provides explicit when-to-use guidance for each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also names an alternative tool: 'For custom sizing use polymarket_fill_risk.' The fill-check section explains when not to trade (realizable_edge_pp ≤ 0), making usage conditions exceptionally clear.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing internal algorithms, slippage assumptions, caching behavior ('Cached 1h at the KV level keyed on all knobs'), and diagnostic output. It also warns about 24h-move signal and explains why certain segments might be empty, providing excellent transparency.

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

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

The description is extremely long and dense, covering model formulas, specific alpha values, gate relaxations, and response field details. While it's well-organized with numbered segments, it's far from concise—many sentences contain implementation specifics (e.g., 'tennis 1.02, soccer 1.10, MMA 1.15, default 1.0') that could overwhelm an agent and hinder quick scanning.

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

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

With no output schema, the description fully explains the response structure: by_segment, fed_candidates/fed_note, and _diagnostics. It describes the fields on each opportunity (edge_pp_net, kelly_fraction, market.liquidity, market.spread_pp, market.volume) and why segments might be empty (via filter_skips), making it highly 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?

Even though schema coverage is 100%, the description adds substantial meaning to parameters. It explains the rationale for knobs like min_liquidity and max_spread_pp ('drop opportunities where edge isn't realizable'), the difference between min_kelly and min_partition_leg_kelly, and gives guidance on slippage_pp values ('Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade').

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+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx-driven edge detection and its built-in segmentation into MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, and CONCENTRATED_LONGSHOT.

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 states its intended use case ('Built for what should I bet on today') and explains when to use it: to discover opportunities without paging hundreds of markets. It also provides a caveat about Fed candidates being unreliable at meeting-month horizons, but it doesn't explicitly name alternative tools or state when not to use this one.

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, openWorld, idempotent, and non-destructive behavior. The description goes far beyond this by explaining the response structure (tracked, expired, snapshot_dates), limitations (60-day TTL, snapshot gaps), and interpretation details (decay based on daily closes, signed edge values). This provides rich behavioral context with no contradictions.

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

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

Description is long but well-structured with clear divisions (Args:, RESPONSE:, LIMITS:). It front-loads the core purpose, then details parameters and output, ending with limitations. Every sentence adds substantive information; no filler.

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

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

Given the tool's moderate complexity and absence of an output schema, the description fully compensates by detailing the response objects (tracked, expired, snapshot_dates) and their fields, plus important caveats. The agent has enough information to invoke the tool and interpret results correctly.

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

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

Schema covers 100% of parameters (days, window) with clear descriptions. The description adds minor context like 'snapshot family' and echoes defaults but doesn't significantly improve on the schema. It omits the min clamp for days (2) that the schema includes. 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?

Description clearly states the tool's unique function: edge persistence and decay telemetry. It answer a specific trading question (how long has an edge existed and is it shrinking?) and distinguishes itself from sibling tools like polymarket_edges by focusing on historical snapshots. The verb 'answers' gives a concrete use case.

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

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

The description implies when to use this tool: when you need to understand edge persistence over time, not just current edges. It mentions being built from daily polymarket_edges snapshots, which suggests it complements the sibling polymarket_edges tool. However, it doesn't explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses intricate behaviors: it 'walks the ladder', computes vwap_fill_price and slippage_pp, and returns a verdict (clean|degraded|cannot_fill). It also reveals risk-related behavior such as 'thin_legs[]' and 'forced_directional_risk naming the legs most likely to strand you unhedged', which is 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?

The description is long but meticulously structured with REQUIRES, SINGLE-MARKET, BASKET, and USE THIS sections, front-loading the core purpose. Every sentence carries operational value, with no filler; the density is justified by the tool's two-mode complexity.

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

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

With no output schema, the description carries full weight for return-value documentation, and it delivers: it enumerates all return fields for both modes (top_of_book, vwap_fill_price, capture_ratio, profit_usd, thin_legs[], etc.). It also covers edge cases like partial fills and forced directional risk, making it self-sufficient for an agent to decide when and how to invoke it.

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

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

Though schema coverage is 100%, the description adds substantial meaning: it explains that `market` means single-market mode and `event` basket mode, that `size_usd` is 'max spend on buys, target proceeds on sells' in single-market but 'settlement notional S (shares per leg)' in basket mode. It also documents defaults and clamps ('Default 1000, clamp 10–1,000,000'), far exceeding 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') that clearly distinguishes it from siblings like polymarket_arbitrage and polymarket_edges. It elaborates two distinct modes (SINGLE-MARKET and BASKET) with explicit output fields, making the tool's function unmistakable.

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

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

It explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', naming the exact sibling tools and conditions. It also warns why (theoretical overround not capturable, partial basket fills create unhedged directional risk), providing both when and why guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds rich behavioral detail beyond those: the two compatibility_warning cases, temporal_alignment semantics, skipped_cross_type/subtype counters, and the explicit statement that non-equivalent bet shapes mean no arb exists. It explains when spread values are real signals and when they are meaningless, and there is no contradiction with the annotations.

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

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

The description is front-loaded with a clear purpose and uses labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) for scannability. It is long with dense parentheticals, but every sentence earns its place by conveying safety semantics or usage nuance. Slightly too verbose for an agent to parse quickly, but not wasteful.

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

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

For a tool with no output schema, the description thoroughly covers input modes, response shape (leg-by-leg prices, top_spreads_pp), temporal alignment, and safety/failure conditions. It tells the agent exactly how to interpret compatibility_warning and skipped counters, making it complete for correct invocation and result 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?

All three parameters are described in the schema with 100% coverage, so the baseline is 3. The description restates the topic enum and adds mode context, but the schema already includes the override behavior for kalshi_event_ticker and polymarket_event_slug. The net added value for parameters beyond the schema is moderate.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly defining the tool's specific purpose and resource. It distinguishes itself from sibling tools like polymarket_arbitrage by emphasizing the cross-venue comparison and the conditions under which the spread is meaningful. The two modes (topic vs explicit ticker/slug) are also clearly stated.

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

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

The description gives explicit usage modes: topic shortcuts for pre-mapped events and explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also warns that pre-mapped topics are not necessarily tradeable and that most currently return compatibility_warning. However, it does not name alternative sibling tools or explicitly state when to prefer them, so it slightly misses the 'when-not-to-use' guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds useful context by specifying that the postcode is random and valid, and lists the returned geographic details, which goes beyond the annotations. It does not disclose additional limitations or caveats, but the positive annotation profile lowers the burden.

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

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

The description is a single, front-loaded sentence that states the main purpose and then enumerates the returned data fields. There is no wasted wording, and the structure is easy to scan.

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 0 params and has a strong annotation profile. The description covers the core function (random valid UK postcode) and the key outputs (coordinates, region, etc.), which, combined with the output schema, offers a complete picture for an agent to invoke the tool correctly.

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

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

The tool has zero parameters, and schema coverage is trivially 100%. With 0 params, the baseline is 4, and the description appropriately omits parameter details since none exist. It adds nothing about parameters, but nothing is needed.

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

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

The description clearly states the action ('Get a random valid UK postcode') and highlights it returns full geographic details like coordinates, region, district, ward, and constituency. This distinguishes it from sibling tools such as lookup_postcode or validate_postcode, which serve different purposes.

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

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

The description implies the tool is for obtaining a random postcode rather than a specific one, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions. Given the sibling names, an agent could infer the use case, but the guidance is not explicit.

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

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

Annotations already convey read-only and idempotent behavior, and the description adds useful context such as scoping ('Scoped to your identifier') and the dual-mode behavior (omit key to list). It does not describe error handling or return format, but this is partially covered by the annotations.

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

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

The description is three sentences, front-loaded with the main action, then provides examples, scope, and pairing. Every sentence contributes essential information with no redundancy.

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

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

For a simple read-only tool with strong annotations, the description covers functionality, usage context, scoping, and related tools. Since there is no output schema, not detailing return format is acceptable. The tool is appropriately 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% for the 'key' parameter, so the baseline is 3. The description enriches the parameter meaning by explaining that the key retrieves a value 'previously saved via remember' and that omitting it lists all keys, providing context beyond the schema.

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

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

The description clearly states the tool's function with specific verbs and resources: 'Retrieve a value previously saved via remember, or list all saved keys.' It distinguishes itself from siblings by explicitly mentioning remember and forget, and by describing both operational modes.

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

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

It provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives for related operations: 'Pair with remember to save, forget to delete,' effectively delineating when not to use recall.

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 directly contradicts the annotations. Annotations declare readOnlyHint=true, but the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones', which is a state-changing write. This is a serious inconsistency that undermines agent trust.

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: the first sentence states the core purpose, followed by details on return payload, filtering, mark_read, and alternative access. It is slightly dense but each sentence contributes useful information without excessive verbosity. It does not repeat schema descriptions unnecessarily.

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 return format (source, citation_uri, raw payload), filtering, mark_read behavior, and alternative endpoint access. However, it omits interaction between parameters (e.g., unread_only vs mark_read) and does not mention the default limit or range, though these are in the schema. The annotation contradiction further reduces completeness, as the behavioral contract is inconsistent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema: it gives a concrete example filter value ("sec_8k"), clarifies the use of 'since' as ISO timestamp, and explains the effect of mark_read:true (next call only shows newer events). This enriches the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts'. It specifies the resource (subscription feed alerts) and the action (pull/return), distinguishing it from siblings like recent_changes. It also mentions key aspects like filtering and mark_read behavior.

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

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

The description provides usage context: it says 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)' and 'Polls work fine', indicating suitable scenarios (polling, filtering). It also points to an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant behavioral detail: data source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), specific fallback triggers (rate-limited or 5xx), and the PatentsView sunset condition causing soft-fail. This goes well beyond the annotations.

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

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

The description is longer than average, but every sentence contributes essential operational detail (sources, fallbacks, parameter syntax, return structure, alternative tool). It is front-loaded with the most common use cases. Slightly dense, but not wasteful.

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, multi-source aggregation tool with no output schema, the description is thorough: it explains return shape (changes[] grouped by source, total_changes count, pipeworx:// citation URIs), fallback behavior, parameter formats, and the appropriate alternative tool. No critical gaps for an agent to invoke it correctly.

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

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

Schema covers 100% of parameters, but the description adds meaningful semantics: `since` formats (ISO date vs relative shorthand like '7d', '30d', '3m', '1y'), `value` examples (ticker vs zero-padded CIK), and `type` restriction to 'company'. This adds value beyond the 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 opens with concrete user intents ('What's new with X' / 'latest on Y') and clearly states this is a change feed for a company over a time window, aggregating multiple sources in one parallel call. It also distinguishes itself from entity_profile, making the purpose unmistakable.

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

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

Provides explicit guidance on when to use this tool vs. the sibling entity_profile tool: 'Use entity_profile instead when you want the static profile... regardless of window.' Also clarifies supported entity type (company only) and gives typical usage examples (e.g., 'Use "30d" or "1m" for typical monitoring').

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 valuable behavioral context beyond the annotations: persistence semantics (authenticated users get persistent memory, anonymous sessions retain for 24 hours) and key-value scoping. It complements the idempotentHint and readOnlyHint without contradiction.

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

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

The description is well-structured: opens with the core purpose, provides concrete usage examples, then explains storage mechanics and related tools. Every sentence contributes value, and it is appropriately concise for a simple tool.

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

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

Given the tool's simple key-value nature, the description is complete: it explains when to use it, how it behaves across sessions, and how to retrieve/delete data. The lack of an output schema is not a gap because the tool returns no complex result.

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

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

The input schema already covers both parameters with descriptive examples (100% coverage). The description adds the context that values are 'scoped by your identifier', which clarifies how the key is namespaced, slightly enriching parameter meaning.

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

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

The description states a clear, specific purpose: 'Save data the agent will need to reuse later.' It identifies the resource (memory data) and the action (save), and distinguishes itself from sibling tools like recall and forget by explaining that this is the store operation.

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

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

It explicitly provides usage guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also states when to pair with recall and forget, giving clear direction on alternative tools.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds substantial behavioral context: graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR identifiers still return), explicit unresolved identifiers under `unresolved`, source labelling for every identifier, and internal cascading that replaces manual lookups. This goes well beyond annotations.

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

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

The description is long but well-structured, starting with clear examples, then a concise definition, and then breaking down supported types. Every sentence adds value, though the opening list of example queries is somewhat verbose. Front-loading of purpose is strong.

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

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

Despite lacking an output schema, the description fully explains return behavior (identifiers labelled with source, unresolved list), graceful degradation, and supported entity types. For a lookup tool of this complexity, it gives an agent everything needed 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 description coverage is 100%, with detailed descriptions for both `type` and `value`. The description adds examples (AAPL, CIK, 'ozempic') and explains input formats, but it does not significantly add meaning beyond the schema's own parameter descriptions, 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 clearly specifies the verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), with concrete examples like 'What's the ticker for…' and a directive to 'Use FIRST whenever you have a name but need an ID.' It distinguishes from sibling tools by positioning it as the prerequisite step for other tools, covering company and drug identifiers.

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

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

Explicit 'Use FIRST whenever you have a name but need an ID' gives clear when-to-use context, and the examples clarify input types. However, it does not explicitly mention alternative tools or explicitly state when not to use it, so it falls 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral detail beyond annotations: it 'Probes each entity with ai_visibility_check, ranks by score' and returns 'ranked list with score, confidence, signal density per entity'. This informs the user about the internal mechanics and output shape, which is valuable. It does not mention potential latency or multi-call effects, but given strong annotations, this is sufficient.

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

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

The description is three sentences, tight and front-loaded. It states the core action, the method, a use case, and the return format with no wasted words. Every sentence earns its place.

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

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

Given the tool's moderate complexity (multi-entity comparison, dynamic model selection) and the absence of an output schema, the description adequately covers the return value ('ranked list with score, confidence, signal density per entity'). It mentions the key constraint that the first entity is the subject, which is also in the schema. It could add notes about failure modes or rate limits, but it is sufficiently complete for an agent to use effectively.

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 detailed descriptions for all four parameters. The description adds no new parameter semantics beyond what the schema already provides, such as the entities array's first entry being the subject. It echoes the concept but does not enrich it. Thus the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' and specifies it 'Probes each entity with ai_visibility_check, ranks by score'. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison). The purpose is specific and actionable.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"'. It implies this is for multi-entity comparison versus the single-entity ai_visibility_check. It does not explicitly name alternatives or exclusions, but the context is clear enough for a user to know when to invoke it.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description reveals important runtime behaviors: fans out across two services, partial failure degradation, bundlephobia first-measurement latency (5-30s), and the sources_failed field. 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?

Description is front-loaded with the core purpose, then details the fan-out sources, return fields, success/failure behavior, and ecosystem scope. Every sentence carries unique information; it is long but efficient and well-structured.

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

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

For a composite tool with no output schema, the description comprehensively covers inputs, outputs (summary fields, advisories, links, alternative versions), failure modes, timing, and scope. It is fully self-contained for an agent to decide and invoke.

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 both parameters fully (package name, version) and the description mostly restates the schema's own descriptions (e.g., version defaults to latest). Since schema coverage is 100%, baseline is 3, and the description adds no additional parameter meaning.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, with specific verb ('scan') and resource (dependency). It differentiates itself by listing the exact data sources and output fields, making it distinct from any sibling 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 ('whenever an agent asks is X safe / popular / small'), and provides a clear exclusion for non-NPM ecosystems (use deps.dev:version directly). This gives the agent unambiguous guidance.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds implementation details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation and flagging. It also mentions verifiable offsets for quotes, adding useful behavioral context. No contradiction with annotations.

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

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

Three tightly written sentences. Starts with the core action, moves to use case, and ends with technical details. No filler; every clause adds value. The structure is well front-loaded, with the most important information first.

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

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

No output schema exists, but the description explicitly states the return format: top-N passages with character offsets and similarity scores. It also covers the 200K cap, truncation flag, and pairing with ask_pipeworx_grounded, providing enough context for an agent to invoke the tool correctly. The description is complete for the tool's complexity.

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

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

Schema description coverage is 100%, with each parameter (text, limit, query) having a description. The description adds workflow context (pass already-pulled text, natural-language query) and reinforces the 200K char limit, but doesn't add meaning beyond what the schema already documents. However, it clarifies how the parameters interact, giving a 4 instead of 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?

Clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. Differentiates itself from sibling tools by emphasizing it operates on already-fetched text, and explicitly mentions returning top-N passages with offsets and scores. The pairing with ask_pipeworx_grounded further distinguishes its role.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains that it saves context and returns only relevant passages. Provides a direct alternative/companion relationship with ask_pipeworx_grounded, suggesting a workflow. This gives the agent clear decision criteria for when to use this tool versus alternatives.

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

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

The description adds significant behavioral context beyond annotations: requires OAuth, returns subscription id, feed is always on, SMS requires verified phone with 10/day cap, and schema details include webhook auto-disable and one-time signing secret. These are meaningful operational traits not implied by readOnly/destructive/idempotent hints.

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

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

The description is front-loaded with purpose, then auth, then types, then delivery—well-structured and compact. Every sentence adds value, including concrete examples and constraints.

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

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

For a complex tool with nested objects and no output schema, the description covers prerequisites, supported types with examples, delivery channels, and return value. It is sufficiently complete to guide invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters with type-specific examples. The description adds some explanatory color (e.g., 'items:["5.02"] = officer change') but largely mirrors the schema, offering minimal additional 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 uses a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings like list_subscriptions and unsubscribe by stating it returns a new subscription id.

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

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

Usage is implied from the purpose but no explicit alternatives or when-not-to-use are provided. It mentions prerequisites (OAuth account) and alternative pull methods for the feed, but doesn't direct to sibling tools for listing or canceling subscriptions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context beyond that. It specifies the return format (category-bucketed example questions with tool + argument shape), the categories covered, the effect of the topic parameter, and that it draws from the live catalog of thousands of tools. 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 effective; it packs the purpose, output, parameter behavior, and usage guidance into one long paragraph. Every sentence contributes, but the structure could be improved with bullet points or shorter sentences. It is appropriately sized for the information it conveys.

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 that there is no output schema, the description fully explains what the tool returns and how to invoke it. It covers the main use case, the topic parameter, and the source of the suggestions, making it complete for an agent to decide when and how to call it. The lack of mention of pagination or rate limits is not a gap for this onboarding tool.

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

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

The schema describes the single `topic` parameter with a list of possible values, but the description adds meaningful guidance: examples ('finance', 'pharma', 'betting'), instruction to omit for a cross-category spread, and the note that topic focuses the output. This goes well beyond the schema's basic coverage.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point for an agent to discover what questions are worth asking, returning category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings by explicitly saying 'Use this FIRST' and naming the meta-tools it teaches you to call (ask_pipeworx, entity_profile, compare_entities). The verb 'suggest' and resource 'questions' are specific.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional topic filtering and the default behavior when called with no arguments, giving the agent clear context for choosing this tool versus 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?

Even with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds valuable details: ownership enforcement, row deactivation (not deletion), and preservation of historical events via recent_alerts. This meaningfully clarifies the tool's behavior.

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

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

The description is two sentences, front-loaded with the main action, and contains no filler or redundancy. Every sentence contributes useful 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?

Given the tool's simplicity (one parameter, no output schema), the description fully covers the action, constraint, and side effects. The mention of recent_alerts also helps the agent understand the broader context.

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

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

Schema coverage is 100%, with the parameter id already described as 'Subscription id (uuid) returned by subscribe.' The description only echoes 'by id' and adds no new semantic information about the parameter, so the baseline 3 applies.

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

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

The description clearly states 'Cancel a subscription by id' — a specific verb with a resource and method. It also distinguishes the tool's effect (deactivation rather than deletion) from related tools like recent_alerts.

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

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

Provides clear context for when to use (cancel a subscription you own) and mentions ownership enforcement. However, it does not explicitly contrast with sibling tools like subscribe or list_subscriptions, so it stops short of full alternative guidance.

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

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

Beyond the safety annotations, the description discloses critical behavioral nuances: the meaning of 'could_not_verify' as a pipeline failure (not evidence), the distinction with 'unsupported', the existence of an error payload, and the dual structured/grounded pipeline. This is valuable, non-obvious context that agents need.

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

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

The description is longer than average but every sentence adds substance—examples, pipeline details, verdict semantics, and caller warnings. It is well-structured with an 'IMPORTANT for callers' note, though it could be tightened slightly for readability without losing 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?

Despite lacking an output schema, the description fully describes return values (verdict, actual value, reasoning, error fields) and explains edge cases (could_not_verify vs. unsupported). It also covers the tool's relationship to an alternative multi-step workflow, making it very 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?

While the schema covers both parameters with descriptions, the tool description adds important semantic details: tolerance_pct overrides claim wording, is capped at 5 by default, and 'set 1–2 for hallucination detection.' This goes beyond the schema's documentation and helps agents choose correct parameter 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 states a specific verb and resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes this tool from siblings by focusing on fact-checking with verdicts, and even notes that it replaces 4–6 sequential calls, making its niche 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 gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the conditional routing for financial vs. other claims, but does not explicitly name alternative tools or provide exclusions, so it falls slightly 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 cover safety (readOnly, non-destructive, idempotent). The description adds that it returns validity and format details, which is useful but does not disclose limitations such as not checking real-world existence or handling of whitespace/case. 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?

A single, tightly worded sentence that immediately conveys the tool's purpose and output. No filler, front-loaded with the key action, and includes a concrete example.

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 single-parameter validator with rich annotations (readOnly, idempotent) and an output schema, the description provides enough context. It could optionally mention edge cases like case sensitivity or non-existence checks, but the tool's simplicity makes the description largely complete.

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

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

Schema description coverage is 100% with an example already provided. The description repeats the postcode example, adding no significant meaning beyond the schema. Baseline 3 is appropriate since the schema fully documents the parameter.

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

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

The description uses the specific verb 'Validate' with a clear resource 'UK postcode format' and provides an example. It distinguishes from sibling tools like lookup_postcode, which focuses on retrieving data, and random_postcode, which generates postcodes.

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

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

The description implies usage for format validation but does not explicitly state when to use this tool over alternatives such as lookup_postcode or nearest_postcodes. No exclusions or alternative tool guidance is provided, leaving usage context implicit.

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