Bpstat Pt

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds that the default model is free, while using Anthropic requires a BYO key (cost implication), and describes the return structure (per-model + combined view). 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?

Three sentences: main function and default model, optional Anthropic with cost note, return structure. No fluff, front-loaded with key information. Every sentence contributes meaning.

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

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

Given 4 parameters, no output schema, and annotations present, the description covers all parameters, provides use cases, and describes the return format. Sufficient for an agent to understand when and how to invoke the tool correctly.

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

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

Schema coverage is 100% with parameter descriptions. The tool description adds value by explaining default model behavior, when _apiKey is needed, and that context helps disambiguate. This goes beyond the schema by providing usage context and cost implications.

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

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

Clearly states the tool probes LLMs for visibility of an entity and provides a score (0-100). Identifies default model and optional Anthropic integration. Distinct from sibling tools like deep_research or entity_profile, focusing specifically on AI visibility auditing.

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

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

Explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not mention when not to use or alternatives, but context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations: it mentions routing, argument filling, citation URI stability, performance ('one fast call'), and tier availability. It does not contradict annotations and provides additional operational expectations.

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

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

The description is long but front-loaded with the most important directive and flows logically from comparison to use cases to examples to escalation path. It could be trimmed slightly—some examples and repetitions could be tightened—but the density is justified given the tool's central role and the need to differentiate from multiple siblings.

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

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

Given the tool's high complexity and absence of an output schema, the description is remarkably complete: it covers scope, result type, citation format, performance, tier compatibility, alternative escalation paths, and provides multiple usage examples. This is more than sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with aliases fully documented, so the baseline is 3. The description adds semantic value by providing many example natural-language queries and explaining the breadth of acceptable inputs (filings, drugs, stats, patents, etc.), which helps the agent formulate effective questions beyond the schema's terse parameter 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 routes questions to 5,562 tools across 1462 sources and returns structured answers with stable pipeworx:// citation URIs. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, making its purpose and scope immediately apparent.

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 ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when-to-step-up guidance ('Step up only when needed... use ask_pipeworx_grounded... deep_research'). It also provides concrete example queries and explicitly excludes use cases, making it exceptionally clear when to choose this tool over alternatives.

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

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

The description adds valuable context beyond the annotations, explaining that this is a full working router with no fallback, and that results are compared against the stable router. It also discloses the current state (no active candidate) and the fact that it may change when candidates are tested.

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

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

The description is four sentences with no filler. Each sentence conveys a distinct fact: beta status, equivalence to ask_pipeworx, current state, and usage guidance, making it concise and well-structured.

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

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

Given no output schema, the description covers the essential context: beta nature, current parity, lack of fallback, and comparison to the stable router. The 'same response shape' reference relies on sibling knowledge but is sufficient for this variant 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 all six parameters documented as aliases for question. The description only says 'same arguments' without adding new semantic detail, so it relies on the schema, which is already complete.

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 beta version of ask_pipeworx, an identical universal router with the same tools and response shape. It distinguishes itself from siblings by emphasizing its experimental nature and current parity with the stable router.

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 'Use it exactly like ask_pipeworx when you want the newest routing', providing clear usage context. It also states that no candidate is active right now, so it currently matches ask_pipeworx exactly, which tells the agent when this variant is appropriate.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description goes further by detailing the refusal mechanism (specific refusal_reason values), the guarantee to use only tool-result content, and the extra LLM call cost. This adds significant behavioral context 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 front-loaded with the core value proposition and packs a wealth of information (behavior, return format, refusal types, usage guidance, cost comparison) into just two sentences. Every clause earns its place with no redundancy.

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

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

No output schema is present, so the description correctly takes on the burden of explaining return values, including the success object and all potential refusal reasons. It also covers the underlying routing mechanism and the cost tradeoff, making the tool's behavior fully predictable for an agent.

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

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

Schema description coverage is 100%, so the schema already provides full parameter meaning (including aliases). The description adds no parameter-specific details beyond general statements about filling arguments, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode that extracts answers only from tool results. It distinguishes itself from the sibling tool ask_pipeworx by emphasizing the grounded extraction and refusal behavior, making its unique role evident.

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 (high-stakes reads, quoted/cited/acted-on answers) and when to prefer the alternative (casual lookups via ask_pipeworx). Even provides a cost tradeoff (extra LLM call), giving clear decision-making criteria.

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

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

The description goes far beyond annotations, detailing fan-out examples, response shapes, resolver contract, parent_event extractor, news field behavior, safety mechanisms, illiquidity handling, and resolution-rule risk. It adds extensive behavioral context that annotations alone do not provide, 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 very long and includes many examples, edge cases, and internal details. While informative, it lacks conciseness; the first two sentences capture the core purpose, but the remainder adds bulk. A more structured approach (e.g., grouped into sections) would improve readability, but currently it is overly verbose.

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

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

