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 declare readOnly/openWorld/idempotent/non-destructive. The description adds useful behavior: 'returns the structured answer with stable pipeworx:// citation URIs', 'one fast call', 'works on every tier', and routing to live news + news-feeds packs. It does not contradict annotations. Minor gaps: no mention of rate limits or error behavior, but those are not expected given annotation coverage.

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

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

The description is long but well-organized: it front-loads the primary instruction ('PREFER OVER WEB SEARCH'), provides concrete examples, and ends with clear escalation guidance. Every sentence adds value, though the length is at the upper limit for a tool descriptor.

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

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

The description is highly self-sufficient. It explains the internal routing, citation URIs, the distinction between ask_pipeworx and grounded/deep_research, applicable domains, and even news behavior. With no output schema, this textual detail compensates fully. Sibling distinctions are covered explicitly.

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 already provides 100% coverage: the only meaningful parameter is 'question', with five documented aliases. The description's examples ('What was Apple's revenue in 2024?') reinforce natural-language usage but do not add new semantic layers beyond what the schema states. Baseline 3 is appropriate.

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

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

The description clearly states this is a question-routing/answering tool with a specific verb ('routes the question'), resource scope ('5,529 tools across 1,455 verified sources'), and output ('structured answer with citations'). It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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 'PREFER OVER WEB SEARCH' and lists trigger phrases like 'what is', 'look up', 'find', plus examples. It says 'START HERE for most questions' and defines when to escalate: 'for hallucination-resistant... use ask_pipeworx_grounded; for broad/multi-part... use deep_research.' Also addresses news routing.

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

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

Beyond the annotations (read-only, idempotent), the description discloses that it is experimental, currently identical to ask_pipeworx, and that routing may change when a candidate is under test. It also clarifies it is a full working router with no fallback, providing rich behavioral context.

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

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

The description is information-dense with no filler, covering the beta nature, relationship to the stable tool, current state, exact usage, and experimental context in a compact format.

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

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

Given the tool's complexity as a router, the description fully explains its capabilities, current matching behavior, experimental edge, and fallback semantics. The same response shape as ask_pipeworx is referenced, which is sufficient for understanding outputs without an 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?

The input schema already describes all six parameters as aliases for the natural-language question. The description adds no extra parameter details, so a baseline score of 3 is appropriate since schema coverage is complete.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself by noting candidate routing improvements are periodically enabled, making its purpose and relationship to the stable sibling explicit.

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

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

Explicitly instructs to use it exactly like ask_pipeworx when the newest routing is desired, noting results are compared against the stable router. This provides clear when-to-use guidance and differentiates it from the stable alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds substantial behavioral context beyond that: the refusal protocol with specific refusal_reason enum values, the verbatim evidence quote, the data_truncated failure mode, and the extra LLM call cost. 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 every sentence contributes critical operational detail: return shape, refusal reasons, usage policy, and cost tradeoff. It is structured clearly with success/refusal dichotomy, though it could be slightly tightened without losing value.

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

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

With no output schema, the description takes full responsibility for explaining the return contract, and it does so completely: success payload fields, refusal reasons, evidence type, and cost. It also clarifies relationship to sibling tools, making it fully sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and all six parameters are aliases for the same core 'question' field, thoroughly documented in the schema. The description's mention of 'fills arguments' is contextual but does not add semantic detail beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explicitly explains it 'EXTRACTS the answer using ONLY what the tool result contains.' This specific verb+resource pairing distinguishes it from its sibling ask_pipeworx by emphasizing grounded, evidence-based answers rather than open-ended responses.

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

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

The description gives explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' followed by concrete examples. It also names the alternative and when to prefer it: 'prefer ask_pipeworx for casual lookups.' This fully covers when and when-not.

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?

The description discloses major behavioral traits not captured by annotations: latency of 15-60s (up to ~90s for thorough), the guarantee that unanswered facets return explicit gaps[] and are 'never invented', the contradictions[] scan, semantic excerpting of large records, and the notable constraint that citation_uri is 'present only when the source emits one that resources/read can actually serve'. It also discloses the account and paid-tier requirement.

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

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

The description is long but every sentence earns its place; the account gate is front-loaded, followed by the core capability and differentiators. The density is justified by the tool's complexity and the lack of an output schema, though a slightly tighter ordering could improve scanability.

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

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

With no output schema, the description fully specifies the return packet structure: verbatim evidence, confidence, source, fetched_at, a stable pipeworx:// citation, explicit gaps[], contradictions[], and the hop field and citation_uri. It also covers latency, depth semantics, account requirements, and exclusions, making the tool virtually self-explanatory for an agent.

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

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

