Kroger

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

Annotations already indicate read-only, non-destructive, and open-world behavior. The description adds value by noting the default free model, the cost implication for Anthropic (BYO key, pay directly), and the return format (per-model scores + 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?

The description is a single, well-structured paragraph that front-loads the action and default model, then covers optionality and return format, ending with use cases. Every sentence contributes value.

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

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

Given the tool has 4 parameters, no output schema, but strong annotations, the description covers purpose, behavior, parameters, use cases, and return format. It could mention failure modes or rate limits but is largely complete.

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

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

Schema coverage is 100%, and the description enriches all parameters: entity is described with examples, models lists supported values, _apiKey is conditioned on model choice, and context disambiguates. This adds meaning beyond the schema.

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

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

The description uses specific verbs ('probe', 'score') and identifies the resource (LLMs, business/brand visibility). It clearly distinguishes the tool's purpose from siblings by focusing on multi-model visibility scoring.

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 cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'). It does not provide explicit when-not-to-use or contrast with siblings like 'scan_competitor_ai_presence', but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds important behavioral context beyond those annotations: it routes to one of 5,798 tools, fills arguments automatically, and returns a structured answer with citation URIs. Rate limits and failure behavior are not discussed, but for a safe read-only tool this is not a major gap.

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 over-long and repetitive: the same set of example queries and the 'even if web search could also answer it' phrase appear twice. The opening is front-loaded and useful, but the duplicated content and awkward trailing sentences are clear editing failures that waste token budget.

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 high-complexity routing tool with no output schema, the description covers scope, invocation triggers, examples, output form, and sibling alternatives. The agent has enough context to select and call the tool correctly; a tighter presentation would make it fully polished.

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 six parameters are aliases for the single 'question' parameter, and the schema already describes it with 100% coverage. The description adds value by specifying the breadth of accepted queries, giving trigger phrases, and providing representative examples, so the agent knows exactly what kind of natural-language input is expected. No parameter ambiguity remains.

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 that ask_pipeworx routes natural-language factual questions to the appropriate structured-data tool and returns cited answers with pipeworx:// URIs. It enumerates the covered domains and explicitly frames itself as preferable to web search, making its purpose and resource scope unambiguous.

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

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

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions'), concrete example queries, and explicit alternatives for other cases: ask_pipeworx_grounded for highest accuracy, deep_research for broad/multi-part questions, and news packs for breaking-news sentiment. This fully disambiguates when to invoke this tool versus 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?

Goes well beyond the annotations by revealing live experimental routing, the current inactive-candidate state with a retirement date, that it currently matches ask_pipeworx exactly, and that it is a full working router with no fallback. This is exactly the kind of behavioral context an agent needs for a beta tool.

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?

Front-loaded with the core definition, then current status, usage instruction, and no-fallback guarantee. Every sentence contributes useful information, though the specific date and repeated 'exactly like ask_pipeworx' phrasing make it slightly longer than strictly 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?

For a universal router with no output schema, the description covers what the tool is, what is different from stable, when to use it, the current operational state, and the fact that it is fully functional. An agent has enough to invoke it correctly and distinguish it from ask_pipeworx.

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

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

The input schema covers 100% of parameters and already documents all six fields as aliases for question, so the description adds little parameter-level meaning. It usefully notes that arguments are identical to ask_pipeworx, but the schema does the semantic heavy lifting.

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

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

States directly that it is a beta version of ask_pipeworx: an identical universal router with the same 5,798 tools, arguments, and response shape, plus candidate routing improvements. This clearly sets it apart from the stable ask_pipeworx and signals its experimental scope.

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

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

Explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and that results are compared against the stable router. It could more strongly state when not to use it, such as preferring stable or grounded variants for normal use, but the intended experimental scenario 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 state read-only/idempotent, but the description adds substantial behavioral detail: it never invents facts, returns verbatim evidence, may return an explicit refusal, and enumerates all refusal reasons. It also clarifies data sourcing behavior and the additional latency/cost implication.

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

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

Every sentence earns its place: purpose, routing mechanism, return contract, refusal contract, usage guidance, and cost tradeoff are all included without redundancy. The most important differentiator is front-loaded.

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

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

Given there is no output schema, the description compensates by fully specifying the success response shape and all refusal paths. It also positions the tool against siblings and provides clear selection criteria, making it complete for safe 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?

Input schema coverage is 100% and the sole required parameter is well-documented with aliases. The description does not add parameter-level detail, which is acceptable because the schema fully describes the question input.

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 identifies a specific, differentiated mode: a hallucination-resistant, grounded-answer MCP for high-stakes reads. It names the exact mechanism (extraction only from tool results) and clearly separates itself from ask_pipeworx and ask_pipeworx_beta.

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 ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when NOT to use it ('prefer ask_pipeworx for casual lookups'). Also discloses the cost tradeoff of one extra LLM call, which directly informs selection.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description goes well beyond these by detailing behavioral traits: it resolves markets, classifies bets, fans out to data sources, handles low-confidence matches with short-circuit status, skips closed/inactive markets, and reports illiquid spreads. 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 long but every section provides essential information: main purpose, classifiers, fan-out examples, response shapes, resolver contract, parent event extractor, news fields, safety notes, and resolution rules. It is well-structured with clear headings and front-loaded with the core action.

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

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

Despite having no output schema, the description thoroughly details the response structure, including keys like result.market, result.analysis, result.evidence, and their subfields. It covers edge cases (low confidence, closed markets, wide spreads, cancellation rules) and system behaviors (fallback mechanisms in news, blocking routes). The level of detail is complete for an agent to understand and trust the tool's outputs.

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

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

Schema coverage is 100%, and the description adds significant meaning. For the 'market' parameter, it explains accepted formats (slug, URL, question text). For 'depth', it distinguishes between 'quick' and 'thorough' with rationale. For 'include_raw', it recommends false to keep responses small and notes when true is needed. The examples in the input schema also clarify 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 the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research), resource (Polymarket bet), and scope (pulling Pipeworx data), distinguishing it from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides extensive context on what the tool returns and how to interpret results, covering scenarios like low-confidence matches, closed markets, and wide spreads, effectively guiding when and how to invoke it.

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

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

