Snb Ch

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

Annotations already declare read-only, idempotent, open-world, and non-destructive, so the bar for adding value is lower. The description meaningfully adds that the default model is free, that using Anthropic requires a BYO key and direct payment, and that it returns per-model score/confidence/signals/raw_response plus a combined view. This enriches the agent's understanding of cost and external 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?

Three sentences with no redundancy: the first states the action and output, the second covers configuration and cost, the third outlines return structure and use cases. Every sentence earns its place, and the most important information is front-loaded.

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

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

There is no output schema, so the description's explicit mention of per-model {score, confidence, signals, raw_response} + combined view fills that gap. It also covers configuration (default, models, key) and use cases. It could go deeper on how visibility is scored or what 'signals' means, but for an agent seeking to select and invoke the tool, the description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by linking `_apiKey` to the 'anthropic' model (the schema merely says 'optional Anthropic API key') and clarifying that omitting models defaults to workers-ai. This contextual relationship 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 uses a specific verb ('Probe') and resource ('one or more LLMs'), with clear scope ('business / brand / product / topic') and a measurable output ('score visibility (0-100) per model'). It effectively distinguishes itself from sibling tools by emphasizing visibility scoring rather than Q&A or research, and the 'Useful for' list further clarifies its niche.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model vs. the optional Anthropic key with cost implications. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: it routes to 5,621 tools, returns structured answers with citation URIs, works on every tier, and is a single fast call. No contradiction exists.

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 front-loaded with the most critical guidance (prefer over web search, examples, start-here directive). Each sentence contributes value, and the structure is logical: purpose, scope, examples, then alternatives. Slightly verbose 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 a single required parameter and no output schema, the description is remarkably complete. It covers what the tool does, when to use it, how to phrase queries, and directs to alternatives, leaving nothing necessary for correct invocation 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?

Schema description coverage is 100% and all six parameters are aliases for the same question parameter. The description reinforces that the question is natural language and accepts aliases, but that information is already present in the schema. It adds little new meaning beyond the schema.

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

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

The description states the tool answers factual questions about real-world data with citations, listing specific domains (SEC filings, FDA, FRED/BLS, patents, etc.) and giving examples. It distinctly differentiates from siblings like ask_pipeworx_grounded and deep_research, so an agent knows exactly what this tool does and what it is not.

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 instructs to 'PREFER OVER WEB SEARCH' and defines when to use it (factual questions about real-world entities) with specific query patterns and examples. It also names alternatives (ask_pipeworx_grounded, deep_research) and conditions for stepping up, plus notes it's the default entry point for most questions.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds context about beta behavior (candidate routing improvements possibly active, currently matching stable) and confirms it is a working router. This enriches behavioral understanding 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 reasonably concise, front-loading the beta nature and key distinction from ask_pipeworx. It avoids fluff but includes necessary details about routing comparisons and current state. Some repetition about being a full router exists, but it serves to prevent misinterpretation.

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 (universal router with thousands of tools), the description explains purpose, usage, behavioral status, and relationship to siblings. It covers that the response shape matches ask_pipeworx without needing an output schema, and the absence of fallback is clarified. No critical information for an agent to decide to use it is missing.

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

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

Schema coverage is 100%, so all six parameters are documented in the schema, including aliases for the required question field. The description adds no further parameter-level semantics beyond stating the tool takes arguments, which is marginal given full schema coverage. Baseline of 3 is appropriate.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, a universal router with 5,621 tools, and that it takes a natural-language question. It differentiates from siblings by explicitly naming stable ask_pipeworx and grounded variant, establishing it as the experimental edge.

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: use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared to the stable router. It also clarifies there is no fallback; it is a fully functional router, eliminating ambiguity about availability.

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 provide readOnly, openWorld, idempotent, and non-destructive hints, but the description adds significant behavioral detail beyond that: it explains the extraction process, the exact output structure (including refusal reasons), and the extra LLM call cost. All of this is transparent and complements the annotations 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 somewhat long but every sentence carries critical information: behavior, return format, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the core purpose and then details, with no fluff. It could be marginally trimmed, but it earns a 4 for density and structure.

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

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

This description is exceptionally complete: it covers the tool's purpose, behavior, output structure (including exact refusal reasons), when to use it vs. alternatives, and the cost implication. Despite lacking an output schema, it fully describes the return value. There are no critical gaps for an agent to resolve before calling 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?

Schema description coverage is 100% and the parameters are all aliases for the single 'question' parameter, which the schema fully documents. The description does not add parameter-specific semantics, but none are needed since the schema is exhaustive. Baseline 3 is appropriate when the schema handles parameter documentation.

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 ('ask') with a resource (Pipeworx grounded mode), and explicitly contrasts with the sibling ask_pipeworx by adding the hallucination-resistant extraction behavior. It distinguishes itself immediately with 'Hallucination-resistant answer mode' and explains the routing mechanism, making the tool's purpose unmistakable.

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

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

