Gov Auctions

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

Annotations declare readOnlyHint=true and idempotentHint=true, which the description does not contradict. The description adds behavioral details: that the default model is free and that Anthropic requires a BYO key, plus the return structure.

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 compact paragraph, starting with the core action and progressively adding details. Every sentence serves a purpose 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?

Given the tool's 4 parameters and no output schema, the description sufficiently covers the input semantics, use cases, and return structure. It could mention more about the output format but is adequate for typical usage.

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 4 parameters. The description adds meaning by stating the default model and the condition for using _apiKey, which clarifies the parameter's role beyond its schema 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 states the verb 'probe' and the resource 'LLMs', specifies scoring 0-100 per model, and distinguishes this from sibling tools like ask_pipeworx which are about querying a specific knowledge base.

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

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

It explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to provide the _apiKey for Anthropic. However, it does not explicitly state when not to use it vs siblings.

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

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

Annotations already signal readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context by explaining that the tool routes questions to other tools, fills arguments automatically, and returns citation URIs, so an agent understands it as an orchestrator rather than a single-source lookup. Minor gap: no detail on rate limits or failure behavior, but annotations already cover the safety 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 dense but well-organized: priority statement, mechanism, trigger phrases, examples, and alternatives. It is slightly longer than necessary because 'START HERE for most questions' and 'even if web search could also answer it' reinforce the same idea, but every section contributes useful routing guidance.

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

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

For a high-complexity router with no output schema, the description covers when to use, when not to use, alternatives, accepted input style, concrete examples, and return behavior via citations. An agent has enough context to select and call the tool correctly without needing the schema or extra metadata.

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

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

The input schema has 100% coverage: the required 'question' parameter and all aliases (q, query, prompt, text, input) are fully documented. The description adds illustrative example queries, but the schema already carries the semantic burden, so this stays at the baseline 3.

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

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

The description clearly defines the tool as a question router over '5,798 tools across 1,517 verified sources' that 'returns the structured answer with stable pipeworx:// citation URIs.' It establishes a specific verb+resource contract and distinguishes it as the default alternative to web search and to sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description is explicit about when to use the tool: 'PREFER OVER WEB SEARCH' for factual/current/historical data, 'use whenever the user asks...' specific trigger phrases, and 'START HERE for most questions.' It also names alternatives with selection conditions: ask_pipeworx_grounded for exact answers from a specific source, and deep_research for broad/multi-part fan-out across many sources.

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

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

Beyond the read-only/idempotent annotations, the description discloses genuinely useful dynamic behavior: routing improvements can go live at any time, no candidate is active as of 2026-07-26 so it currently matches ask_pipeworx exactly, and results feed comparison against the stable router. It also clarifies it is a full working router rather than a stub — exactly the kind of non-obvious, ever-changing behavior an agent needs to know.

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

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

Four sentences, front-loaded with identity and differentiator, each earning its place. The triple repetition of 'same...same...same' followed later by 'matches ask_pipeworx exactly' is slightly redundant, and the specific date will age, but the description is otherwise tight and well ordered.

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 router over 5,798 tools with no output schema, the description covers the crucial questions: what it is, how it differs from stable, current state, how to invoke it, and what becomes of results. Response shape is handled by reference to the sibling ('same response shape'), which is acceptable but assumes the agent can resolve ask_pipeworx's contract.

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% — all five alias parameters and question are documented in the schema itself, so the description carries no parameter burden. It adds only the cross-reference that arguments are identical to ask_pipeworx, which is a marginal confirmation rather than new semantic content. 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 states the tool is a universal router identical to ask_pipeworx (same 5,798 tools, same arguments, same response shape) but carrying candidate routing improvements. This precisely identifies the verb (route a question to the appropriate tool), the resource (the 5,798-tool universe), and the differentiator from its siblings ask_pipeworx and 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?

Explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and describes the evaluation loop against the stable router. It names the alternative and the selection condition, though it never states explicit exclusions such as when to prefer the stable router 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?

Even with strong annotations like readOnlyHint and idempotentHint, the description adds substantial behavioral detail: it performs an extra LLM call, returns evidence as verbatim quotes, and provides explicit refusal reasons for cases where the source does not answer. It also discloses the exact success and refusal response shapes.

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

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

The description is dense but every sentence carries essential information: behavior, return format, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the key differentiator and avoids 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?

Despite no output schema, the description fully specifies the return shape and all possible refusal reasons. It also covers routing behavior, cost implications, and use-case boundaries, making it complete enough for an agent to invoke this tool correctly.

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

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

The schema already documents all 6 parameters with 100% coverage, including the aliases for `question`, so the baseline is 3. The description clarifies the overall natural-language query behavior but does not add syntax or format details beyond what the schema already provides.

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

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