Discloses data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinical trials for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. Annotations already indicate safe, read-only behavior, and description adds rich context without contradiction.

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

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

Description is somewhat lengthy but front-loaded with trigger phrases and each sentence provides distinct value. Could be slightly more concise, but remains efficiently 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?

Covers entity types, data sources, sorting, return format, and replaces many sequential lookups. Without output schema, description adequately explains what the tool returns (paired data + URIs).

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 already describes both parameters with 100% coverage. Description adds practical examples (tickers/CIKs for company, drug names) and explains the meaning of values in context of the comparison, enriching 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 states explicit purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. Provides trigger phrases ('compare X and Y', 'X vs Y', 'which is bigger') and distinguishes from sequential lookups.

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

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

Explicitly advises to always prefer this tool over sequential single-pack lookups. Gives clear context for when to use company vs drug type, and explains the data pulled for each.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral detail beyond them: parallel routing across 5,798 tools, explicit gaps[] that are never invented, semantic excerpting rather than head-truncation, depth-dependent hop behavior, a fetchability guarantee for citation URIs, and expected latency ranges (15-60s, up to ~90s). No contradiction with annotations.

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

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

The description is long but every clause carries functional information — account requirements, sibling routing, data-source scope, return packet structure, citation semantics, depth differences, and latency. It is front-loaded with the critical account gate. Minor redundancy with the schema's depth description prevents a 5.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and the hop field. It also covers prerequisites, alternatives, timing, and depth-specific behavior, so an agent has enough to invoke and interpret results correctly.

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

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

The input schema already covers both parameters well (100% coverage), so the baseline is 3. The description adds meaningful context: thorough depth requires a paid plan, quick/standard/thorough map to different hop behaviors, and the 'hop' field appears on every finding. This extra context pushes it above baseline without duplicating the schema.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call.' It also clarifies what it is not ('NOT open-web search') and describes the decomposition/routing mechanism, making the purpose unmistakable and well-differentiated from siblings.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx instead', and 'Best for broad/multi-part questions over structured data.' It also names the required account tier and billing condition for 'thorough' depth.

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?

Describes output details (top-N tools with names, descriptions, schemas) and that results are 'ready to call directly'. Annotations confirm read-only, idempotent, non-destructive. 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?

Single dense paragraph, front-loaded with purpose. Lists many domains but necessary for clarity. Could be slightly more concise, but not excessively 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?

No output schema, but description explains output suffices for discovery tool. Covers purpose, usage, behavior, and parameters comprehensively.

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

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

Schema coverage 100%, but description adds value by explaining aliases (q, task, search, description) and providing examples. Adds 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?