Given the tool's complexity, the high schema coverage, and lack of output schema, the description is exceptionally complete. It covers input types, internal behavior, response structure, edge cases, and safety considerations, leaving little ambiguity for an AI 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?

Input schema coverage is 100% with detailed descriptions for all three parameters. The description does not add significant new meaning; it reiterates the market parameter formats and provides examples, but the schema already fully explains the parameters. Thus baseline score of 3 is appropriate.

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

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

The description states clearly that the tool researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the action ('Research'), the resource ('Polymarket bet'), and the method ('pulling relevant Pipeworx data'). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on different aspects.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides detailed examples of when it applies and also describes blocking conditions like low-confidence matches and closed markets, effectively guiding when to trust the output.

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

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

The description adds substantial behavioral context beyond the annotations: it explains the specific data pulled for each type (revenue, net income, etc. for companies; adverse events, approvals, trials for drugs), fiscal year handling, sorting by primary metric, and inclusion of citation URIs. All annotations (readOnly, openWorld, idempotent) are consistent and the description enriches 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 dense and informative, with front-loaded trigger phrases and key behavioral details. While it is somewhat long, every sentence adds value. The structure is logical but could be slightly more streamlined by grouping related behaviors.

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 adequately explains that the tool returns paired data with citation URIs and sorted results. It covers the main scenarios and data sources. However, it omits potential error cases (e.g., invalid tickers, insufficient entities) and does not specify the exact response format, which could aid agents further.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaning by explaining the type enum values, the meaning of values elements (tickers/CIKs vs drug names), and constraints like min/max items. It clarifies that for drugs, use generic names, 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 comparisons of 2-5 companies or drugs, specifying data sources (SEC EDGAR for companies, FAERS/FDA for drugs). It explicitly distinguishes from sequential single-pack lookups and mentions sibling tools like entity_profile, making the purpose unambiguous.

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

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

The description provides explicit natural language triggers ('Compare X and Y', 'X vs Y', etc.) and advises preference over sequential lookups. It explains the type parameter and value constraints, offering clear context for when to use this tool, though it could explicitly state when not to use it (e.g., single entity queries).

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: requires account (free tier limitations, paid for thorough), never invents answers, returns gaps[] for unanswered facets, explicit citations with fetchable URIs, semantic excerpting of large records, contradictions[] for standard/thorough, and latency expectations. No contradictions with annotations.

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

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

The description is dense and front-loaded with the most critical caveat (account required, alternatives). It packs substantial information efficiently, but it is on the longer side and could be tightened; however, every sentence contributes meaningful guidance, so it earns a high score.

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

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

For a complex tool with no output schema, the description comprehensively explains what the tool returns (findings packet, verbatim evidence, confidence, citations, gaps[], contradictions[]) and how it behaves. It covers authentication, pricing tiers, latency, scope limits, and alternatives. This is a complete picture 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 description coverage is 100%, so schema fully documents question and depth. The description adds semantic value by explaining the meaning of depth levels (quick=3 facets, standard=5 with gap recovery, thorough=8 paid with iterative hop), and clarifies that broad/multi-part questions are acceptable for the question parameter. Slight overlap but adds useful context.

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

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

The description clearly states it is a grounded multi-source research tool over 1462 structured data sources, with decomposition and parallel routing across 5,562 tools. It distinguishes itself from siblings by explicitly naming ask_pipeworx as the alternative for single lookups and live news, and notes this is NOT open-web search.

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: best for broad/multi-part questions over structured data, with clear alternatives (ask_pipeworx for single lookup, live news, breaking topics). It also explains depth levels and when to choose standard vs thorough, including expected latency and paid plan requirements.

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 discloses that the tool returns 'top-N most relevant tools with... full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed'. No contradiction with annotations (readOnlyHint, idempotentHint, non-destructive).

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 paragraph of three sentences, front-loaded with the main action. Every sentence adds value: purpose, usage scenario, return details. No redundant or extraneous information.

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

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

For a tool with 6 parameters (100% coverage), no output schema, and a discovery role, the description fully covers purpose, usage, return behavior, and parameter aliases. It explains what the tool returns and how to use the results, making it self-contained.

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

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

Schema coverage is 100% and schema already describes each parameter. The description adds value by explaining that multiple aliases (q, task, search, description) are all acceptable and providing example queries. This clarifies the flexibility beyond the schema's per-field descriptions.

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

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