The description clearly identifies this as a grounded, hallucination-resistant answer mode that extracts answers only from fetched tool results. It explicitly distinguishes itself from the sibling tool ask_pipeworx while stating its specific responsibility for high-stakes factual reads.

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

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

The description gives explicit when-to-use guidance: use whenever an answer will be quoted, cited, or acted on and facts must not be invented. It also names the alternative ask_pipeworx and says to prefer it for casual lookups, providing a clear decision rule.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by enumerating the returned fields: title, description, category, location, bid, close time, seller agency, and link. 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?

Two sentences: first specifies purpose and lookup mechanisms, second lists return fields. No redundant information; every word is informative.

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

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

For a single-lot lookup tool with well-documented parameters and annotations, the description covers essential context: what to provide, how to provide it, and what is returned. It doesn't discuss error handling or auth, but those are minor given the tool's simplicity.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description adds context by explaining the two lookup methods and the relationship between source/source_lot_id and url, 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 clearly states the verb 'get full details' for a resource 'single government auction lot', and specifies two distinct lookup methods: by source+source_lot_id or by URL. This distinguishes it from sibling tools like 'auctions_search' which returns lists.

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

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

The description implies usage after a search by noting 'as returned by auctions_search', and offers URL as alternative. It does not explicitly state when not to use or name alternative tools, but the context is sufficient for an AI agent to infer appropriate 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 and idempotentHint, so the description only adds minor context (returns time remaining, current bid, location, link). 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?

Two concise sentences that front-load the main purpose and include optional filters and return fields without unnecessary detail.

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

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

For a list tool with no output schema, the description mentions return fields (time remaining, current bid, location, link) and explains the limit constraint. It is sufficiently complete for the use case.

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 descriptions are provided. The description does not add significant new meaning beyond the schema's parameter descriptions.

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

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

The description clearly states the tool lists auction lots ordered by soonest close time across multiple sources, distinguishing it from siblings like 'auctions_search' by specifying the 'what can I still bid on before it ends' view.

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

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

The description implies usage for finding lots closing soon and lists optional filters, but does not explicitly state when not to use or mention alternative tools like 'auctions_search' or 'auctions_coverage'.

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 discloses the exact nature of the output (per-source counts and last-refreshed timestamps), which adds behavioral detail beyond the annotations' read-only/open-world hints. No contradiction with annotations exists, and the description enriches the agent's understanding of what the tool returns.

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 concise sentences that front-load the purpose and include the key output fields. Every word contributes to understanding the tool, with no redundant or missing content.

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

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

For a zero-parameter, no-output-schema tool, the description fully explains what the tool does and when to use it. The tool's simplicity means the description covers all necessary context, making it complete.

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

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

The tool accepts no parameters, and the empty schema is fully documented. Since there are no parameters to explain, the description need not provide additional semantics, and the baseline for zero parameters is appropriate.

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

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

The description clearly states the tool provides an overview of government-auction data availability, including per-source active lot counts and data freshness. It uses specific nouns to distinguish this from sibling tools like auctions_search and auctions_closing_soon, which focus on searching or time-sensitive listings.

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 instructs when to use the tool: to gauge coverage and data currency before relying on it. This provides clear context, though it does not mention when not to use it or name alternative tools, which prevents a top score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds context about the return fields (source, title, location, current bid, close time, link), which is helpful beyond the annotations.

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

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

The description is two sentences, each earning its place. It front-loads the purpose, then details filtering and return info, and ends with a sibling hint. 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?

Given the tool's complexity (7 parameters, no output schema), the description covers all essential aspects: what it does, what it returns, and how to filter. It's sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'keyword' is matched on the item title, 'state' is a 2-letter code, 'asset_type' enumerates values, and 'closing_within_hours' filters by time. 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 it searches live US government auction lots for physical assets, specifies the types of assets and sources, and distinguishes itself from the sibling tool 'auctions_sold_comps' for historical prices.

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 this tool (search live auctions) and when to use alternatives ('auctions_sold_comps' for historical prices). It could further mention not to use for specific lot details (use 'auction_lot_details'), but the main distinction 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by stating that the data 'no upstream site keeps but Pipeworx retains' and that it 'only includes lots that have closed with a recorded final price'. This provides useful context beyond the annotations.

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

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

Three sentences: first defines purpose and uniqueness, second gives usage guidance, third describes output. Every sentence is informative and concise with 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?

The description fully covers what the tool does, what it returns (count, min/median/max/average, recent examples), how to filter, and why it's unique. Despite no output schema, the description compensates adequately. For a tool with 4 optional parameters and aggregation, this is highly complete.

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

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