Description clearly states the verb 'find' and resource 'tools', and distinguishes from siblings by being a discovery tool. It provides extensive domain examples, 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?

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use guidance.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing soft-fail behavior for patents, expected empty sections like fda_products for small-molecule companies, the sources_used/sources_failed contract, and the resolved:false path for private companies. This gives an agent realistic expectations about data availability and failure modes without contradicting any annotations.

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

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

The description is dense and front-loaded with example queries and the core 'prefer' directive. It is longer than necessary because it repeats some parameter semantics already present in the schema and includes an extensive but useful list of sources; overall it remains well-organized and mostly efficient.

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 does a thorough job of explaining return sections such as cik, company_name, recent_filings URI patterns, and fundamentals. It also defines the sources_used/sources_failed contract and input resolution edge cases, which is essential for correctly interpreting results from such a multi-source 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?

Although the schema already documents both parameters well, the description adds crucial semantic detail: name resolution via SEC EDGAR, zero-padded CIK format, accepted ticker/CIK/name forms, and the private-company resolved:false outcome. It also clarifies that 'type' values are interchangeable, reinforcing correct invocation.

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 producing a full cross-source profile of a US public company in one parallel call, supported by example user phrasings. It explicitly distinguishes itself from single-pack SEC/XBRL/news lookups, so an agent can tell what kind of holistic request this tool is meant for.

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

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

It gives an explicit decision rule: always prefer this over chaining single-pack lookups when the user asks for a holistic view. This is a strong when-to-use signal and names the main alternative behavior, making selection straightforward.

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

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

Annotations already declare destructiveHint=true for deletion. Description adds no behavioral context beyond what annotations provide (e.g., no mention of irreversibility or authorization needs). Consistent with annotations, no contradiction.

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

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

Two concise sentences with essential information front-loaded. 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?

Given simplicity (one required param, no output schema), the description fully covers purpose, usage, and behavior. 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?

Parameter 'key' is fully described in schema (100% coverage). Description repeats 'Memory key to delete' without adding extra meaning like format or constraints. Baseline 3 for high schema coverage.

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

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

Clearly states 'Delete a previously stored memory by key.' Verb and resource are specific. Distinguishes from sibling tools by mentioning '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: 'when context is stale, the task is done, or you want to clear sensitive data'. Also provides pairing guidance with 'remember' and 'recall'.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, indicating a safe read operation. The description adds process details (fetching, extracting, emitting markdown) that enhance transparency without contradicting annotations.

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

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

The description is concise with 4 sentences, front-loading the purpose. It avoids verbosity, though a slight reduction in the use cases list could improve conciseness.

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

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

Given the simple 2-parameter tool with no output schema, the description sufficiently explains the input, process, and output format ('a single text blob ready to drop at site-root/llms.txt'). It covers the essential context 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 does not add significant meaning beyond the schema; it mentions 'fetches the page' but lacks details on URL format or max_links behavior.

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

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

The description clearly states the tool generates a production-ready llms.txt file for AI crawlers, specifying the verb and resource. While it provides use cases, it does not explicitly differentiate from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description includes 'Useful for:' with three specific scenarios, implying when to use the tool. However, it does not mention when not to use it or provide alternatives, leaving the agent without explicit guidance for disambiguation.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that price/stock are store-specific and that location_id overrides zip_code, which is 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 efficient sentences, includes an example, no wasted words. Front-loaded with 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?

No output schema, but description lists expected return fields (price, promo, stock, etc.) and explains store-specific logic. Complete for a product detail lookup 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%, but description adds an operational example and clarifies that location_id overrides zip_code and product_id comes from kroger_product_search, significantly aiding parameter understanding.

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

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

Description clearly states verb 'Get' and resource 'full detail for one grocery product', listing specific fields (price, promo price, stock, etc.). It implicitly distinguishes from kroger_product_search (requires product_id) and kroger_store_locator.

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 explains when to use zip_code or location_id for store-specific data, includes an example. Missing explicit when-not-to-use or alternatives, but sibling tools provide 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 indicate read-only, idempotent, non-destructive. Description adds that it returns real-time shelf prices, promos, stock, and aisle; also clarifies that without location no prices are returned. This adds 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?

Three compact sentences plus an example; front-loaded with core function. Every sentence provides essential information with no redundancy.

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

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

Given no output schema, the description adequately explains what is returned (prices, stock, aisle, catalog). Covers location dependency. Could hint at pagination or filtering, but the limit parameter is already in 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 has 100% description coverage, so parameters are well-documented. Description reinforces the role of zip_code/location_id with an example but does not add significant new semantics 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?