Even though schema coverage is 100%, the description adds valuable semantics: it explains the depth enum values with concrete counts ('quick=3 (single hop), standard=5 (default; adds a gap-recovery hop...), thorough=8 (paid; adds a full iterative hop...)') and clarifies that the question parameter is natural language and can be broad/multi-part, which is crucial for correct invocation.

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

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

The description identifies a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' that 'decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL, and returns a findings packet'. It clearly distinguishes itself from open-web search and from sibling ask_pipeworx by naming that alternative directly.

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

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

Explicit usage guidance is provided: 'For a single lookup use ask_pipeworx (one LLM call, not many)' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also instructs to use ask_pipeworx when not signed in, since deep_research requires an account, and details when depth levels are appropriate.

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

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

Annotations already 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context such as fanning out across multiple sources, returning specific data fields, and noting USPTO patent API soft-fail. Slight improvement possible with error handling details.

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

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

The description is lengthy but well-structured, front-loaded with example queries. Every sentence adds value given tool complexity, though minor trimming possible. Still effective.

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

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

No output schema exists, but the description thoroughly explains return structure (cik, company_name, recent_filings, fundamentals, patents, news, LEI). Covers all key aspects an agent needs to understand what the tool returns.

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. The description adds meaning beyond schema: explains that 'type' only supports 'company' and 'value' can be ticker or CIK, and stresses that names are not supported, which aids correct invocation.

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

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

The description clearly states the tool's purpose: to provide a full cross-source profile of a US public company via examples and explicit 'full cross-source profile' phrasing. It distinguishes from sibling tools like resolve_entity and chaining individual lookups.

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

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

The description explicitly tells when to use this tool (holistic view requests) and when not to (if only a name, use resolve_entity). It also states it should be preferred over chaining single-pack lookups, providing clear 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 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 indicate read-only, open-world, idempotent behavior. The description adds substantial context: response structure, safety fields (compatibility_warning, temporal_alignment), and counters for skipped comparisons. 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 lengthy but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, though some redundancy could be trimmed. Front-loaded with purpose, then details.

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 response in detail: leg-by-leg prices, spread array, top_spreads_pp, and safety fields. Covers edge cases like temporal misalignment and non-equivalent bet shapes. Comprehensive for a complex tool.

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

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

All three parameters have descriptions in the schema (100% coverage). The description further clarifies usage: topic lists exact shortcuts, explicit tickers override topic mapping. This adds meaning beyond the schema.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers), distinguishing it from sibling tools like polymarket_arbitrage. The verb and resource are well-defined.

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

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

Provides explicit when-to-use guidance: two modes with example shortcuts and explicit pairing. Warns that most pre-mapped topics return compatibility warnings and are not tradeable, helping the agent avoid misuse. Also explains safety fields and conditions for non-equivalent bet shapes.

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

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

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 annotations (readOnly, idempotent, openWorld), the description discloses important behaviors: graceful degradation when GLEIF/OpenFIGI is unavailable, explicit listing of unresolved identifiers under `unresolved`, and internal cascading through multiple lookup endpoints. This adds significant context about failure modes and data provenance.

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

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

The description is long but packed with distinct facts: query examples establish use cases, the 'Use FIRST' instruction provides a clear action, and the type-specific blocks add necessary detail. The structure moves from examples to a general rule to specifics, making the length justified and scannable.

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 what the tool returns for both types, including the `unresolved` field and the rxnorm citation format. It covers input normalization, sources, ownership data, and failure handling, making the tool self-contained and complete for an agent.

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

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

Although the schema already describes both parameters, the description enriches them substantially: for 'company' it details the cross-source identity spine (CIK + ticker + LEI + FIGI + ownership data) and accepted input forms; for 'drug' it specifies RxCUI, ingredient, brand, and citation output. It also clarifies that enrichment degrades gracefully, which is not in the schema.

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

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

The description explicitly states that the tool resolves a user-spoken name to canonical/official identifiers and provides concrete query examples ('What's the ticker for…'). It distinguishes itself from siblings by framing itself as the first step for name-to-ID conversion, while tools like entity_profile imply deeper analysis after resolution.

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

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

The description gives a clear directive: 'Use FIRST whenever you have a name but need an ID.' It also specifies the two supported types (company, drug) and their accepted input formats, allowing the agent to choose correctly. However, it does not explicitly name alternative tools to use instead, so the exclusion guidance is implicit rather than explicit.

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

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

Annotations (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.