Schema description coverage is 100% — all 4 parameters have clear descriptions. The description adds usage context ('filter by keyword, asset_type, and/or state' and explains output), but does not significantly enhance the semantic understanding of each parameter beyond what the schema already provides.

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

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

The description clearly states it provides 'Historical SOLD prices for government auction items — the final hammer price of closed lots.' This is a specific verb-resource combination that distinguishes it from siblings like 'auctions_search' (likely for active listings) and 'auction_lot_details' (for specific lot info).

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

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

The description explicitly says 'Use to answer "what do seized pickup trucks actually sell for" or to comp an asset' and gives filtering examples. While it doesn't name alternative tools, the context is clear enough for an agent to decide when to use this vs. other auction-related tools.

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

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

Description extensively details behavioral traits beyond annotations: market resolution, classification, parallel fan-out, response shapes, resolver contract, parent event extraction, news fallback, safety for low-confidence and closed markets, wide-spread handling, and cancellation rule parsing. 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 well-structured with sections and front-loaded purpose, but it is verbose with many examples and detailed explanations. Could be more concise while retaining key information.

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

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

Given no output schema and complex behavior, the description is highly complete, covering input, process, output shapes, edge cases, safety, and resolution details. It leaves little ambiguity for the 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 covers all three parameters completely. Description adds meaningful context: market input formats, depth quick vs thorough, include_raw with size implications. Adds examples and notes beyond schema.

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

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

The description clearly specifies the tool researches a Polymarket bet by pulling Pipeworx data, with specific inputs (slug, URL, question text) and outputs (evidence packet plus comparison). It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on a single bet research.

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

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

The description explicitly states use cases (should I bet, what does data say, is there edge) and examples of when to use. It does not explicitly exclude alternatives but provides ample context for appropriate usage.

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

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

Description adds substantial context beyond annotations: explains data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, etc.), sorting behavior, off-calendar fiscal year handling, and return format with citation URIs. All annotations (readOnly, openWorld, idempotent, non-destructive) are consistent and reinforced.

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

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

The description is front-loaded with examples and key guidance, and every sentence adds value. While it is lengthy, the richness of information justifies the length. Minor opportunity to tighten but overall 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, the description thoroughly covers return format (paired data with URIs), entity types, data sources, sorting, and comparison logic. It addresses potential ambiguity (off-calendar years) and provides complete context for a non-nerd 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?

With 100% schema coverage, description goes beyond enum/type descriptions by detailing exactly what data each entity type retrieves (company: 10-K financials; drug: adverse events, approvals, trials). It also explains sorting by primary metric, adding significant semantic value.

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

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