Clearly states it searches grocery products at Kroger-family supermarkets, listing returned data (prices, stock, aisle). Includes example query and specifies what questions it answers (cost, stock, price comparison). Differentiates from siblings by focusing on product search vs. store locator or product details.

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

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

Provides clear context: use for searching products and getting prices; explains that without location only national catalog is returned. Gives explicit example. Does not directly name alternatives but implies when to use location parameters.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by specifying the return fields (names, addresses, phone, hours, location_id) and explaining that location_id is needed for price lookups, as well as noting the optional API key parameter. This covers 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?

The description is two sentences with an example, front-loading the purpose and key details. Every sentence earns its place, with no 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?

Given no output schema, the description covers the primary return fields (store names, addresses, phone, hours, location_id). It explains the tool's core functionality well. However, it does not mention error handling, pagination, or default behavior when parameters are omitted, which would be minor enhancements.

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

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

Schema description coverage is 100% with all 5 parameters described. The description adds an example call but does not provide additional semantic meaning beyond what the schema already gives. The mention that 'location_id' is needed for price lookups is helpful but is not parameter-specific.

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

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

The description uses a specific verb ('Find') and clearly identifies the resource ('Kroger-family grocery stores and supermarkets') with a comprehensive list of banners. It distinguishes from sibling tools like 'kroger_product_details' and 'kroger_product_search' by focusing on store locator functionality.

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

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

The description states the tool is for finding stores near a US ZIP code. It provides an example call. However, it does not explicitly state when to use this tool versus alternatives or mention when not to use it. The context is clear enough given sibling names.

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

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

Annotations already declare read-only and idempotent. The description adds useful context about default active-only behavior and the include_inactive parameter, but no further behavioral details are needed.

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 concise sentences: one for action and return fields, one for usage guidance. No unnecessary words.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers the return structure and usage scenario, making it complete 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% with a clear description for the only parameter (include_inactive). The description reinforces the default behavior but adds no new parameter information, meeting the baseline.

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

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

The description clearly states the action (list active subscriptions) and specifies the returned fields (id, type, params, timestamps, fire_count). It is distinct 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?

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for selection 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?

Annotations only set all four hints to false, providing no positive safety signals, so the description carries full burden. It discloses the claim_token flow for anonymous filing, rate limiting (5/day), quota exemption (free), and the guidance to describe issues in terms of Pipeworx tools rather than pasting user prompts—valuable behavioral context not available in annotations.

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

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

Though long, every sentence contributes: purpose, use cases, server exclusion, guidance on describing feedback, claim_token handling, and rate limits. It is front-loaded with the primary purpose and structured as a dense but non-redundant paragraph. No filler.

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

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

With no output schema, the description explains the return value (claim_token) and how to use it for follow-up. It covers prerequisites (account vs. no account), constraints (rate limit, free), and the submission context (describe in terms of Pipeworx tools). Given the tool's moderate complexity, this is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining how to use claim_token to read a previous report, and clarifies that 'filing without an account returns a claim_token'—connecting the parameter to the return flow. This earns one point above baseline.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools like ask_pipeworx by framing it as feedback, not a query, and enumerates the exact feedback categories (bug, feature, data_gap, praise).

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

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

Provides explicit when-to-use conditions ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well'), a when-not-to-use exclusion ('if the tool came from a different MCP server... file it with that server instead'), and a disambiguation rule ('Pipeworx tool names are the ones this connection lists').

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

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

Annotations cover read-only, idempotent, etc. Description adds caching behavior (5min-1h), data source (CF analytics-engine), and no-PII guarantee, exceeding annotation value.

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

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

Three sentences, front-loaded with core return value, then use cases, then data notes. 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?

Adequate for a simple tool with no output schema: covers purpose, usage, and behavior. Lacks explicit return format, but the description hints at structure. Could mention response shape.

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

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

Schema has 100% coverage with description, but tool description further explains window semantics (shorter for hot, longer for steady-state), adding meaning beyond enum values.

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

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

Description clearly states it returns top tools, packs, and call volume over a window. Distinguishes from siblings by specifying it shows what other AI agents are calling, differentiating from search/discovery 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?

Three explicit use cases provided, and window trade-off explained. No explicit when-not-to-use or alternative siblings, 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?