The description explicitly states when to use this tool ('Use whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), directly referencing the alternative and the cost tradeoff. This is textbook usage guidance with no ambiguity.

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

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

Despite safe-read annotations (readOnlyHint=true, destructiveHint=false), the description goes far beyond them, disclosing fan-out patterns, response shapes, resolver contracts, safety short-circuiting, closed-market handling, wide-spread warnings, and cancellation-rule risks. It adds rich behavioral context that is essential for safe and correct use, with no contradictions.

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

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

The description is long but densely packed with operational details. It is front-loaded with a clear purpose sentence and organized into labeled sections (CLASSIFIERS, FAN-OUT, RESPONSE, SAFETY, etc.), making it navigable. While some sentences could be trimmed, the length is justified given the tool's complexity and the critical safety information conveyed.

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

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

With no output schema, the description thoroughly documents return shapes: result.market fields, result.analysis fields, result.evidence keying, resolver contract (market_match_confidence, score, alternatives, suggestions), parent_event extractor, news fallback fields, and statuses for low-confidence and closed markets. It is complete for an AI agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% (3 parameters, all documented). The description adds meaning beyond the schema, particularly for the 'market' parameter by explaining how slug/URL/question text are resolved and that this drives category-specific fan-outs. It also gives examples that illustrate the parameter syntax, adding value over the bare schema.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool's scope (Polymarket bet research with market-vs-model comparison) and provides concrete examples, making its purpose unmistakable and distinct from siblings.

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 gives use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This clearly indicates when to use the tool. It does not explicitly name alternatives or exclusions, but the context is clear and the examples cover common scenarios, so a 4 is appropriate.

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

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

Beyond the readOnly/idempotent annotations, the description discloses significant behavioral details: pulls from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This adds valuable context not available 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 every sentence adds value: trigger phrases, usage rule, data sources, metrics, sorting, output. Slightly longer than necessary but well-structured and front-loaded with examples.

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

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

Despite no output schema, the description fully informs the agent about input, behavior, and output expectations. It covers data source nuances (fiscal calendar), sorting logic, and result format, making it highly complete for a comparison 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 enum and array constraints, so the baseline is 3. The description enriches parameter meaning by giving concrete examples for companies (tickers/CIKs) and drugs (names), and explains what data each type pulls, which goes beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs, using specific verbs like 'compare', 'rank', 'head to head'. It distinguishes itself from sequential lookups and provides concrete example phrases.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a clear directive on when to use this tool versus the alternative of multiple lookups. It also lists trigger examples and explains the two entity types.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: the default cube ID (devkua), the list of verified-live IDs, and what each ID represents. It does not describe return format, but given the simple tool and no output schema, the added context is valuable.

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

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

The description is four sentences, all purposeful: purpose, usage, verified IDs, and default. It is front-loaded with the core action and immediately clarifies value. No redundant phrasing or padding.

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

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

For a tool with one optional parameter, no output schema, and rich annotations, the description provides complete context: what it does, when to use it, what inputs are valid, and the default. The mention of 'dimension items / series keys' hints at the response nature, making it adequately comprehensive.

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

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

Schema coverage is 100% with a description and examples for cubeId. The description enriches this by explaining what each cube ID means (e.g., devkua = foreign exchange rates, zimoma = money market), which is not present in the schema. This helps the agent select appropriate 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 starts with a specific verb ('Fetch') and resource ('Swiss National Bank cube's dimensions/structure'), and clarifies with parenthetical detail ('dimension items / series keys'). It explicitly contrasts with sibling get_cube by stating 'Use this to understand what a cube contains before/after calling get_cube', clearly distinguishing 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?

The description gives explicit usage context: use it before/after get_cube. It also provides a list of verified-live cube IDs with meanings, which guides the agent on valid inputs and when to apply each. No alternative is named, but the relationship to get_cube is sufficient.

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 carry readOnlyHint/openWorldHint/idempotentHint/destructiveHint, and the description stacks substantial context on top: latency expectations (15-60s, thorough up to ~90s), auth/pricing requirements, the gap[] behavior (never invented), the contradictions[] scan, semantic excerpting, the conditional citation_uri, and hop-field semantics. No contradiction with annotations — 'grounded' and 'never invented' are consistent with the read-only, 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?

Critical info (account requirement) is front-loaded and nearly every sentence adds value. However, it is genuinely long with some redundancy — ask_pipeworx is named as the alternative three separate times (single lookup, breaking news, unsigned-in), and the 'in ONE call / NOT open-web search' point is restated. It could be tightened without losing meaning.

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

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

With no output schema, the description fully compensates by explaining the return packet (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field) and handling edge cases (empty gaps[] for news topics, only-present-when-fetchable citation_uri, excerpting of large records). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and both parameters (question, depth) are already well documented. The description adds value beyond the schema by tying depth to cost (thorough needs a paid plan), latency, and iteration behavior (gap recovery vs. lead chasing), plus guidance on question scope. This goes beyond the baseline 3.

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

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

States a specific, differentiated purpose: grounded multi-source research across 1,472 structured data sources in one call, decomposing questions into facets routed in parallel to 5,621 tools. It explicitly contrasts with open-web search and names the sibling it is not (ask_pipeworx), so an agent can select it correctly.

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 exceptional usage routing: best for broad/multi-part questions over structured data, use ask_pipeworx for a single lookup, and prefer ask_pipeworx for breaking/current-news topics (with the rationale that deep_research returns empty gaps[] for non-catalog topics). Also documents the account prerequisite and alternative for unsigned-in users.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral value by disclosing the return format (top-N tools with names, descriptions, full input schemas, curated examples) and the convenience of being 'ready to call directly, no second schema lookup needed' — useful context 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 three sentences and front-loaded with the core purpose. The second sentence lists many domains, which is informative but a bit long; however, it earns its place by clarifying scope. 'Call this FIRST' is a concise actionable guideline. Overall efficient with minimal fluff.

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

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

Given no output schema, the description sufficiently explains return values (names, descriptions, schemas, examples) and the 'no second lookup' benefit. It covers purpose, context, and usage guidance well. Minor gaps like result ordering or pagination are not critical for a discovery tool with safe annotations.

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

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

The input schema is very complete (100% coverage) with descriptions for query and its aliases (q, task, search, description) plus limit. The tool description adds little beyond 'describing the data or task' and 'top-N', which the schema already conveys. Baseline 3 is appropriate because the schema carries the parameter semantics.

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

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

The description opens with 'Find tools by describing the data or task' — a specific verb and resource that clearly states the tool's meta-purpose. It distinguishes itself from sibling tools by positioning itself as a discovery/exploration layer over the actual task tools, listing many domain examples to clarify scope.

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

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

The description gives explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies you would not use this when you already know the exact tool, though it doesn't explicitly name alternatives.

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

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

Annotations already cover readOnly and idempotent safety. The description adds valuable behavioral context: parallel fan-out across sources, soft-fail behavior for the sunsetting USPTO PatentsView API, GDELT→GNews fallback, and specific return fields. It also discloses input limitations (names not supported). Minor omission: no mention of response format or potential latency, but the described behaviors are substantial.

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

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

The description is a single dense paragraph with front-loaded example queries and a clear structure: purpose, usage preference, source list, return details, and input constraints. Some redundancy exists (e.g., 'full cross-source profile' vs. 'fans out across'), but overall it conveys a lot of information without excessive verbosity.

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

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

Given the tool's complexity and absence of an output schema, the description is remarkably complete. It specifies all return fields (cik, filings, fundamentals, patents, news, LEI), fallback behaviors, input constraints, and usage guidance. This is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema already provides 100% coverage for both parameters, including examples and the name restriction. The description reinforces with concrete formats ('AAPL' vs '0000320193') but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb phrase 'full cross-source profile of a US public company' and enumerates concrete data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It distinguishes itself from sibling tools by explicitly preferring this over chaining single-pack lookups and contrasting with resolve_entity 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') and an alternative path ('use resolve_entity first if you only have a name'). This clearly directs the agent on tool 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 destructiveHint=true and idempotentHint=true. The description adds some context about clearing 'sensitive data' and pairing with memory tools, but does not add significant behavioral details beyond what annotations convey.

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

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

The description is concise, with the main action front-loaded in the first sentence. The second sentence adds usage context efficiently without redundancy.

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

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

For a simple one-parameter delete tool with annotations covering destructiveness and idempotency, the description provides enough context for an agent to select and invoke it correctly. It includes when to use and related tools, making the description 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%, and the parameter description 'Memory key to delete' is clear. The tool description reinforces the 'key' parameter but does not add additional meaning or syntax 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 action: 'Delete a previously stored memory by key.' This is a specific verb+resource combination and distinguishes the tool from siblings like 'remember' and 'recall' by indicating a destructive delete 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?

The description provides clear context on when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also pairs with 'remember and recall,' but does not explicitly mention when not to use it or name alternatives beyond these siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that the tool fetches the page and extracts specific elements, plus the output format (standard llms.txt markdown). It explicitly states the output is a single text blob, which is helpful.

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

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

The description is two sentences, front-loaded with the core purpose and process, followed by practical use cases. Every sentence adds value 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?

Despite lacking an output schema, the description explains the output as a single text blob and clarifies where to deploy it. Combined with the annotations and parameter schema, the tool is fully understandable.

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

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

Schema coverage is 100%; both url and max_links are described with meaningful descriptions. The description does not add parameter-specific details beyond the schema, which is acceptable given the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb (generate) and resource (llms.txt file). It distinguishes itself by describing the process (fetches, extracts, emits) and names the target AI crawlers (ChatGPT, Claude, Perplexity).

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 use cases: getting a client's site indexed, drafting for one's own project, or auditing a competitor. It does not name alternative sibling tools, but the scenarios give clear context for when to use it.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses that cube discovery is limited to a set of verified-live IDs and provides the exact list and default, which are crucial for correct invocation. No contradiction with annotations.

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

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

Two sentences, front-loaded with the action and output type. The ID mapping is compact and efficient, with no fluff.

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

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

For a single-parameter tool with no output schema and strong annotations, the description fully covers what the agent needs: purpose, valid inputs, default, and output format. Nested or complex behavior is absent.

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

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

The schema already has a description for cubeId, and the tool description enriches this by mapping each known ID to its semantic meaning (e.g., devkua = FX rates). This goes beyond the schema's basic example list.

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 'Fetch' as a specific verb and identifies the resource as 'Swiss National Bank statistical data cube's time series'. It distinguishes from sibling cube_structure by focusing on time series data, not structure.

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 by listing four valid cube IDs and their meanings, and states the default. However, it does not explicitly mention when to use this vs alternatives like cube_structure, so no explicit 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 indicate read-only, idempotent, non-destructive behavior. The description adds value by specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and the notion of 'active' subscriptions, which is beyond the annotation metadata.

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

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

The description is two sentences, front-loaded with the main purpose and return fields, followed by a concise usage tip. Every word contributes value and there is no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It states the scope (caller's subscriptions), the return fields, and provides context for when to use it relative to adding or cancelling subscriptions. No significant information is missing.

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

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

The schema description coverage is 100%, so the single parameter include_inactive is fully documented in the schema. The tool description does not mention the parameter or add additional semantics, so it stays at the baseline of 3.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It also enumerates the returned fields, and the usage note about finding an id to cancel implicitly distinguishes it from subscribe/unsubscribe tools.

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

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

The description provides explicit use cases: review existing subscriptions before adding more, or find an id to cancel. It does not mention explicit alternatives or when-not-to-use, but the context is clear enough to guide tool 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?

Despite annotations already indicating non-readonly and non-idempotent behavior, the description adds substantial context: returns a claim_token for anonymous filing, rate limit of 5 per identifier per day, free/no quota impact, team reads digests daily, and roadmap influence. No contradiction with annotations.

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

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

Although the description is long, every sentence earns its place: purpose, usage triggers, exclusions, claim_token flow, rate limits, and quota status. It is front-loaded with the purpose and immediately gives actionable guidance.

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

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

Given four parameters, a nested context object, no output schema, and no required params, the description covers all essential operational aspects: what counts as valid feedback, how to file anonymously, how to retrieve status later, and practical constraints (rate limit, quota). It is fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond schema by explaining the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed') and by instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, which directly enriches message/context semantics.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from all sibling research/discovery tools and explicitly enumerates feedback types (bug, feature/data_gap, praise).

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 triggers ('wrong/stale data', 'tool you wish existed', 'worked surprisingly well') and an explicit exclusion ('ONLY for tools served by this Pipeworx connection... file it with that server instead'). Also clarifies how to identify Pipeworx tools and how to use claim_token for follow-up.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description adds valuable context: it is self-aggregating, derived from CF analytics-engine, excludes PII, returns only (pack, tool, count), and caches for 5min-1h depending on window. This enriches the agent's understanding of data freshness and privacy 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 well-structured and front-loaded with the purpose, followed by a numbered list of use cases and a concise note on aggregation and caching. No unnecessary filler, though it could be slightly tighter.

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 explains the return categories (top tools, top packs, total call volume) and the data format (pack, tool, count). It also covers caching and data source, making it complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100% with a descriptive enum for 'window' explaining the default and trade-offs. The description mentions the window values but adds no new meaning beyond what the schema already provides, so it meets the baseline without going further.

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 'What other AI agents are calling on Pipeworx right now' and explicitly states it 'Returns the top tools, top packs, and total call volume over a recent window.' This clearly identifies the verb (returns), resource (Pipeworx trending), and unique scope (other agents' usage), distinguishing it from sibling tools like discover_tools or ask_pipeworx.

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

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

The description lists three concrete use cases: discovering hot data sources, confirming canonical tool choice, and aligning with agent needs. This provides clear 'when to use' guidance, though it does not explicitly mention when *not* to use it or name 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations providing baseline safety, the description adds significant behavioral depth. It warns that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it,' and explains the partition filter's placeholder handling that can return null. These are non-obvious traits that impact decision-making, going 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 long but every sentence carries essential information, organized with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and separate mode explanations. It is front-loaded with the core purpose and then details edge cases and response formats. No filler or redundancy exists; each part earns its place given the tool's complexity.

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

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

With no output schema, the description fully specifies the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{...}' for event mode. It also covers failure modes, fill-check behavior, and relationship to another tool. For a tool with two optional parameters and multiple modes, this is complete and self-sufficient.

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

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

While the schema already covers both parameters with descriptions, the tool description greatly enriches them. It provides concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), clarifies that full URLs are accepted for event, and explains the behavioral differences between event and topic modes. This adds meaning beyond the schema, making parameter choice intuitive.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly states the tool's function and methodology, and distinguishes between three modes (trending scan, event, topic) without confusing the reader. This is far more specific than the generic title and effectively sets it apart from sibling tools.

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

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

The description gives explicit usage instructions: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative tool for a related but distinct need: 'For custom sizing use polymarket_fill_risk.' This provides clear context for when to use this tool and when to defer to another.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: caching behavior ('Cached 1h at the KV level keyed on all knobs'), edge calculation details ('edge_pp_net (after slippage)'), the 24h-move warning, the diagnostics funnel counters, and the special Kelly handling for partition overrounds. This far exceeds what annotations provide.

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

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

The description is a single, extremely dense paragraph without any bullet points or section breaks. While every sentence carries relevant information, the lack of structure makes it harder to parse. It is appropriately sized for the tool's complexity but poorly organized, earning a 3.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the logic behind each model segment. It also covers caching and why certain segments might be empty. This is complete for a complex tool.

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

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

The input schema already documents all 9 parameters at 100% coverage. The description adds inter-parameter context that the schema cannot convey, such as the relationship between min_kelly and min_partition_leg_kelly (partition arbs ignore min_kelly), and the fact that slippage_pp is subtracted before ranking. This goes beyond the schema descriptions.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from sibling tools like polymarket_arbitrage (likely for cross-market arbitrage) and polymarket_edge_tracker (likely for tracking edges over time).

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 the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also mentions nuances like Fed bets being excluded from ranking. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it misses the exclusion criteria for a 5.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds significant context beyond these: snapshot TTL limits, cache-miss behavior causing gaps, signed edge_pp_net semantics, and decay computation methodology. This fully discloses behavioral traits and edge cases.

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

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

The description is long but well-structured with labeled sections (Args, RESPONSE, LIMITS) and front-loaded with the core purpose. Every sentence carries useful information, though it could be slightly more compact 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?

With no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates), including edge cases like data gaps and TTL. It also covers limitations and methodology, making it complete for an agent to invoke 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 coverage is 100% for both parameters. The description adds context about 'window' being a snapshot family and clarifies the meaning of the signed value, which helps the agent understand parameter semantics beyond the schema. While not strictly necessary, it enhances 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 the tool's function: tracking edge persistence and decay over time using daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and differentiates itself from sibling tools like polymarket_edges by focusing on telemetry rather than edge computation.

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

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

The description implies when to use the tool by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), giving a clear use case. However, it does not explicitly name alternatives or state when not to use it, though the sibling context makes the differentiation clear.

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

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