The description clearly states it performs side-by-side comparisons of 2-5 companies or drugs, listing trigger phrases like 'compare X and Y' and 'head to head'. It distinguishes from siblings by explicitly recommending this tool over sequential single-pack lookups, stating it replaces 8-15 calls.

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 examples and explicitly prefers this tool over sequential lookups. However, it does not specify when not to use it (e.g., if individual profiles are needed 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 and idempotentHint=true, so the description does not need to restate safety. It adds valuable behavior: internal decomposition into facets, parallel routing, response packet shape (verbatim evidence, confidence, source, fetched_at, citation), gap handling, hop semantics, contradictions[], semantic excerpting, and latency expectations. Only minor details like rate limits or exact response serialization are absent.

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

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

The description is front-loaded with the most critical info (account requirement, alternative tool, NOT open-web), but it is a dense, multi-clause paragraph that intermixes operational details (citation URIs, excerpting, latency) with selection guidance. Several sentences are long and could be split for readability, though every sentence does add substance.

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 two parameters, one enum, no output schema, and a large sibling set, the description covers all necessary decision and invocation information: usage context, alternatives, failure behavior (gaps[]), return packet fields, latency, and account prerequisites. The lack of an output schema is compensated by describing the response shape in prose.

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 both parameters. The description adds important nuance: depth level semantics (quick/standard/thorough hops, gap recovery, paid plan for thorough), and the caveat that 'quick' omits contradictions[]. This goes beyond the schema while not fully formalizing the depth mapping.

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

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

The description clearly identifies the tool as a grounded, multi-source research tool over Pipeworx's structured data sources, explicitly differentiating it from open-web search. It names specific capabilities (decomposition, parallel routing, findings packet with citations, gaps[]) that distinguish it from sibling tools like ask_pipeworx.

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

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

The description provides explicit when-to-use guidance ('best for broad/multi-part questions over structured data') and explicit when-not-to-use guidance ('For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'; 'For a single lookup use ask_pipeworx'). It also includes alternative routing based on account tier, making selection unambiguous.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No contradictions.

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

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

Description is front-loaded with purpose and usage, then output details. Every sentence adds value, though slightly long. Well-structured 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 tool's complexity (discovery across many domains) and no output schema, the description is complete: it explains what it does, when to use it, what the return contains (top-N tools with schemas), and how to use the results. Sufficient for agent invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it mentions aliases but schema already covers them. No extra parameter depth.

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: 'Find tools by describing the data or task.' It lists numerous domains and explicitly differentiates itself from siblings by advising 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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 when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear usage context and distinguishes from sibling tools.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses parallel fan-out across sources, soft-fail behavior for patents, expected empty fda_products sections, sources_used/sources_failed reporting, and resolved:false with notes for private companies. This sets accurate expectations for partial or empty results.

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

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

The description is front-loaded with trigger examples and the core one-call promise, then packs rich source behavior into a single structured paragraph. It is slightly long and repeats the type-interchangeability point already in the schema, but the detail is mostly purposeful and well-organized.

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

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

For a tool without an output schema, the description thoroughly specifies supported inputs, return sections such as cik, recent_filings, fundamentals, and failure semantics for empty data and private companies. It covers the complexity of the multi-source tool and leaves an agent well-prepared to call and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by explaining that 'company' and 'ticker' are interchangeable and that value accepts a ticker, zero-padded CIK, or company name with EDGAR resolution. This goes beyond the schema's basic 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?

States a specific verb and resource: full cross-source profile of a US public company. Example queries like 'company profile for Microsoft' and 'everything you know about $TICKER' make the trigger and scope unmistakable, distinguishing it from generic search or comparison siblings.

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

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

Explicitly instructs to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when the user wants a holistic view. Gives concrete trigger phrases and clarifies that ticker, CIK, or company name all work, which guides an agent on when to select it 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?

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not significantly expand beyond the 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 sentences with no wasted words. Directly states purpose and usage guidelines in a compact form.

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, no output schema, and sufficient annotations, the description covers purpose, when to use, and basic behavior. It is complete and contextually adequate.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description only says 'by key', adding no new semantic 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 the action 'Delete a previously stored memory by key', identifying both the verb (delete) and resource (memory by key). It distinguishes from sibling tools like 'remember' (store) and 'recall' (retrieve), which are explicitly mentioned.

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 usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also pairs with 'remember and recall', indicating when not to use the tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that it fetches the page, extracts content, and outputs standard markdown format, which is consistent with annotations and provides useful context beyond them.

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

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

The description is three sentences, front-loaded with the core purpose, and each sentence contributes meaningfully. 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 two parameters with full schema coverage, safety annotations, and no output schema, the description sufficiently explains the tool's behavior and output format for an AI agent to use it correctly.

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

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

Schema coverage is 100% with both parameters documented. The description does not add semantic value beyond the schema descriptions, so baseline score of 3 is appropriate.

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

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

The description clearly states it generates an llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt'. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning.

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

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

The description lists three explicit use cases (client site indexing, personal project drafting, competitor auditing), providing clear context. However, it does not explicitly state when not to use it or name alternative tools.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds that it returns specific fields and includes a parameter to include cancelled ones. 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?

Two sentences only, first states purpose and return fields, second gives 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?

Simple tool with one optional parameter and no output schema. Description covers purpose, return fields, and usage context adequately.

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 parameter include_inactive is described in schema. Description mentions it in context but adds no new meaning beyond schema.

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

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

The description clearly states the verb 'List' and resource 'active subscriptions', and lists the fields returned. This distinguishes it from sibling tools like subscribe/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 says to use this to review what you're monitoring before adding more or to find an id to cancel. Provides clear context for when to use.

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

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

Despite annotations providing minimal safety info (all hints false), the description adds rich behavioral context: filing without an account returns a claim_token for later status checks, the tool is rate-limited to 5 per identifier per day, and it is free with no quota impact. It also discloses the human side (team reads digests daily), which helps calibrate expectations. 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 longer than average but front-loaded with purpose and use cases, and each sentence delivers distinct value. The only mildly expendable sentence is the motivational note about team digests and roadmap, which slightly stretches length without operational necessity.

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 covers the key return behavior (claim_token on filing, status on later retrieval), parameter usage, rate limiting, and exclusions. It sufficiently equips an agent to invoke this tool correctly and interpret outcomes, especially given the 4-parameter nested schema and zero required fields.

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 the description adds substantial parameter-level guidance: claim_token must be passed with no other arguments, message should describe in terms of Pipeworx tools/packs and not paste the user's prompt, and context should reference specific tool/pack/vertical. These instructions go well beyond the schema field descriptions.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' using concrete categories (bug, feature, data_gap, praise). This distinguishes it from sibling tools like ask_pipeworx, which are for questions, not feedback reports.

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

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

Explicit guidance is included: use for bugs, feature requests, data gaps, and praise; use only for Pipeworx-served tools and file elsewhere for third-party MCP servers. It even offers a fallback ('Not sure? Pipeworx tool names are the ones this connection lists'), making selection unambiguous.

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, etc. The description adds value by mentioning data source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating nature.

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, front-loaded with the core action, followed by use cases and technical details. Every sentence adds value with no redundancy.

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

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

For a simple read-only tool with one parameter and rich annotations, the description covers purpose, usage, parameter behavior, and key behavioral traits. It is sufficient for an agent to decide and invoke correctly.

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

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

The single parameter 'window' is fully covered by schema description (100%). The description adds semantic guidance on how shorter vs longer windows affect results, which aids selection.

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 returns top tools, packs, and call volume over a window. It lists three specific use cases, distinguishing it from siblings like 'discover_tools' and 'ask_pipeworx'.

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

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

Explicit use cases are provided for discovery, confirmation, and alignment checking. However, no explicit alternatives or when-not-to-use guidance is given.

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 (readOnlyHint, idempotentHint, destructiveHint), the description details scanning behavior, monotonicity checks, partition sum checks, fill check against live depth, semantic anchor threshold, and partition filter logic. 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 paragraphs per mode, every sentence adds value. Length is appropriate for the tool's complexity.

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

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

Covers all modes, output structure (opportunities[], partition_check, fill check), and edge cases (low similarity, placeholder filtering). Despite no output schema, the description adequately documents return values.

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 brief descriptions. The main description adds substantial context: for event, it explains walking child markets and performing date/threshold checks; for topic, it explains cross-event scanning and semantic anchor. Adds meaning beyond 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 it finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes three invocation modes (no args, event, topic). The verb 'find' and resource 'arbitrage opportunities on Polymarket' are specific and distinct from sibling tools.

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

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

Provides explicit guidance for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. Explains trade-offs (cross-event catches patterns single-event misses) and includes fill check warnings and references to sibling tools for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral context: caching behavior (1h at KV level keyed on knobs), response structure with diagnostics, edge computation details (slippage, Kelly), and limitations (placeholder slugs, Fed bets). 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 dense but well-structured, front-loading the purpose and then detailing model families. While lengthy, the complexity of the tool justifies the detail. It could be slightly more concise, but every sentence adds essential context.

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 9 parameters and no output schema, the description is remarkably complete. It explains the response structure under by_segment, diagnostics for empty segments, and how edges are calculated. It covers all necessary context for an agent to use the 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 good descriptions for all 9 parameters. The description adds extra value by explaining how parameters like min_liquidity and max_spread_pp function as 'tradeable-edge knobs' and elaborates on min_partition_leg_kelly's specific behavior, providing context beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities based on Pipeworx data divergence. It specifies the verb 'scan', the resource 'Polymarket markets', and the output 'opportunities'. The detailed breakdown of model families and segments distinguishes it from siblings like 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 says it's built for 'what should I bet on today' and describes how agents discover opportunities without paging. It provides context on when not to use (Fed bets excluded, unreliable data). However, it could more directly state when to use this tool versus the sibling polymarket_arbitrage.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. Description adds critical limits (60-day TTL, daily closes) that go beyond annotations, providing complete transparency.

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

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

Well-structured with leading sentence, explanation, response format, and limits. Slightly verbose but every sentence earns its place. 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?

No output schema, so description fully explains return fields (tracked, expired, snapshot_dates) and their semantics. Covers edge cases (gaps, lifespan) making it complete for agent use.

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

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

Schema covers 100% of parameters with descriptions. Description reinforces defaults (14 days, '1wk') and adds constraints (max 30) not fully explicit in schema, adding marginal value.

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

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

Clearly defines the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. Distinguishes from sibling 'polymarket_edges' by focusing on time-series analysis and answering whether an edge is shrinking.

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?

Explains when to use by contrasting fresh vs old edges, implying use for assessing trade risk. Does not explicitly list alternatives or when not to use, but provides strong contextual guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the return verdicts (clean|degraded|cannot_fill), the risk of partial fills stranding hedges, and the concept of thin legs. 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 ~280 words but well-structured with uppercase section headers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Front-loaded with purpose. Every sentence adds value; no filler. Could be slightly more concise but structure compensates.

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

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

No output schema exists, so description must cover return values. It does so for both modes, listing fields (top_of_book, vwap_fill_price, etc.) and edge cases (thin_legs, forced_directional_risk). Addresses the dominant loss mode mentioned. Adequately complete for a tool with no output schema.

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

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

Schema description coverage is 100%, baseline 3. The description adds context beyond the schema: interprets size_usd for basket mode as 'settlement notional', explains side default logic for basket, and clarifies the market vs event distinction. This is meaningful added value.

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

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

Description starts with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate when this tool should be used.

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

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

Explicit 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' gives clear guidance. Explains why partial basket fills are dangerous. Does not explicitly list when not to use, but the context is strongly implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, but the description goes far beyond them: it discloses the token-overlap matching method, the fee model omission, compatibility warning codes, temporal alignment semantics, skipped leg counters, and that 'unknown' legs are never paired. It also clarifies that null temporal alignment means 'could not be computed,' not confirmed alignment. No contradiction with annotations exists.

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

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

The description is front-loaded with purpose and then structured around modes, response, safety fields, and disclosures. It is long, but nearly every sentence carries distinct operational information. Some repetition around 'EITHER mode' and 'BOTH modes' could be tightened, which prevents a top 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?

Given that there is no output schema, the description carries the full burden of explaining return behavior, and it succeeds: it covers venue prices, top_spreads_pp, per-entry flags, compatibility codes, temporal alignment, skipped counters, fees, and limitations. An agent has enough context to select and invoke the tool correctly and interpret its output safely.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds meaningful interaction semantics: topic shortcuts auto-fetch matching events, explicit ticker/slug parameters override the topic-mapped side, and both modes run an identical token-overlap matcher. This goes beyond the baseline without needing to compensate for schema gaps.

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 and precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the verb, resource, and scope, and the two-mode breakdown further disambiguates what the tool does from generic arbitrage or single-venue tools.

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

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

The description gives strong usage context: it explains the two modes, which shortcuts are pre-mapped, what explicit parameters do, and warns that 'pre-mapped ≠ tradeable' and that most topics currently return compatibility warnings. However, it does not explicitly name alternatives such as polymarket_arbitrage or state when one should prefer those over this tool, so it stops short of full exclusion guidance.

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

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

Description adds behavioral context beyond annotations: scope (scoped to identifier), pairing with remember/forget, and listing behavior when key omitted. No contradiction with annotations.

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

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

Three sentences, front-loaded with core action, no wasted words. Every 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?

For a single-parameter tool with clear annotations and no output schema, the description covers purpose, usage, scope, and pairing fully.

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

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

Schema coverage is 100% with a description for the 'key' parameter. Description adds examples and explains behavior when omitted (list all keys), adding 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 uses specific verbs ('retrieve', 'list') and clearly identifies the resource (saved memories/keys). It distinguishes from siblings 'remember' and 'forget' by naming them.

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

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

Explicitly states when to use ('to look up context the agent stored earlier') and provides examples (ticker, address, notes). Does not explicitly say when not to use, but context implies alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds value by explaining the mark_read cursor mechanism, the returned fields (source, citation_uri, payload), and filtering behavior, enhancing 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 concise, front-loaded with the main action, and every sentence adds specific information 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?

Given the tool's 5 optional parameters and no output schema, the description adequately explains return content, filtering, and the mark_read behavior. It also mentions polling and an alternative access method, though it doesn't detail pagination or limit behavior beyond schema defaults.

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%. The description adds context by providing an example type (sec_8k), specifying that 'since' is an ISO timestamp, and explaining the effect of mark_read. This adds meaning beyond the schema's property descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the action and resource. It distinguishes itself from siblings like list_subscriptions and search_within by focusing on recent alerts from the persisted feed.

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 mentions that polls work fine and provides an alternative GET endpoint for scripts and dashboards, offering some usage context. However, it does not explicitly contrast with other tools or state when not to use this tool.

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

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

Adds behavioral context beyond annotations: fans out to multiple sources, includes fallback logic, notes USPTO soft-failure. Describes return structure (changes[], total_changes, citation URIs). No contradiction with annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false).

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

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