The description clearly states 'Find tools by describing the data or task', specifying a specific verb ('find') and resource ('tools'). It distinguishes from sibling tools by framing this as a discovery tool to be called first when browsing, contrasting with specific tools like search_within or get_dataset.

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 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. While it gives strong when-to-use guidance, it does not explicitly mention alternatives or when not to use, though the context implies it.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description goes beyond by detailing the data sources, fallback mechanisms (patents soft-fail, GDELT→GNews), result structure, and constraints. 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 relatively long but each sentence adds specific, useful information. It uses a pseudo-bulleted list of return fields. Minor redundancy (e.g., 'names not supported' said twice) could be tightened, but overall it is 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 explains what the tool returns (CIK, filings with URIs, fundamentals, patents, news, LEI) and how it works (parallel calls, fallbacks). It covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by giving concrete examples ('AAPL', '0000320193'), clarifying that names are not supported, and explaining that type is currently limited to 'company'. This extra context merits a 4.

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

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

The description clearly states the tool's purpose: producing a cross-source profile of a US public company in a single call. It provides numerous example queries and explicitly distinguishes itself from chaining individual lookups and from sibling tools like resolve_entity.

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

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

The description explicitly states when to prefer this tool ('ALWAYS PREFER over chaining... for a holistic view') and what to do if the user only has a name ('use resolve_entity first'). This provides excellent usage guidance.

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

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

Description confirms destructive behavior, matching annotations. No additional behavioral details beyond annotations, but no contradiction.

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

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

Two sentences, highly concise, front-loaded with action. No wasted words.

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

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

Simple tool with one parameter, no output schema. Description fully covers usage conditions and purpose.

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

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

Schema coverage is 100% with a clear description for the parameter. The description repeats 'by key' without adding new meaning 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?

Clearly states 'Delete a previously stored memory by key', with verb and resource identified. Differentiates from siblings like 'remember' and 'recall'.

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

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

Explicitly lists when to use: stale context, task done, clear sensitive data. Also mentions pairing with remember and recall, providing alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds behavioral details: page fetching, extraction process, and output format ('a single text blob ready to drop at site-root/llms.txt').

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 efficient sentences: purpose, steps, use cases. Front-loaded with key information, 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?

Sufficient for a simple tool with rich annotations and full schema coverage. Explains what the tool does, how it works, and what output to expect.

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%. The description adds minimal extra value for 'url' (example) and 'max_links' (context of 'link entries'). Baseline 3 is appropriate.

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

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

The description uses specific verbs ('generate', 'fetches', 'extracts', 'emits') and clearly identifies the resource (URL). It distinguishes from related siblings like 'ai_visibility_check' by focusing on producing the llms.txt file itself.

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

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

Explicitly lists three practical use cases: indexing a client's site, drafting for own project, auditing competitor's AI visibility.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description goes beyond by detailing return structure (JSON-stat with value/status arrays, dimension objects, extension.series) and warning about dataset size, adding valuable behavioral context.

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

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

The description is concise (two sentences) and front-loaded with the core purpose, with no redundant information.

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

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

Despite no output schema, the description adequately explains the return format and important details like dimension.reference_date and extension.series, making it reasonably complete for a data retrieval 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?

With 100% schema coverage, the description adds meaning by noting that lang defaults to 'PT' and that domain_id and dataset_id come from list_datasets, complementing the schema definitions.

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

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

The description clearly states the tool fetches a dataset as JSON-stat and emphasizes it returns actual data/observations, distinguishing it from sibling tools like list_datasets which only provide metadata.

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 this tool (to get actual data) and prerequisites (requires domain_id and dataset_id from list_datasets), but does not explicitly mention alternatives or when not to use it.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. Description adds value by confirming that 'metadata only' means no numeric values, and specifies fields returned and language behavior. 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?

Three sentences, no waste. Front-loaded with main purpose, followed by returned fields, then a clear note about behavior. Every sentence contributes.

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 2 parameters, no output schema, and annotations providing safety profile, the description fully covers what the tool does, what it returns, and how to use it in the broader workflow.

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. Description adds meaning by stating series_ids are 'numeric' and comma-separated, and lang defaults to PT. The schema examples reinforce this.

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 uses specific verb 'Look up metadata' and resource 'series by numeric series id'. It lists returned fields and distinguishes from sibling tools by stating it does not return numeric values, clarifying its role relative to get_dataset.

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 the tool ('identify a series and find which dataset_id holds its observations, then call get_dataset') and mentions language default. However, it does not explicitly exclude cases 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds return format details (JSON-stat collection with specific fields), which provides useful behavioral 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?