Annotations already declare readOnly/idempotent/destructive hints, and the description adds substantial behavioral context: it walks the order-book ladder, returns specificity like top_of_book/vwap_fill_price, and warns about partial fills converting arb into directional exposure. 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?

Though long, the description is tightly structured with purpose, a REQUIRES clause, distinct SINGLE-MARKET and BASKET sections, and a usage callout. Every sentence adds operational value; no filler or redundancy.

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

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

For a complex tool with no output schema, the description enumerates all critical return fields for both modes, including risk outputs like thin_legs[] and forced_directional_risk. It covers prerequisites, mode semantics, and failure modes, making it essentially self-sufficient for an agent to decide 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%, and the description adds mode-specific semantics beyond the schema: size_usd is 'max spend' for buys vs 'target proceeds' for sells, and for basket mode it means settlement notional S (shares per leg). It also documents the default 1000 and clamp range, significantly enriching the parameters.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-trade risk check, and it details both single-market and basket 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 explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and provides the reasoning (theoretical overround not capturable, partial basket fills create unhedged directional risk). This gives concrete triggers and contrasts with alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses rich behavioral details: how modes work, response structure (leg-by-leg prices, spread[].top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), and the meaning of edge cases like matched_pairs:0. It also warns about 'pre-mapped ≠ tradeable', adding significant context not available from annotations.

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

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