Well-structured: starts with example queries, then sources, parameters, return structure, and alternative. Every sentence adds value, though slightly lengthy. Front-loaded with purpose.

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

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

Complex tool with multiple external APIs and no output schema, but description covers return structure, limitations (USPTO sunset), and fallback. All three parameters fully described with examples. Complete for effective use.

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

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

Schema coverage is 100% but description adds significant meaning: explains 'since' accepts ISO date or relative shorthand with examples, 'type' only supports 'company', 'value' accepts ticker or CIK. This goes well beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists example queries and specifies data sources (SEC EDGAR, GDELT→GNews, USPTO), distinguishing it from sibling 'entity_profile' which provides static profile.

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

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

Explicitly indicates when to use (recent changes over a window) and when not to ('Use entity_profile instead when you want the static profile'). Describes fallback behavior (GDELT→GNews) and soft-failure for USPTO, providing clear context for 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?

Description adds behavioral context beyond annotations (key-value pair scoped by identifier, persistence 24h for anonymous, authenticated users persistent). Consistent with idempotentHint=true.

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

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

Concise multi-sentence structure with main purpose first, followed by usage guidance and pairing info. Every 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?

Fully explains storage model, session scoping, and persistence. No gaps given the simple storage functionality and no output schema.

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

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

Schema coverage is 100%, but description adds contextual examples of key-value pairs (e.g., 'subject_property', 'target_ticker') that enhance understanding beyond schema.

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

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