Two sentences: first gives purpose and input, second gives output structure and chaining. No wasted words, front-loaded with key information.

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

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

No output schema, but description sufficiently explains return format and chaining. For a simple listing tool, this is adequately complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds a concrete example for domain_id (3 for Balança de pagamentos) and mentions lang default, but doesn't add substantial 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 clearly states the tool lists datasets within a statistical domain, specifies the input source (domain id from list_domains), and differentiates from sibling tools like list_domains and get_dataset.

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

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

Explicitly instructs to use a domain id from list_domains and mentions chaining to get_dataset. Also notes lang defaults to PT. No explicit 'when not to use', but 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?

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds that it returns hierarchical data with parent_id, and describes returned fields. This goes beyond annotations but is not critical for safety.

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

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

Two sentences, front-loaded with purpose, no filler. Every sentence adds value: first defines the tool, second details output and workflow.

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 one optional parameter and no output schema, the description fully explains what the response contains (id, parent_id, labels, counts) and how to proceed. No missing context for a listing 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 a single 'lang' parameter. The description mentions 'lang defaults to PT; pass "EN" for English', which repeats the schema's description without adding new syntactic or semantic details. Minimal added value.

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

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

The description clearly states the tool lists statistical domains from Banco de Portugal, specifying it returns the full subject tree with fields like id, parent_id, labels, and counts. It distinguishes itself from sibling 'list_datasets' by advising to start here and then use a domain id with list_datasets.

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

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

Explicitly says 'Start here, then use a domain id with list_datasets', providing clear workflow guidance. Also explains lang parameter default (PT) and how to switch to English, leaving no ambiguity about when and how to use.

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

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