The description is dense and well-structured, starting with the core purpose, then modes, response, and safety fields. Every sentence adds useful information, though it is quite long and could be slightly tightened without losing value. The use of capital letters for modes and key terms improves scanability, but the density may challenge quick consumption.

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

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

With no output schema, the description carries the full burden of explaining return values, which it does thoroughly: leg-by-leg prices, matched spread, and safety fields. It covers edge cases (compatibility_warning conditions, temporal alignment, skipped legs) and provides enough context for an agent to understand when results are meaningful. This is a complete description for a complex 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 lists three parameters with basic descriptions, but the description adds semantic depth: it explains the 'topic' mode with 10 pre-mapped values, and clarifies that kalshi_event_ticker and polymarket_event_slug override the topic-mapped defaults. This goes beyond the schema's coverage, which already mentions the enumeration but not the override behavior or response interplay.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from siblings like polymarket_arbitrage by focusing on comparing the same question across two venues. The description also clarifies scope by noting that pre-mapped topics may not be tradeable, reinforcing its unique 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?

The description provides clear when-to-use context: compare Kalshi and Polymarket prices for equivalent bet shapes, with two modes (topic shortcuts or explicit tickers). It warns that pre-mapped topics often return compatibility_warning, guiding users to expect non-tradeable results. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it misses the full 'alternatives' criterion.

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. The description adds valuable context beyond annotations, such as scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the dual retrieval/list-all 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?