The description clearly states the tool's verb ('save') and resource ('data'), provides concrete examples (resolved ticker, target address), and distinguishes from siblings (recall, forget).

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

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

Explicitly indicates when to use ('when you discover something worth carrying forward'), contrasts with sibling tools, and notes authentication-based persistence differences.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses rich behavioral detail: graceful degradation of LEI/FIGI enrichment, ambiguity handling via figi_candidates, explicit unresolved identifiers, ISIN-to-LEI mapping, and multi-endpoint cascading. This gives an agent an accurate model of what happens at call time.

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 content is valuable, but it is delivered as one dense, run-on paragraph with heavy parentheticals and editorializing. It would be easier for an agent to consume if split into purpose, usage, and per-type behavior sections. Every item earns its place, but the structure makes it harder 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?

Given the tool's complexity and the absence of an output schema, the description covers the essential behavior: input types, supported entity types, ambiguity behavior, unresolved-result handling, fallback behavior, and identifier sources. An agent has enough context to call it correctly.

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

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

Although the schema already covers both parameters, the description adds meaningful semantics: ISIN as an accepted company input, the entity-name-only rule for bond issuers, and the warning that trailing security-class words will fail FIGI matching. It also clarifies the drug type with brand/generic examples.

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

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

The description names a specific verb and resource: resolve a user-spoken name to canonical/official identifiers needed by other tools. It is immediately distinguishable from siblings like entity_profile or compare_entities, and the opening examples make the intended use unmistakable.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' which is clear when-to-use guidance. It does not name explicit alternatives or when-not-to-use cases, but the priority placement and identifier-focused framing make the intended position among sibling tools 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 (readOnlyHint, idempotentHint, etc.) are consistent. Description adds that it probes with ai_visibility_check and returns a ranked list. Does not cover rate limits or network behavior, but is sufficient for a read-only orchestration 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?