Annotations declare the tool as read-only, idempotent, and non-destructive. The description adds context about the scope (caller's subscriptions) and the default active filter, enhancing transparency without 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 two sentences, front-loading the purpose and then listing return fields and usage guidance. No extraneous content.

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

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

The description covers the tool's purpose, return structure, and use cases. Despite no output schema, the return fields are listed. The tool is simple and the description is complete enough for effective use.

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

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

Schema coverage is 100% with the parameter `include_inactive` well-described. The description does not add further parameter details, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly provides use cases: review monitoring before adding more subscriptions or find an id to cancel. This gives clear guidance on when to use the tool.

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

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

Annotations provide minimal information (readOnly=false, etc.). The description enriches this with rate limits (5 per identifier/day), the claim_token follow-up workflow, that it's free and doesn't count against tool-call quota, and that the team reads digests daily. This gives the agent important behavioral context beyond the structured 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 provides actionable information: purpose, use cases, exclusions, content guidance, claim_token workflow, and rate limits. It is front-loaded with purpose and structured logically.

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 explains return behavior (claim_token) and how to check resolution status. It also covers rate limiting, scope restrictions, and content expectations. For a feedback tool with this complexity, it 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?

Schema covers all 4 parameters with descriptions, so baseline is 3. The description adds extra guidance: message should be 1-2 sentences typical, should describe issues in terms of Pipeworx tools/packs, and the claim_token should be passed in the form pipeworx_feedback({claim_token:"pwfb_…"}). This additional context justifies a 4.

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

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

The description states exactly what the tool does: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the feedback types (bug, feature/data_gap, praise) and clearly distinguishes itself from sibling data-retrieval tools by being the only feedback mechanism for 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 provides explicit when-to-use guidance: use for wrong/stale data (bug), missing capabilities (feature/data_gap), or praise. It also gives a clear when-not-to-use rule: only for Pipeworx connection tools, not other vendors' MCP servers, with instruction to file elsewhere. This is exemplary.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds important context: data derived from CF analytics-engine, no PII, and caching details (5min-1h). No contradiction.

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

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

Three well-structured sentences, front-loaded with the core purpose, each earning its place. No redundancy or fluff.

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

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

For a read-only tool with one optional parameter and no output schema, the description fully explains what is returned, data source, privacy, and caching. Annotations cover safety. No gaps.

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

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

Schema has one parameter with full enum description and coverage 100%. Description restates the window options and adds guidance on interpretation (short vs long windows), but doesn't provide substantial 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 clearly states the tool returns trending data (top tools, packs, call volume) over a window, with specific verb 'returns' and resource 'Pipeworx trending data'. It distinguishes from siblings like ask_pipeworx or discover_tools by focusing on current agent activity.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming popular tool, seeing alignment). No explicit when-not-to-use or alternative sibling names, but the use cases provide clear context for when to invoke.

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. Description adds substantial context: details on monotonicity checks, partition_sum validation, semantic anchor (Jaccard similarity >=0.30), partition filter for placeholders, and fill check against live CLOB depth. 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 lengthy but well-structured with clear sections. The first sentence states purpose, followed by mode explanations and caveats. While verbose, the complexity of the tool justifies the length and every sentence seems necessary.

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

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

Despite lacking an output schema, the description fully explains the response structure including opportunities array, partition_check object, and fill check details. It also references a related tool for custom sizing, making the description 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?

Schema coverage is 100% with parameter descriptions. The description adds extra nuance: explains that event accepts slugs or full URLs, and topic accepts seed questions. It also clarifies behavioral differences between modes, providing meaningful value beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three distinct modes: no args (trending_scan), event mode, and topic mode, providing specific verb+resource clarity and implicit differentiation 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?

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event... or topic.' Recommends event mode for specific markets. Also advises against trading when fill check shows non-positive edge, and directs to polymarket_fill_risk for custom sizing.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) by disclosing the edge computation (net of slippage), caching behavior (1h KV-level), response structure (by_segment with diagnostics), and handling of empty segments. No contradiction with annotations.

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

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

The description is quite long but well-structured with clear sections for model families, tradeable-edge knobs, and response details. While verbose, the organization aids comprehension. Some redundancy could be trimmed, but overall it earns its length given the 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?

All 9 optional parameters are described with defaults and usage guidance. The response structure is fully detailed including diagnostic info for empty segments. No output schema is provided, but the description compensates by listing all response fields (edge_pp_net, kelly_fraction, etc.). The tool's behavior is fully specified for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the purpose and context of each parameter (e.g., min_liquidity to filter thin-book, slippage_pp with Polymarket fee context, min_partition_leg_kelly for partitions). Defaults and rationales are provided, enhancing agent 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 purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also includes the use case 'what should I bet on today' and distinguishes it from siblings by detailing unique features like model families and structural arbitrage.

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

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

The description provides extensive guidance on when to use the tool, including scenarios for each of the three opportunity segments. It does not explicitly state when not to use it vs. alternatives, but the detailed descriptions imply appropriate contexts. Implicit differentiation from sibling tools is present.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: snapshots are daily, decay computed from daily closes (not intraday), history bounded by 60-day TTL, and gaps possible. 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 well-structured: purpose first, then detailed response format (tracked[], expired[], snapshot_dates[]), followed by limits. It is dense but not verbose; could be slightly trimmed but earns a 4.

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 return values (tracked with fields, expired with lifespan, snapshot dates). It also covers limits (TTL, decay computation). This fully compensates for the missing output schema.

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

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

Schema coverage is 100% for both parameters, but the description clarifies days clamps (2-30, max 30, default 14) and window represents 'snapshot family' (24hr/1wk/1mo). This adds context beyond the schema descriptions, meriting a score above baseline 3.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It answers 'how long has this edge existed and is it shrinking?' and distinguishes itself from the sibling polymarket_edges by focusing on temporal analysis rather than raw snapshots.

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

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

The description implies usage for historical edge analysis versus instantaneous snapshots, but does not explicitly state when not to use or list alternative tools. However, the context signals include buddy tool polymarket_edges, so an agent can infer the distinction.

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 (readOnlyHint, openWorldHint, idempotentHint) indicate safety and non-destructive nature, which the description supports. Description adds details on ladder-walking, verdicts (clean/degraded/cannot_fill), and forced directional risk, going 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 well-structured with sections for single-market and basket modes, but it is somewhat verbose (~200 words). Every sentence is informative, but some output details could be streamlined without losing clarity.

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 (two modes, multiple output fields, integration with other tools), the description covers all necessary aspects: purpose, usage conditions, parameter behavior, return values, risks, and when to avoid. No output schema, but description compensates fully.

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

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

Schema coverage is 100%, and description adds significant meaning: explains mode-dependent interpretation of parameters (e.g., size_usd as max spend vs target proceeds vs settlement notional), default side logic, and output fields. Adds value 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?

Description clearly defines the tool as a realizable-vs-theoretical edge check against live order-book depth for Polymarket. It specifies two distinct modes (single-market and basket) and lists the outputs, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

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.' Provides rationale about uncapturable overround and partial-fill risk, offering clear guidance on alternatives.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds critical behavioral context: delta interpretation, compatibility warnings (shape mismatch, semantic mismatch), temporal alignment check, and skipped cross-type/cross-subtype counters. No contradiction with annotations.

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

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

Description is verbose but well-structured: begins with overview, then lists modes, response format, and safety fields. Every sentence provides value, but some redundancy could be trimmed (e.g., repeated emphasis on 'pre-mapped ≠ tradeable'). Could be about 20% shorter without losing clarity.

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 complexity (two venues, multiple modes, safety warnings, response fields) and no output schema, the description is thorough: explains each response field (raw probabilities, top_spreads_pp), compatibility_warning subcases, temporal_alignment logic, and skipped counters. No gaps identified.

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

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

Schema covers 100% of parameters with descriptions. Description adds meaning beyond schema: lists the 10 topic shortcuts, explains how explicit tickers override topic-mapped values, and clarifies that topic is optional. Nearly all necessary context is provided.

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

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

Explicitly states cross-venue spread between Kalshi and Polymarket for the same resolving question. Clearly distinguishes two modes (topic shortcuts and explicit tickers) and describes what the response contains. Differentiates from sibling tools like polymarket_arbitrage by focusing on spread calculation.

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 detailed when-to-use guidance: topic mode for common macros, explicit mode for custom pairs. Explicitly warns when compatibility_warning fires (no arb exists) and explains conditions under which spreads are meaningless (e.g., temporal misalignment, non-equivalent bet shapes).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description is fully consistent. It adds value by explaining the scoping to anonymous IP, BYO key hash, or account ID, which is not 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?

Three sentences: first states core function, second gives use cases, third adds scope and pairing. No wasted words, front-loaded with purpose.

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

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

With single optional parameter, 100% schema coverage, and no output schema, the description fully explains behavior when key is omitted (list keys) and scoping. Complete for this simple 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 description 'Memory key to retrieve (omit to list all keys)'. The tool description reinforces this and adds concrete examples (ticker, address, research notes), enhancing semantic understanding 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 retrieves a saved value or lists all keys, with specific verb ('retrieve') and resource ('value previously saved via remember'). It distinguishes from sibling tools 'remember' and 'forget' by explicitly naming them in the context.

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

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

The description provides explicit usage context: looking up stored context like ticker, address, research notes. It also indicates when to omit the key argument (list keys) and pairs with remember/forget for a complete workflow.

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 safe, read-only, idempotent behavior. Description adds value by detailing output structure (source, citation_uri, event payload) and the mark_read consumption mechanism. 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?

Four sentences, front-loaded with purpose, followed by output details, filtering, mark_read behavior, and alternative access. Every sentence provides 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?

Given the tool's moderate complexity (5 params, no nested objects, no output schema), the description covers purpose, output fields, filtering, consumption semantics, and alternative access. It feels complete and informative.

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 descriptions. Description adds examples (type 'sec_8k') and explains whether mark_read affects future calls (only newer ones). This adds meaning beyond the schema's parameter 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?

Description states 'Pull fired events from your subscription feed' with a clear verb and resource. It implicitly distinguishes from siblings by focusing on the feed, but does not explicitly differentiate from tools like list_subscriptions or get_dataset.

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?

Description provides guidance on filtering, mark_read consumption, and mentions that polling works fine. It also notes an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool vs 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 indicate readonly, idempotent, and non-destructive behavior. The description adds significant behavioral context: parallel fan-out across multiple APIs, rate-limiting fallback (GDELT→GNews), soft-failure for USPTO, and return format (changes grouped by source, citation URIs). 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 detailed but each sentence adds value. It starts with example queries to convey purpose, then explains internals, parameter usage, and alternatives. It could be slightly shorter, but it remains well-structured and informative.

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

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

Given the tool's complexity (multiple data sources, fallbacks, output format), the description is complete. It explains return structure, edge cases (soft-fail, rate limiting), and provides a comparison with 'entity_profile'. No output schema exists, but the description compensates with sufficient detail.

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

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

All three parameters are described in the schema (100% coverage). The description enhances understanding by providing examples for 'since' (ISO dates and relative shorthand), clarifying that 'type' is limited to 'company', and showing acceptable formats for 'value'.

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

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

The description clearly states the tool retrieves a change feed for a company within a time window, using verbs like 'get changes' and providing many example queries. It distinguishes itself from the sibling 'entity_profile' by specifying when to use the alternative.

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

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

Explicit guidance is given: example queries illustrate use cases, and the description directly tells when to use 'entity_profile' instead. It also explains fallback behavior for news sources and soft-failure for patents, aiding proper invocation.

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 idempotentHint=true and destructiveHint=false. Description adds valuable context: scoped by identifier, persistence differences for authenticated vs anonymous users (24-hour retention). 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?

Concise, no wasted words. Front-loaded with purpose, then usage, then technical details. Sentences earn their place, and the description is highly readable.

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

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

For a simple tool with two string params and no output schema, the description covers all necessary aspects: what, when, scope, persistence, and related tools. Fully adequate.

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 has 100% coverage with examples for key and value. Description reinforces their purpose but does not add substantial 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 saves data for reuse across conversations/sessions, with verb 'save' and resource 'key-value pair'. It distinguishes from siblings recall and forget, making purpose unambiguous.

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

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

Explicitly advises when to use ('when you discover something worth carrying forward') and pairs with recall/forget for full lifecycle. Provides clear context for appropriate invocation.

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

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

The description adds substantial behavioral detail beyond annotations: it specifies output structure (labels for source, explicit unresolved list), graceful degradation if GLEIF/OpenFIGI are unavailable, and internal cascading lookups. This gives the agent precise expectations about how the tool behaves under varying conditions, far exceeding the safety-only 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 information-dense, with no filler. It is front-loaded with user-intent examples followed by a clear purpose statement. The detailed breakdown of company and drug types is justified given the tool's complexity. It could be tighter, but every sentence adds value, so it earns a slightly above-average score.

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

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

With no output schema, the description compensates fully by explaining return structures for both entity types, including source attribution, unresolved handling, and fallback behavior. It covers edge cases (ISIN, non-US issuers) and operational characteristics (cascading lookups). The agent gets a complete picture of what to expect without needing to infer.

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 describes both parameters, the description adds crucial semantic depth: for 'type=company', it reveals that ISIN is also accepted as input and resolves to the legal entity via GLEIF, covering non-US issuers. For 'type=drug', it details the output fields (RxCUI, ingredient, brand) and citation format. This goes well beyond the schema's high-level 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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete example queries, distinguishes from siblings by focusing on ID resolution, and gives a directive to 'Use FIRST whenever you have a name but need an ID.' This clearly separates it from tools like entity_profile or compare_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 explicitly states when to use the tool ('Use FIRST whenever you have a name but need an ID') and explains the benefit ('replaces 2-3 manual lookups'). However, it does not name specific alternatives or explicitly state when NOT to use it, which would make the guidance fully explicit. Still, the primary use case is clear and gives actionable 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful context: it probes each entity with ai_visibility_check, ranks scores, and returns per-entity metrics (score, confidence, signal density). This explains the workflow 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?

Four sentences, each earning its place: purpose, mechanism, use-case example, output spec. No redundancy or fluff. Front-loaded with the core function.

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?

Without an output schema, the description adequately explains return values (ranked list with score, confidence, signal density). It covers required input (entities, 2-8) and optional parameters. Minor omission: doesn't mention error handling or limits on input size beyond '2-8', but overall 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?

Schema has 100% description coverage for 4 parameters. The description adds value by noting that the first entity is treated as the 'subject' for narrative purposes, and clarifies that context is shared across probes. This extra nuance aids correct parameter usage.

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

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

The description clearly states a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side'. It distinguishes from sibling tools like ai_visibility_check (single-entity) and compare_entities (generic) by detailing the ranking and competitive audit focus.

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and an example question ('does Claude know about us as well as our competitors?'). It does not explicitly exclude use cases or mention alternatives, but the context strongly implies when to use this composite tool vs. individual probes.

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, not destructive), the description adds behavioral details: fans out across two services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and 'sources_failed' lists timeouts. It also describes the return structure comprehensively.

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 main idea. Each sentence adds value: purpose, usage, return details, failure modes. It could be slightly more concise, but it is clear and informative without unnecessary repetition.

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

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