Three sentences, all informative with no redundancy. Front-loaded with the action verb 'Retrieve' and flows logically from action to usage to scoping to companion tools.

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

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

With no output schema, the description clarifies both usage modes: retrieving with a key and listing all keys by omitting it. Scoping and relationships to remember/forget provide complete operational context for this simple read-only 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%, and the description reinforces the optional key semantics by saying 'omit the key argument' to list all. It adds meaningful examples of keys (target ticker, address, prior research notes) that go beyond the schema's minimal property description.

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

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

Description opens with 'Retrieve a value previously saved via remember' — a specific verb and resource. It also covers the alternate use case of listing all saved keys, which clearly distinguishes it from sibling tools like remember and forget.

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

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

Explicitly states when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It also names companion tools and their roles: 'Pair with remember to save, forget to delete,' providing clear alternative paths.

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 describes a mutation side effect with mark_read:true, but annotations declare readOnlyHint=true. This is an annotation contradiction, which misleads agents about the tool's safety profile. Despite the description being transparent about the mutation, the contradiction warrants a score of 1 per the rules.

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

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

The description is concise and front-loaded with the core purpose. Each sentence adds unique information: return format, filtering, mark_read side effect, polling advice, and alternative endpoint. No filler or redundancy.

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

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

For a tool with no output schema, the description sufficiently explains return values (source, citation_uri, raw event payload), filtering options, mark_read behavior, polling suitability, and an alternative HTTP access. This is complete given 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 coverage is 100%, so the baseline is 3. The description adds value by giving a concrete type example ('sec_8k'), explaining mark_read behavior (flagging events read for subsequent calls), and clarifying the since parameter as an ISO timestamp. This exceeds the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns the most recent alerts. It uses specific verbs ('Pull', 'Returns') and resource ('subscription feed', 'persisted feed'), and distinguishes itself from siblings like subscribe and list_subscriptions by focusing on retrieving events rather than managing subscriptions.

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

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