The description adds substantial behavioral context beyond annotations, including the default trending scan, semantic anchor, partition filter, fill check, and response structure. Annotations already declare readOnlyHint and idempotentHint, which align with the description.

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 well-structured, with key information front-loaded. Each sentence adds value, though some technical details could be organized into bullet points for 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 of the tool (two modes, multiple checks), the description covers the response format, filters, and trade signals. It is complete enough for an agent to use, though no output schema is provided.

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

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

Schema coverage is 100%, and the description adds meaning by explaining the purpose of each parameter, providing examples, and detailing the behavior of topic mode. This goes beyond the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event and topic modes, making the purpose specific and differentiating it from sibling tools like 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?

The description provides explicit guidance on when to use each mode: event for a specific market and topic for cross-event scanning. It includes examples and explains cross-event catching, but lacks explicit when-not-to-use advice.

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 destructiveHint=false. The description adds substantial behavioral context, including details on three model families, caching at 1h in KV store, diagnostics for empty segments, and handling of Fed bets. This goes well beyond what annotations provide, offering deep transparency into the tool's inner workings.

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

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

The description is verbose and contains extensive technical detail, which may overwhelm agents. However, it is well-structured with segments and front-loads the primary purpose. Some redundancy exists, and brevity could be improved without losing essential information.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the response structure (by_segment, diagnostics), caching behavior, edge cases for Fed bets, and filter knobs. All necessary context for correct invocation is present.

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 all 9 parameters. The description adds extra meaning for several parameters, such as slippage_pp explaining the basis for default 0.3 and min_partition_leg_kelly clarifying its relationship to min_kelly. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today' and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by explicitly describing its unique approach and output segments.

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 explains the tool's purpose and segments, and mentions tradeable-edge knobs, but does not provide explicit guidance on when to use this tool versus alternatives such as polymarket_arbitrage, polymarket_edge_tracker, or other siblings. It implies usage for discovering opportunities but lacks direct comparisons or exclusions.

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

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

Annotations already provide read-only, open-world, and idempotent hints. The description adds substantial behavioral details: daily snapshot basis, possible gaps, decay computation from daily closes, and the output structure (tracked, expired, snapshot_dates). 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 detailed yet efficient, using structured notation for the response. It is front-loaded with the key question. A few sentences could be tightened, but overall it earns its length.

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

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

Given no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and covers limitations. It provides enough context for an agent to understand what the tool returns and how to interpret results.

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

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