Three sentences: purpose, mechanism, and example use case. No extraneous words. Information is front-loaded and 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?

Description explains the return format (ranked list with score, confidence, signal density). No output schema exists, so this is adequate. Could mention error handling or entity limits (2-8 in schema), but schema covers that.

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% (baseline 3). Description adds value by explaining that the first entity is the 'subject' and others are competitors, and clarifies model usage with API key requirement. This goes 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 uses specific verbs ('compare', 'probes', 'ranks') and identifies the resource ('AI visibility across multiple entities'). It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic) by focusing on AI-marketing audits.

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

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

Description provides a clear use case ('competitive AI-marketing audits') with an example question. It implies the tool is for multi-entity comparison but does not explicitly state when to use alternatives like ai_visibility_check or compare_entities.

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?

Disclosures beyond annotations: composite call fanning out to two services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timed-out sources. All consistent with readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false.

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

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

Description is fairly long but packed with essential details. Front-loaded with main purpose. Slightly verbose but appropriate for a complex tool; concise enough for understanding.

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 enumerates all returned fields (summary block, per-advisory detail, links, alternative versions). Covers latency, partial failures, ecosystem scope. Highly complete 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 has 100% coverage with descriptions for both parameters. The description adds context: scoped packages accepted, version defaults to latest. This adds minor value beyond the schema, justifying a 4.

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

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

The description clearly states it's a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It specifies the return summary and distinguishes from siblings by noting NPM ecosystem only and referencing alternatives for other ecosystems.

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 an agent asks about safety, popularity, or size, or cost of adding a package. Also notes NPM-only scope and that other ecosystems use deps.dev directly, providing clear usage boundaries.

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 (readOnlyHint, idempotentHint, etc.), the description adds specific behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and that passages include offsets for verification.

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

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

The description is a single paragraph with front-loaded purpose, and every sentence adds necessary information. No redundant or 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?

Despite no output schema, the description explains return format (top-N passages with offsets and similarity scores), covers edge cases (truncation), and integrates with sibling tools. All aspects are addressed.

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 the description adds value: provides max length for text, examples for query, and default value for limit (5) not in schema. It does not conflict with 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, provides specific examples (SEC 10-K, article), and distinguishes from siblings by mentioning pairing with 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 explicitly recommends using the tool when a record is too large for the prompt, and it mentions a complementary tool (ask_pipeworx_grounded). It does not explicitly state when not to use, but the guidance 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 already indicate a non-read-only, non-destructive, idempotent operation. The description adds significant behavioral context: authentication requirements, SMS rate limits (10/day), webhook auto-disable after 10 failures, and the one-time return of the webhook secret. No contradictions with annotations.

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

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