Provides clear context on when to use the tool (polling, reading alerts) and explicitly mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts and dashboards, implying this tool is for interactive use. It does not explicitly exclude other tools, but the guidance is sufficient.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive, but the description adds essential runtime behavior: fan-out to multiple sources, GDELT→GNews fallback triggers, and PatentsView sunset soft-fail. This goes well beyond the annotations and clarifies what the agent should 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 dense but each clause contributes: triggers, sources, fallback, time handling, return shape, and alternative tool. It could be better structured with bullets, but it's not bloated; the length is justified by inherent complexity.

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

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

For a multi-source aggregation tool with no output schema, the description covers trigger phrases, sources, fallback logic, soft-fail behavior, `since` formats, return structure (changes[], total_changes, citation URIs), and the sibling alternative. This is comprehensive.

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

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

Schema covers all three parameters with descriptions, but the description enriches `since` with concrete formats ('2026-04-01', '7d', '3m') and a recommended value ('30d'/'1m'). It also clarifies `value` accepts ticker or zero-padded CIK, adding practical examples beyond 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 natural-language query examples, then states the precise action: a change feed for a company over a time window in one parallel call, fanning out to SEC, GDELT/GNews, and USPTO. It clearly differentiates from entity_profile, which serves the static 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 names entity_profile as the alternative when a static profile is desired, and advises '30d' or '1m' for typical monitoring. It also explains fallback conditions (GNews on rate-limit/5xx) and soft-fail for patents, giving concrete use context.

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

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

Annotations already establish non-read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: persistence differences between authenticated users and anonymous sessions (24 hours) and key-value scoping by identifier. It does not mention whether storing an existing key overwrites the value, but the idempotentHint partially covers that.

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 contains five sentences, each adding necessary information: the core purpose, usage signals, storage structure, persistence rules, and related tools. There is no filler or repetition of structured data.

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 only two required parameters, no output schema, and annotations are present. The description covers purpose, when to use, persistence behavior, and sibling relationships. Minor gaps like overwrite semantics and response format prevent a perfect score, but the description is largely complete for a simple memory store.

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 confirms the key-value model and mentions scoping by identifier, but it does not add meaningful detail about the key/value parameters beyond what the schema already provides.

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

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

The description opens with a specific action ('Save data the agent will need to reuse later') and identifies the resource as key-value memory. It clearly distinguishes the tool from siblings by explicitly naming recall and forget as its counterparts for retrieval and deletion.

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

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

The description provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward') and gives concrete examples. It mentions pairing with recall and forget, though it doesn't explicitly state when not to use it 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: it identifies that the tool cascades through several lookup endpoints internally, degrades gracefully if GLEIF or OpenFIGI are unavailable, and explicitly lists unresolved identifiers under `unresolved` rather than omitting them. These details are not present in the readOnlyHint/openWorldHint/idempotentHint annotations and help the agent understand the tool's behavior in edge cases.

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

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