Given no output schema, the description fully explains the return structure (summary block with fields, per-advisory detail, links, alternative versions). It covers partial failures and timeouts. With two well-documented parameters, the description is complete for an agent to understand the tool's input, output, and behavior.

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 descriptions for both 'package' and 'version'. The description adds minimal additional semantic value beyond what the schema already provides. It mentions defaulting version to latest, but that is also in the schema. Thus, 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: a composite check for adding an npm package, using specific verb 'scan dependency'. It specifies the exact use case ('should I add this npm package') and distinguishes itself from related tools by noting 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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 tells when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives exclusion criteria: other ecosystems should use 'deps.dev:version directly'. This provides clear guidance on 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 mark it as read-only, idempotent, and non-destructive. The description adds rich behavioral details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char cap with truncation flagging, and offset-based passage verification. No contradictions with annotations.

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

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

The description is a single, well-structured paragraph of four sentences. It front-loads the purpose, immediately explains value, and packs technical details concisely 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?

Despite no output schema, the description fully explains return values (passages with offsets and similarity scores), the embedding model, windowing, and size limit. It also contextualizes usage with a sibling tool. All parameters are addressed, making it self-contained for agent invocation.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by reiterating the text cap and providing example queries, but does not significantly extend understanding 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 semantic search inside a fetched record, using examples like SEC 10-K. It distinguishes its niche from sibling tools by noting it searches within a provided text rather than general Q&A, but doesn't explicitly contrast with similar sibling tools like ask_pipeworx.

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

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