The description is a single dense paragraph that packs a lot of information without wasted words. It could be broken into bullet points for scanability, but the information is well-organized and front-loaded with the main purpose.

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

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

Despite no output schema, the description explains the return value (new subscription ID) and covers all aspects: types, parameters, delivery options, authentication, rate limits, and failure recovery. The agent has enough information to use this tool correctly.

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

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

Schema coverage is 100%, but the description goes beyond with detailed examples for each subscription type and delivery option (e.g., sec_8k items codes, polymarket_edge topic, webhook signing explanation). This adds real meaning for the agent.

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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It lists supported types and delivery channels, which distinguishes it from sibling tools like recent_alerts or unsubscribe.

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

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

The description provides clear context for when to use this tool (e.g., setting up ongoing monitoring) and notes prerequisites like needing a Pipeworx OAuth account and phone verification for SMS. It does not explicitly exclude alternatives but does imply that the feed is always on, so one-time pulls can use recent_alerts.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are fully consistent with description. The description adds value by detailing the output structure (category-bucketed examples with tool+argument shapes) and source (live catalog). 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 moderately long but every sentence contributes: example queries, output description, usage instruction. Information is front-loaded with the purpose, and structure is logical. No fluff.

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

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

Given the simple parameter set (1 optional), no output schema, and thorough annotations, the description provides complete context for an agent to use the tool correctly. It explains what to expect and when to use it.

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

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

Schema coverage is 100% with a clear description of the topic parameter. The description's mention of topic values mirrors the schema without adding new semantic meaning. Baseline 3 is appropriate as schema already does the heavy lifting.

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

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

The description clearly identifies the tool as an onboarding entry point with specific verbs ('suggest', 'use this first') and resource ('what can I ask Pipeworx?'). It distinguishes from siblings like 'discover_tools' and 'ask_pipeworx' by stating it returns 'category-bucketed example questions' and is meant for initial discovery.

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 do not yet know what Pipeworx can do for you') and how to call (no arguments vs. topic). The description also guides toward meta-tools, providing clear context and alternatives.

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

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

The description adds significant context beyond annotations: it explains that rows are deactivated (not deleted) and ownership is enforced. This aligns with the non-destructive and idempotent hints, and fully discloses the behavioral traits.

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 no wasted words. It front-loads the primary action and then adds critical behavioral context, making it highly 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?

The description covers purpose, ownership constraint, deactivation behavior, and linkage to 'recent_alerts' for historical data. For a simple one-parameter tool with no output schema, this is fully complete.

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

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

The input schema already has 100% documentation coverage for the lone 'id' parameter, describing it as a UUID from subscribe. The tool description reiterates 'by id' but adds no additional parameter meaning beyond what the schema provides.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscription), with additional context about deactivation vs deletion. This distinguishes it from siblings like 'subscribe' and 'recent_alerts'.

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

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

The description explicitly tells when to use this tool (to cancel subscriptions) and implies when not to (not for deleting, only own subscriptions). It does not explicitly list alternatives but provides sufficient context through ownership and deactivation details.

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 annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior, but the description adds critical behavioral nuance that annotations can't: the distinction between could_not_verify (check failed, not evidence) and unsupported (no source covers it), the routing logic between SEC/XBRL and the grounded pipeline, and the inclusion of citations. This is transparent and doesn't 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?

Although the description is long, every sentence earns its place. It opens with trigger phrases, then states purpose, then covers routing, outputs, and critical caller warnings, ending with the value proposition of replacing multiple calls. The structure is front-loaded and logically organized, with no filler or redundancy.

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

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

With no output schema, the description fully explains return values (verdict types, actual value, citation, reasoning) and the nuanced meaning of error states. It also covers both routing paths and provides usage intent. Combined with strong annotations, this description is complete for a tool of this complexity.

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

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

Schema coverage is 100% with both parameters described, so the baseline is 3. The description adds meaningful context beyond the schema: it gives concrete example claims for 'claim', and for 'tolerance_pct' it explains the override behavior, default derivation from the wording, and recommended values for hallucination detection. This elevates the parameter understanding beyond what the schema provides.

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

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

The description clearly and specifically states the tool's purpose: natural-language claim verification against authoritative sources. It uses strong verbs like 'verify', 'fact check', and 'check', and distinguishes itself from siblings by focusing on claims that return a verdict rather than open-ended Q&A. It also details the two internal pipelines (structured SEC/XBRL for financial claims, grounded for all others), making the 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 explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' This is clear and actionable. It also explains that it replaces 4–6 sequential calls, implying a composite use case. However, it doesn't explicitly name alternative tools or specify when not to use it, so it stops short of full when/when-not/alternatives guidance.

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