The description is long but structured: it front-loads examples and the core purpose, then details supported types, source behavior, and failure modes. Each sentence contributes important operational details for a complex lookup tool. While it could be trimmed slightly, the organization is clear and the content is relevant, earning a 4 rather than a 5.

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

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

There is no output schema, so the description must explain return values, and it does thoroughly: for companies it lists CIK, ticker, LEI, FIGI, and labels with sources; for drugs it returns RxCUI, ingredient, brand, and a citation. It also covers edge cases like non-US issuers and graceful degradation. Given the tool's complexity and the absence of an output schema, this description is highly complete.

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

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

The input schema already provides 100% coverage with descriptions for both parameters and an enum for 'type,' so the baseline is 3. The description adds extra meaning by mentioning ISIN as an accepted input for 'company' (not listed in the schema) and explaining that an ISIN resolves to the legal entity via GLEIF mapping. This goes beyond the schema's basic syntax and enriches the semantics.

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

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

The description opens with concrete natural-language examples, then clearly states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also adds the directive 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from sibling tools like entity_profile or compare_entities that operate on already-resolved entities.

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

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

The description gives explicit usage context by saying 'Use FIRST whenever you have a name but need an ID' and provides example queries that illustrate when it should be invoked. It also notes that it replaces 2-3 manual lookups, implying a preference over multi-step alternatives. However, it does not explicitly name alternatives or state exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral detail: it 'probes each entity with ai_visibility_check', 'ranks by score', and returns 'score, confidence, signal density per entity'. This goes beyond the annotations by explaining the underlying process and output, though it does not mention potential rate limits or error 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 tight and front-loaded: three sentences that cover purpose, usage context, and return format without fluff. Every sentence adds value, and the structure flows logically from 'what' to 'when' to 'output'.

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 correctly takes responsibility for explaining the return value ('ranked list with score, confidence, signal density per entity'). It also covers the invocation flow (probes via ai_visibility_check). Minor gaps include not explicitly stating the 2-8 entity constraint (though in schema) or error handling, but for an agent's selection and invocation it is sufficiently complete.

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

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

Schema description coverage is 100%, with all four parameters described in detail (e.g., entities array includes the first-as-subject rule). The tool description adds little beyond repeating this, such as 'your brand + N competitors', which is already in the schema. Therefore the baseline of 3 applies.

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

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

The description clearly states the tool's purpose with specific verbs and resources: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling tools like ai_visibility_check by focusing on multi-entity comparison and ranking, explicitly mentioning 'your brand + N competitors' and delivering a ranked list.

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

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

The description provides clear context for when to use the tool: 'Useful for competitive AI-marketing audits' and gives an example query. It implies this tool is for side-by-side comparison versus single-entity checks, but it does not explicitly exclude alternatives or name sibling tools, stopping short of a full 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 readOnly/idempotent annotations, the description reveals composite behavior, partial failure handling, and latency expectations: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' It also details the return summary block, per-advisory detail, and links, adding significant insight 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?

Despite being one of the longer descriptions, every sentence serves a purpose: core purpose, usage triggers, output details, ecosystem scope, and failure behavior. It is front-loaded with the primary use case and structured logically, making it easy to parse without unnecessary verbosity.

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

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

For a composite tool with no output schema, the description fully compensates by listing the exact summary fields, per-advisory details, links, and alternative versions. It also covers ecosystem limitations, potential latency, and degradation behavior, making the tool's behavior and returns fully understood.

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

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

The schema already provides 100% coverage of both parameters (package and version) with clear descriptions. The description adds no new parameter semantics beyond what the schema states, such as 'version defaults to the latest published version when omitted' which is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite check for 'should I add this npm package to my project', with specific verbs like 'scan' and 'fans out' across deps.dev and bundlephobia. It differentiates itself from siblings by focusing on npm package evaluation, distinct from the other research/analysis tools like bet_research or deep_research.

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

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

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

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds rich behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine, 500-char overlapping windows, and truncation flagging beyond the 200K cap. These are meaningful disclosures beyond the structured fields.

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

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

Every sentence earns its place: first defines the action, second gives use cases and benefits, third suggests a complementary tool, fourth details technical behavior. Front-loaded with the core purpose and 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?

For a tool with no output schema, the description explains the return type (top-N passages with offsets and scores), the truncation behavior, and the context of use. It covers the tool's operation and output expectations comprehensively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond the schema by giving examples of what to pass (e.g., SEC 10-K body) and example queries, plus the natural-language query concept, strengthening 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 opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by contrasting with ask_pipeworx_grounded and mentioning it searches within already-fetched content, not the whole knowledge base.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names the alternative ask_pipeworx_grounded and explains the pairing (fetch with the gateway, ground over relevant passages), providing clear decision guidance.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses important behavioral traits: returns a subscription id, requires authenticated accounts, describes delivery channels with phone verification and a 10/day SMS cap, and notes the feed is always on. This adds value without contradicting any 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 moderately long but every sentence contributes value. It is front-loaded with the core purpose, then covers requirements, types, and delivery channels in a logical order. No filler or redundancy.

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

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