The description gives explicit guidance: use when a record is too large for the prompt, to save context. It suggests pairing with ask_pipeworx_grounded for grounding over passages, but doesn't provide explicit when-not-to-use scenarios or alternatives among 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?

The description adds significant context beyond annotations: it confirms the tool writes (create), returns an ID, lists required account type, explains delivery channel behavior (SMS cap, webhook auto-disable, HMAC signing), and notes that anonymous users cannot persist subscriptions. Annotations already indicate idempotent and non-destructive, and the description aligns with these.

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

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

The description is front-loaded with the main purpose and is well-structured, but it is lengthy. While every sentence adds value, some repetition (e.g., email validation mentioned in both delivery enum and description) could be trimmed. Still, it is efficiently organized for a complex tool.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers return value, type-specific examples, delivery details, prerequisites, and limitations (e.g., SMS phone verification). It provides enough information for an agent to use the tool correctly.

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

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

With 100% schema coverage, the description still adds substantial meaning: it gives concrete examples for each subscription type (e.g., 'items:["5.02"] = officer change') and detailed explanations for delivery options (e.g., webhook HMAC signing and auto-disable). This goes well beyond the schema descriptions.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream'. It distinguishes the tool from siblings like list_subscriptions, unsubscribe, and recent_alerts by specifying that this tool creates a subscription and returns a new ID.

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

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