Both parameters are fully described in the schema (100% coverage). The description repeats default values and bounds, adding minor clarification (e.g., 'clamp 2-30'), but does not significantly extend 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 provides 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes from sibling tools like polymarket_edges by focusing on historical decay and persistence.

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 context on when to use the tool (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades') and outlines limitations (60-day TTL, gaps). It does not explicitly list when not to use, but the context is clear enough.

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, and non-destructive behavior. The description adds significant detail: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and warns that partial basket fills convert an arb into an unhedged directional position. No contradiction with annotations.

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

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

The description is long but well-structured, using capitals for mode names and clear examples. Every sentence contributes useful information. Could be slightly more concise, but still 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?

Despite no output schema, the description lists all return fields for both modes in detail. It also explains the risk of partial fills and forced directional risk. For a complex tool with two modes and risky outcomes, the description is complete enough for an agent to understand what 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%, so the schema already documents all parameters. However, the description adds value by explaining parameter semantics in context: e.g., size_usd interpretation differs for single-market vs basket, side has auto-detection for basket mode based on partition sum. This enriches 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 a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by advising to use this tool before acting on those signals.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also states the requirement for one of 'market' or 'event' parameters and explains the consequences of not using it (theoretical overround not capturable, partial fills create directional risk).

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?

Although annotations already declare readOnly, idempotent, and non-destructive behavior, the description goes far beyond that by disclosing pairing verification caveats, compatibility codes, skipped unclassified legs, fee treatment (gross vs net), and the semantics of temporal_alignment nulls. It even warns that both compatibility_warning and compatibility_codes can be non-empty even when matched_pairs > 0. This is substantial operational transparency that the annotations could not convey.

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

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

The description is long, but the density of caveats justifies most of the length; it uses inline headings like TWO MODES, RESPONSE, and SAFETY FIELDS to organize what could otherwise be a wall of text. It front-loads the core purpose before diving into codes and skipped counters, and nearly every sentence adds either a matching rule or a validation caveat. It could be tightened with bullet lists, but the structure is serviceable for a tool with many safety fields.

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 present, the description carries the full burden of explaining return values, and it covers each venue's prices, spread[].top_spreads_pp, compatibility fields, per-entry flags, skipped unclassified legs, temporal alignment object, fee note, and skipped counters. It even explains the meaning of null in temporal_alignment and warns that pre-mapped does not equal tradeable. There is no obvious required detail an agent would need to call or interpret this tool that is missing.

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

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

Schema coverage is 100%, so the schema already documents the three parameters, but the description adds meaningful mode semantics: topic selects one of ten pre-mapped shortcuts that auto-fetch the matching event, while explicit ticker plus slug create custom pairings and override the mapped sides. It also clarifies that both modes run the identical token-overlap matcher and that the same disclosures apply. It does not explicitly state what happens if neither topic nor explicit parameters are supplied, though zero required parameters make that a minor gap.

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

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

The description opens by defining the tool as a cross-venue spread between Kalshi and Polymarket for the same resolving question, which names the resource and the computation precisely. It distinguishes this from single-venue or arbitrage siblings by emphasizing two venues, equivalent bet shapes, and the same resolving question. The TWO MODES section further specifies exactly what the tool fetches: pre-mapped topic shortcuts or explicit ticker/slug pairings.

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

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

It gives clear when-to-use guidance for the two input modes: use topic for pre-mapped macro shortcuts and use kalshi_event_ticker plus polymarket_event_slug for custom pairings. It also tells users when not to treat results as tradeable, warning that pre-mapped topics can return compatibility_warning and that spreads are gross, not net edge. It does not, however, explicitly name sibling alternatives such as polymarket_arbitrage or state the conditions that would select one of those instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. Description adds context on scoping (by identifier) and the behavior of listing keys when argument omitted. Does not contradict 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, front-loaded with core function. Every sentence adds value: main operation, when to use, scoping, and relationship to siblings. 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?

For a simple retrieval tool with one optional parameter and strong annotations, the description covers main behavior, scoping, and sibling relationships. Could explicitly mention the return format (value or list of keys) but it is reasonably implied.

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 'key' parameter. The description adds 'omit the key argument to list all keys' clarifying the optional behavior and the listing functionality, which is not explicit in the schema.

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

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

Description states 'Retrieve a value previously saved via remember, or list all saved keys' with specific verb+resource. Distinguishes from siblings remember and forget, and provides example use cases like user's target ticker or address. Clear scope and operation.

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

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

Explicitly says when to use (look up context stored earlier), implies when not to use (save with remember, delete with forget), and mentions scoping by identifier. Provides explicit pairing with remember and forget, and gives examples of appropriate contexts.

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

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

The description states that setting mark_read:true flags events as read, implying a state mutation. This contradicts the readOnlyHint annotation, which indicates no side effects. Therefore, the description contradicts 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 four sentences and front-loads the core purpose. It contains minimal redundancy, though the last sentence about an alternative endpoint could be considered optional but still useful.

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 covers all important aspects: return fields (source, citation_uri, payload), filter parameters, the mark_read feature, and polling safety. It is complete for a read-oriented tool with no required parameters.

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 value by giving example values for type ('sec_8k') and explaining the effect of mark_read, which is not fully captured in 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 begins with 'Pull fired events from your subscription feed,' specifying a clear verb and resource. It distinguishes from sibling tools like list_subscriptions by focusing on events from the feed rather than managing subscriptions.

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

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

The description explains filtering and the mark_read option, and notes that polling is acceptable. It provides an alternative endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools like subscribe or list_subscriptions.

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

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

Beyond annotations (readOnly, idempotent, etc.), description discloses fallback behavior (GDELT→GNews on rate limits), soft-fail for USPTO, and output structure (changes grouped by source with citation URIs). 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 comprehensive but slightly verbose. However, every sentence provides useful information (query examples, source details, parameter hints). Front-loaded with examples; 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?

Despite no output schema, description explains return structure ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). Covers fallback behaviors and limitations (USPTO soft-fail). Complete for a complex multi-source 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 has 100% coverage with descriptions for all parameters. Description adds further clarity: 'since' accepts relative shorthand ('7d', '30d', '3m', '1y'), 'value' accepts ticker or CIK. 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 states it returns a change feed for companies from multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes from sibling 'entity_profile' by specifying when to use each.

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 this tool vs 'entity_profile' (static profile vs change feed). Provides example queries ('What's new with X', 'latest on Y') and instructions for the 'since' parameter.

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 adds beyond annotations: key-value pair scoped by identifier, persistence differences per auth status. Annotations already indicate idempotentHint=true and non-destructive, which is consistent. The added behavioral details are valuable.

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

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

The description is concise and front-loaded: purpose first, then usage guidelines, then persistence details. Every sentence adds value 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 covers storage behavior, scoping, persistence, and pairing with sibling tools. It provides all necessary context for an agent to use this tool effectively.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds real-world naming conventions (e.g., 'subject_property') and clarifies value type as 'any text', enhancing 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 'Save data the agent will need to reuse later' with a specific verb and resource. It differentiates from siblings like recall and forget, and provides concrete examples (resolved ticker, target address, etc.).

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Names sibling tools for complementary actions (recall, forget), providing clear context for 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds substantial behavioral context beyond that: graceful degradation when LEI/FIGI sources are unavailable, explicit treatment of unresolved identifiers under `unresolved`, the cascade through multiple endpoints, and the behavior for ambiguous matches (asserts nothing, returns figi_candidates). No contradiction with annotations.

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

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

The description is long but densely packed and efficiently front-loaded with example queries and the primary directive. Each paragraph builds on the previous one and adds non-redundant information. It is not concise in length, but every sentence earns its place; a 4 reflects that it is appropriately sized for the complexity, even though it could be tightened slightly.

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

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

This is a complex tool with multi-source resolution, fallback behavior, and special cases for bonds and drugs. The description explains all of this, including the return format (e.g., figi_candidates, unresolved, labeled identifiers) even though there is no output schema. An agent has everything needed to call it correctly, including edge cases and input constraints.

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 both parameters. However, the description adds critical semantics that go far beyond the schema: it explains how to format the `value` for bonds (issuer only, not the full phrase), gives concrete examples (AAPL, CIK, ISIN, drug names), and clarifies the meaning of different inputs (e.g., ISIN resolves to legal entity). This is exactly the kind of compensation expected when the schema is bare.

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

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

The description states a precise verb (resolve) and resource (user-spoken NAME to canonical/official identifiers), with concrete example queries and a clear positioning as the first step when a name needs an ID. It is unambiguously distinct from the resolver's siblings (entity_profile, compare_entities) even though it doesn't name them, because it explicitly scopes to identifier resolution rather than profile or comparison.

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?

Gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and detailed input formatting constraints (e.g., pass only the entity name, not the full phrase). It does not explicitly name alternative tools for exclusion, but the strong positional statement plus the type-specific instructions cover the practical decision points.

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 nature. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This enhances transparency 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 two sentences: first gives purpose and process, second gives usage context and example. It is front-loaded, efficient, and contains 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?

The description covers tool purpose, process (probes, ranks, surfaces), and output (ranked list with score, confidence, signal density). No output schema exists, so the description adequately informs the agent of return value structure. It is complete for the tool's moderate complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity is treated as the 'subject' for narrative, and it contextualizes the 'entities' parameter as brand/competitor names. This goes beyond the schema's formal 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 compares AI visibility across multiple entities side-by-side, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI visibility and competitive audits.

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

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

The description provides clear usage context with an example question and states it is useful for competitive AI-marketing audits. While it does not explicitly list when not to use it, the context and sibling tool names imply alternatives for single entity checks or generic comparisons.

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?

Adds behavioral details beyond annotations: graceful degradation on bundlephobia timeouts (5-30s), partial failure handling, and return structure. 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 informative but slightly dense; front-loads key purpose and use case. Could be trimmed slightly but still effective.

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 details return fields, links, and alternative versions. Covers edge cases (partial failures, ecosystem limitation). Thorough for a composite 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%, but description adds value by mentioning scoped packages are accepted and default version behavior. Justifies 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 it is a composite check for npm packages, combining deps.dev and bundlephobia data. It distinguishes from siblings by specifying the npm ecosystem scope and unique functionality.

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 (e.g., 'is X safe/popular/small') and when not (non-npm packages fall under deps.dev:version directly). Provides clear usage 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 and idempotentHint. The description adds valuable implementation details (BGE embeddings, cosine, 500-char windows, 200K cap with truncation flag) and mentions each passage carries an offset, 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 compact (~80 words), front-loaded with the core action, uses capitalization for emphasis, and every sentence serves a purpose 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, but the description specifies the output format (top-N passages with character offsets and similarity scores) and technical details (embedding, windowing, truncation). Slightly more could be said about the return structure, but it is sufficient.

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

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

Schema has 100% parameter descriptions. The description adds contextual examples (e.g., supply-chain risk, fiscal year revenue) and clarifies usage, but does not provide significant new information 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 it performs semantic search inside a fetched record, distinguishing it from sibling tools by specifying it's for large texts too big for the prompt. It uses specific verb+resource and provides a clear example of use case (SEC 10-K).

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 advises use when the record is too large for the prompt and pairs it with ask_pipeworx_grounded for grounding. It lacks explicit 'when not to use' guidance but the context is sufficient.

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

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

Adds details beyond annotations: SMS cap (10/day), webhook signing, verification requirements. 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?

Front-loaded purpose, structured lists. Slightly long but each sentence adds value.

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

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

Explains return value, required account, types, delivery options. No output schema so return info is covered. Missing two types in description incomplete but overall solid.

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 100%, description enriches with examples and constraints. However, description mentions only 3 of 5 enum types, missing patent_grant and clinical_trial.

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 action ('Create') and resource ('proactive monitoring subscription'), returns ID. Distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Specifies required OAuth account and supported types/delivery channels. Lacks explicit comparison with other subscription tools but provides enough context for 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that results are drawn from a live catalog of thousands of tools and returns category-bucketed examples, which provides some context beyond annotations but does not significantly extend the behavioral profile.

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 comprehensive but front-loaded with example queries. Every sentence adds value, though it could be slightly more concise. The structure is logical and easy to scan.

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

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

For a simple discovery tool with 1 optional parameter and no output schema, the description is thorough. It explains the purpose, usage, parameter behavior, and what kind of output to expect, making it complete for an agent to decide when to invoke it.

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

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

With 100% schema coverage and 1 parameter, the description adds value by explaining the topic parameter's purpose, listing example values (finance, pharma, etc.), and clarifying how omitting it works. This goes beyond the schema's simple description.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions. It uses specific verbs (returns, call) and distinguishes itself from siblings by being the tool to use first when unsure what to ask.

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 to use this tool first when you don't know what Pipeworx can do, and provides guidance on using with or without the topic parameter. It does not explicitly mention when not to use it or list alternatives, but the context is clear.

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

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

Annotations provide idempotentHint and destructiveHint, and the description adds key details: ownership enforced, row deactivated not deleted, keeping historical events. This goes beyond annotations without contradiction.

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

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

Two efficient sentences front-load the primary action and add relevant context. No wasted words; every sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description covers ownership, operational behavior, and result. It is complete enough for an agent to use correctly.

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

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

Schema covers the single parameter 'id' with full description. The description does not add additional parameter information, but schema coverage is 100%, 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 'Cancel a subscription by id,' providing a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description explains ownership enforcement and the deactivation behavior, giving clear context on when to use. However, it does not explicitly mention when not to use or alternatives, though the context is sufficient.

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

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

Annotations already indicate readOnly/openWorld/idempotent safety, but the description adds crucial behavioral context: the dual routing paths (SEC XBRL vs grounded pipeline), the full set of verdicts, the presence of verification_error for could_not_verify, and the fact that unsupported is distinct from refuted. This goes well beyond annotations and gives a complete picture of how the tool behaves.

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 fairly long but well-organized: begins with trigger phrases, then states when to use, describes the two paths, lists return values, and provides an IMPORTANT caveat. Each sentence carries meaningful information; it is dense but not wasteful, though slightly verbose for a tool with only two parameters.

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 (dual routing, multiple verdict types, error semantics), the description is remarkably complete. It explains the return structure (verdict, value, citation, reasoning), distinguishes between could_not_verify and unsupported, and notes what the tool replaces. No critical behavioral aspects are left to inference.

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 claim and tolerance_pct. The description adds value by explaining how tolerance_pct interacts with claim wording, its default cap of 5, and a specific use case (set 1–2 for hallucination detection). It also clarifies that claim is a natural-language factual claim, reinforcing the schema examples without redundancy.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources, with explicit trigger phrases and examples. It distinguishes between company-financial claims routed to SEC EDGAR and other claims falling through to a grounded pipeline, setting it apart from sibling tools like ask_pipeworx_grounded.

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

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

The description gives explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies when NOT to use it by explaining that could_not_verify means the check didn't happen, and unsupported means no source exists, preventing misinterpretation. It even says the tool replaces 4–6 sequential calls, implying it should be preferred over a multi-step pipeline.

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