Given the tool's complexity (nested objects, multiple subscription types, delivery channels) and the absence of an output schema, the description covers the essential aspects: purpose, return value, authentication, types, and delivery options. It omits webhook details from the main description (though present in the schema), but remains sufficiently complete for an agent to understand and correctly invoke the tool.

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

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

The input schema has 100% description coverage, but the tool description adds practical meaning beyond the schema, such as explaining that items:["5.02"] means officer change for sec_8k and giving specific examples for each type. This enhances parameter understanding beyond the structured schema descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb+resource and distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation. It also details supported subscription types, adding further specificity.

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 requires a Pipeworx OAuth account, explains the always-on feed delivery and how to pull alerts (via recent_alerts or GET), and notes optional email/SMS with constraints. It doesn't explicitly contrast with alternative tools, but it clearly implies this tool is for creating subscriptions, not managing or listing them.

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, covering safety. The description adds meaningful behavioral context: it returns categorized example questions with tool/argument shapes, supports topic filtering, and is drawn from the live catalog. This goes beyond the annotations without contradicting them.

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

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

The description is longer than average but efficiently packs multiple example user intents, the return payload, topic filtering, and usage guidance into a single structured paragraph. Every sentence contributes to understanding the tool's purpose and invocation, though it could be slightly tighter.

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

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

With only one optional parameter and no output schema, the description carries the burden of explaining return values and usage context. It clearly describes the categories returned and the tool-shape inclusion, and provides a list of related meta-tools. It is sufficiently complete for guiding an agent, though it omits details like response size or potential edge cases.

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

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

The input schema fully documents the optional 'topic' parameter with its allowed values and the default full-spread behavior (100% coverage). The description repeats this information with examples, adding minimal extra semantic value beyond what the schema already provides.

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

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

The description clearly identifies this as the onboarding entry point for discovering what Pipeworx can do, explicitly stating it returns category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings by mentioning meta-tools and framing itself as the 'Use this FIRST' 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?

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') and describes parameter behavior (omit for full spread, pass topic to focus). It does not explicitly mention when not to use it or compare to similar siblings like discover_tools, but the context is clear.

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

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

Beyond the annotations (which already indicate a non-read, non-destructive, idempotent operation), the description adds key behaviors: ownership enforcement (only own subscriptions), and that the row is deactivated rather than deleted, preserving historical events via recent_alerts. This provides context not captured in 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 short sentences, each adding essential information: the action, the ownership rule, and the deactivation behavior. It is front-loaded with the core function and contains no filler.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all essential operational details: the required id, ownership constraint, and the non-destructive nature of the cancellation. It even connects the deactivation behavior to the recent_alerts tool, providing a complete picture for an agent.

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

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

The input schema already provides full coverage (100%) for the single `id` parameter with a description referencing subscribe. The tool description only restates 'by id' and adds the ownership constraint, which doesn't enhance the semantic meaning of the parameter itself. With high schema coverage, 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 opens with a specific verb+resource ('Cancel a subscription by id'), clearly distinguishing it from sibling tools like subscribe, list_subscriptions, and recent_alerts. The ownership constraint further clarifies scope.

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

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

The description implies when to use the tool (when you have a subscription id from subscribe and want to cancel your own subscription). It provides context about ownership and deactivation, and explicitly mentions that historical events remain accessible via recent_alerts, which helps an agent decide between this tool and alternatives. However, it doesn't explicitly state when not to use it or name alternatives directly.

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

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

The description goes well beyond annotations by detailing the verdict types, distinguishing could_not_verify from unsupported, and instructing callers not to treat could_not_verify as evidence. It also discloses the dual execution paths, which is critical behavioral context not available in the annotations.

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

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

The description is long but every sentence earns its place, with front-loaded examples and a clear structure that culminates in the callers-important caveat. The length is justified by the tool's complexity and the need to explain error semantics.

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 enumerates the return components (verdict, actual value with citation, reasoning) and clarifies the meaning of each failure verdict. It fully equips the agent to understand expected results and how to interpret them.

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 descriptions for both parameters (100% coverage), so the baseline is 3. The description adds meaningful extra context: it explains tolerance_pct overrides the claim's implied tolerance, provides a usage range, and recommends 1–2% for hallucination detection, which the schema lacks.

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 a specific verb+resource: natural-language claim verification against authoritative sources, listing example query forms. It distinguishes itself from sibling tools by describing its verdict output and the two-path architecture (SEC EDGAR vs grounded pipeline), making its unique role clear.

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 whenever the agent needs to check whether something a user said is factually correct,' giving clear when-to-use guidance. It doesn't name alternative tools or provide exclusions, but it does explain the automatic fallback for any non-financial claim, which helps routing decisions.

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