The description provides when to use (proactive monitoring), prerequisites (OAuth account), and delivery channel details. It indirectly contrasts with recent_alerts for pulling alerts. However, it does not explicitly state when not to use this tool versus alternatives like list_subscriptions or unsubscribe.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety profile is clear. The description adds context: it returns example questions with exact tool+argument shapes drawn from the live catalog, which goes beyond annotations. 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 informative but somewhat lengthy. It front-loads the main purpose and then enumerates categories. While every sentence adds value, it could be more concise. Still, it is well-structured and readable.

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 (1 optional param, no output schema) and rich annotations, the description is fully complete. It explains purpose, usage, parameter behavior, and output format, leaving no ambiguity for an AI agent.

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

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

Schema coverage is 100% with a description for the 'topic' parameter. The description adds further detail: lists example topic values (finance, pharma, etc.) and clarifies that omitting topic returns a cross-category spread, providing additional meaning.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions. It distinguishes itself from siblings by specifying its use case: when the agent doesn't know what Pipeworx can do. The verb 'suggest_questions' and resource are specific.

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

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

The description explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also mentions optional topic parameter to focus. It doesn't specify exclusions, but the guidance 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?

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds value by explaining ownership enforcement, deactivation (not deletion), and that historical events remain accessible via recent_alerts. 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, no wasted words, front-loaded with the primary action. Efficient and clear.

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

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

For a simple tool with one parameter and no output schema, the description fully covers behavior, constraints, and side effects, making it complete for agent use.

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 schema for the 'id' parameter. The description adds no additional meaning beyond stating 'by id', so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id', and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by emphasizing ownership enforcement and deactivation vs 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 context on when to use (cancel own subscription) and mentions ownership enforcement and the effect on historical alerts, though it does not explicitly list when not to use or compare to alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds crucial operational behavior: it distinguishes 'could_not_verify' from 'unsupported', warns that 'could_not_verify' must not be shown as evidence, and details the two-path routing logic. This is rich, non-obvious context that helps callers interpret results correctly.

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

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

The description is well-structured and every sentence earns its place: trigger examples, usage rule, routing, return payload, and a critical caveat. It is compact for the complexity it covers and front-loads the core purpose.

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

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

With no output schema, the description compensates by explaining the verdict list, actual value with citation, reasoning, and the meanings of error verdicts. It also covers both claim categories and the routing logic, making it complete for an agent to invoke and interpret the tool correctly.

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

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

The input schema already fully describes both parameters, including the 'claim' example and tolerance_pct semantics. The description does not add parameter-level detail beyond mentioning 'exact percent-delta math' for the financial path, so it meets only the baseline for full 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 names a specific verb ('validate') and resource ('natural-language claim verification'), along with trigger phrases like 'fact check' and 'verify the claim that'. It clearly defines the tool's scope and explains the two processing paths (structured SEC EDGAR for company-financial claims, grounded pipeline for all others), distinguishing it 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?

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing rules for different claim types. However, it does not explicitly mention when NOT to use the tool or name alternative tools, 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.