Open Contracting

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

Annotations already declare readOnlyHint=true, destructiveHint=false, establishing safety. The description adds behavioral context: default model, free tier, BYO key for Anthropic, and output structure, enriching 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 extremely concise—two sentences—with no wasted words. It front-loads the primary action and effectively uses whitespace for readability.

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

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

Given no output schema, the description partially explains return structure (per-model fields + combined view). Parameters are fully covered. Slightly incomplete on output details but adequate for a safe, simple tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: default model for 'models', purpose of '_apiKey', and disambiguation role of 'context', surpassing schema alone.

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

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

The description clearly states the tool probes LLMs about an entity and scores visibility, with specific verb and resource. It does not explicitly differentiate from siblings like 'scan_competitor_ai_presence', but the purpose is 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?

The description mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not provide when-not-to-use or contrast with sibling tools, leaving usage context implied 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?

Beyond readOnly/OpenWorld/idempotent hints, the description explains it routes to 5,502 tools, fills arguments, returns structured answers with citations, is the default entry point, and works on all tiers. It also implies limitations by recommending ask_pipeworx_grounded for hallucination-resistant answers.

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 tightly organized: it opens with a strong directive, lists domains, explains the mechanism, gives trigger phrases and examples, then details alternatives. Every sentence serves a purpose, with no filler.

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

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

For a router tool without an output schema, the description adequately covers what it returns (structured answer with pipeworx:// citation URIs), when to use it, and how it compares to siblings. No crucial gaps identified.

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

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

Schema coverage is 100% with all parameters described, so baseline is 3. The description adds value by providing concrete example questions (e.g., 'current US unemployment rate', 'Apple's latest 10-K') that illustrate the range of input, warranting a 4.

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

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

The description clearly states the tool answers factual questions by routing to thousands of verified data sources and provides examples. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says to prefer over web search, gives trigger phrases, and explains when to step up to alternatives (ask_pipeworx_grounded for grounded answers, deep_research for broad questions). Also clarifies breaking-news handling.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable context beyond annotations: it explains this is a live experimental router with candidate routing improvements under test, currently matches ask_pipeworx exactly because no candidate is active, and falls back to nothing (it is a full working router). This clarifies the behavioral nuances of an experimental version without contradicting annotations.

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

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

The description is a single, dense paragraph that conveys all essential information: beta status, parity with ask_pipeworx, current inactive state, usage instructions, and comparison purpose. It is slightly long but every sentence earns its place; no filler or redundancy beyond the detailed context needed for an experimental tool.

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

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

Given the tool's complexity (experimental router with 5,502 tools) and rich annotations/output schema absence, the description adequately covers purpose, current behavior, usage, and the comparison process. It explains the fallback behavior and active state, but could theoretically add more detail about what 'candidate routing improvements' entail or how to interpret results, though this may be intentionally abstract for an experimental 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 description coverage is 100% with six parameters, but the description adds semantics by stating the same arguments as ask_pipeworx and that all parameters are aliases for the natural language question. While the schema already documents each alias, the description confirms the universal router's argument handling and reinforces that 'question' is the primary parameter, adding slight value beyond the structured fields.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx with a specific universal router function, explicitly stating it has the same 5,502 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by explaining it is the experimental edge with candidate routing improvements, providing clear sibling differentiation.

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

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

The description explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains the current state (no active candidate matching ask_pipeworx exactly) and that results are compared against the stable router for merging decisions, giving clear context and an implicit alternative (ask_pipeworx) without being misleading.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses critical behavioral traits: it returns a structured answer with evidence and confidence, and explicitly lists all possible refusal reasons when data is insufficient. This fully informs the agent about the tool's operational behavior.

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

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

The description is detailed but every sentence serves a purpose: defining the mode, referencing the sibling tool, explaining the output structure, listing refusal reasons, and providing usage guidance with cost trade-offs. It is front-loaded with the key phrase 'Hallucination-resistant answer mode' and is well-structured 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 lack of an output schema, the description fully compensates by specifying the exact return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and all possible refusal cases. It also positions the tool within its sibling set by referencing the shared routing with ask_pipeworx, making it contextually 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?

The input schema already covers all parameters at 100% coverage, with each being an alias for the natural-language 'question' parameter. The description adds little parameter-specific detail beyond what the schema 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 clearly states the tool's function: a hallucination-resistant answer mode for high-stakes reads that extracts answers using only the tool result content. It distinguishes itself from its sibling ask_pipeworx by highlighting the grounded extraction and refusal behavior, making its purpose unambiguous.

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

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

It explicitly specifies when to use the tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'), while also naming the alternative (ask_pipeworx) and explaining the extra LLM call cost. This provides clear decision-making guidance.

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

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

The description extensively explains behaviors beyond annotations: low-confidence short-circuit, closed market handling, wide-spread warnings, resolution-rule risk, and blocking mechanisms. Adds significant value beyond the readOnlyHint and idempotentHint.

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

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

The description is very long and detailed, with multiple sections. While comprehensive, it could be more concise. The structure with headers helps, but brevity is sacrificed for completeness.

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

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

Given no output schema, the description thoroughly covers response shapes, resolver contract, parent_event extractor, news fields, safety measures, and resolution rules. Highly complete for a complex tool.

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

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

All 3 parameters are described in schema (100% coverage). The description adds value with examples for market, depth meanings (quick vs thorough), and include_raw behavior details.

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 researches Polymarket bets by pulling Pipeworx data in one call, with specific inputs and outputs. It doesn't explicitly differentiate from sibling tools like ask_pipeworx or polymarket_edges, but the purpose is 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?

Explicit use cases are provided: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' However, it does not include when not to use or mention 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 indicate safe read-only operation. The description adds valuable behavioral details: what data is pulled per type, handling of off-calendar fiscal years, sorted results, and citation URIs. No contradiction with annotations.

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

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

The description is longer but every sentence adds value. It starts with examples, states core function, then adds details. Could be slightly trimmed but overall efficient for the complexity.

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

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

No output schema, but description mentions return includes paired data and citation URIs. It covers key aspects like metric sorting and data sources. Additional specificity on output formatting would improve completeness.

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

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

With 100% schema coverage, the description still enriches understanding by explaining how each type affects data retrieval (financials vs. safety counts) and how the values parameter should be formatted (tickers/CIKs for company, names for drug). This goes well beyond the schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 entities (companies or drugs) in one parallel call. It provides example queries and distinguishes itself from sequential single-entity lookups, making the purpose unmistakable.

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

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

Explicitly advises preference over sequential single-pack lookups when comparing entities. While it doesn't name alternative tools, it contrasts with the sibling 'entity_profile' (single entity) and implies not to use for single queries.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses rich behavior: parallel routing across 5,502 tools, findings packet structure (verbatim evidence, confidence, source, fetched_at, citation), explicit gaps[] for unanswered facets, 'never invented' claim, hop field, citation_uri resolvability, contradictions[] for standard/thorough, semantic excerpting, and latency expectations (15-60s, thorough up to 90s). This far exceeds annotation coverage and provides deep 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 long but every sentence earns its place, with clear front-loading of the critical account/alternative info. The structure flows logically from function to use cases to depth semantics to citations to performance. It is slightly verbose, but for a complex tool this is justified; a 5 would be for an even tighter presentation.

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: findings packet with specific fields, gaps[], contradictions[], hop, citation_uri, and semantic excerpting. It also covers account requirements, alternatives, latency, and depth options. For a parameter-rich, multi-step tool, the description is complete enough 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?

The description adds substantial meaning beyond the input schema. While the schema describes the 'depth' enum values, the description enriches them with behavioral details: standard 're-angles unanswered gaps (gap recovery)' and thorough 'chases the best leads... plus the contradictions[] scan', along with paid-plan implications and latency differences. For 'question', it explains broad/multi-part is fine and that decomposition is the point, more than the schema's generic phrase.

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

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

The description clearly states the tool performs 'grounded multi-source research' across Pipeworx's structured data sources, explicitly distinguishing it from open-web search. It also differentiates from ask_pipeworx by noting it's 'best for broad/multi-part questions' with decomposition and parallel routing. The verb+resource+scope is specific and unambiguous.

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

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

The description gives explicit usage guidance: 'Best for broad/multi-part questions over structured data', and contrasts with 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also explains account requirements and provides an alternative ('If you are not signed in, use ask_pipeworx instead'), covering both when-to-use and when-not-to-use.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns top-N relevant tools with full schemas and curated examples, ready to call directly, and accepts multiple aliases. 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?

Four sentences, front-loaded with key purpose. Every sentence adds value; no wasted words. Efficient and clear.

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

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

For a discovery tool with 6 parameters (all described) and no output schema, the description completely explains input aliases, output (top-N tools with schemas), and usage context. No gaps.

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

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

Schema has 100% coverage with descriptions for all parameters. Description adds value by noting aliases for query and giving natural language examples, going beyond schema.

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

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

Clearly states 'Find tools by describing the data or task.' Specific verb and resource, and the description makes it distinct from sibling tools by explaining it returns tool definitions with schemas.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear usage context and examples of tasks.

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, etc. Description adds behavioral details: fans out across multiple sources, mentions USPTO patent sunset and soft-fail behavior, and lists return fields. 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?

Single paragraph with example queries front-loaded for LLM recognition. Every sentence adds value, though slightly dense. Could be broken into bullet points for readability.

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 2 required params and no output schema, the description covers inputs, outputs, data sources, fallbacks, usage priority, and limitations. Very complete for the tool's complexity.

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

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

Schema coverage is 100%, but description adds context: explains type enum limits, format of value (ticker or zero-padded CIK), and explicitly warns that names are not supported, referencing resolve_entity. This adds significant guidance 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 it provides a 'full cross-source profile of a US public company' and lists exact return fields. It distinguishes from siblings like resolve_entity by noting names are not supported and directing to use resolve_entity first.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides when-not-to-use by stating names not supported and suggesting resolve_entity as an 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 indicate destructive and idempotent behavior. The description adds relevant context about clearing sensitive data and confirms the operation, but does not detail error handling or behavior for nonexistent keys. Slight gap, but overall consistent and useful.

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?

Extremely concise at two sentences, front-loaded with the primary action. Every sentence serves a purpose: stating the operation, giving usage context, and linking to siblings.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description is fully complete. It covers what, when, and how to pair, leaving no gaps for the intended 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%, and the schema already describes the 'key' parameter. The description simply restates 'by key' without adding new meaning. Meets baseline but does not exceed.

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') with a specific verb and resource. It distinguishes this tool from its siblings (remember, recall) by focusing on deletion, making the purpose unambiguous.

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

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

Explicit usage guidance is provided: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also recommends pairing with remember and recall, offering 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?

Annotations already convey safety (readOnly, idempotent). Description adds behavioral details: fetches an external page, extracts content, emits markdown. Contradicts none.

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

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

Single paragraph, front-loaded with main action, no redundant sentences. 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?

No output schema, but description clearly states output is a single text blob ready to drop at site-root/llms.txt. Complete for a simple two-parameter tool.

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

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

Schema coverage is 100%; parameters are well-documented in schema. Description adds no additional meaning beyond implying url is the site to summarize.

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

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

Description clearly states it generates a production-ready llms.txt file for any URL, listing specific actions (fetch, extract title/description/key links, emit standard format). It distinguishes from siblings like scan_competitor_ai_presence by focusing on 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?

Explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing competitor. Clear context, but no explicit when-not-to-use or alternative sibling names.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds value by listing the exact fields returned and the effect of the 'include_inactive' parameter, extending beyond annotations.

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

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

Two sentences with no wasted words. The purpose and return fields are front-loaded, and every sentence serves a clear 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?

For a simple tool with one optional parameter and no output schema, the description is complete. It covers what the tool does, what it returns, 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%, so baseline is 3. The description does not add additional parameter meaning beyond the schema's description of 'include_inactive'. It meets the minimum but does not enhance understanding.

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

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

The description uses a specific verb 'list' and resource 'subscriptions', clearly stating the tool's purpose. It distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing active subscriptions.

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

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

The description provides explicit when-to-use guidance: 'review what you're monitoring before adding more or to find an id to cancel.' It does not discuss when not to use, but the context is clear.

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

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

The description adds behavioral context beyond annotations by noting the data is from a 'weekly-refreshed mirror' and specifying exactly what counts are provided. Annotations already declare it as read-only, idempotent, and non-destructive, and the description aligns with these without contradiction.

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

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

The description is two sentences: the first gives the core purpose, the second provides detailed context about countries and freshness. It is front-loaded and every sentence adds value, 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?

Given zero parameters and no output schema, the description fully explains what the tool returns and when to use it. It covers the purpose, scope, behavior, and usage guidance completely for a simple overview tool.

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

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

The tool has zero parameters, so the schema provides full coverage. The description explains the return value (country data details), compensating for no output schema. A score of 4 is baseline for zero parameters, and the description adds meaningful context.

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

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

The description clearly states the tool's purpose: providing per-country publisher name, release and contracting-process counts, and freshness of procurement data. It distinguishes itself from sibling tools like oc_process_history, oc_recent, and oc_tender_search by being a high-level overview, making its role unique.

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 to 'Call this first' before relying on data, providing clear usage context. It also lists the 18 covered countries, helping the agent decide when this tool is appropriate.

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

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

The description adds value beyond the annotations by stating the chronological order and the progression from tender to award to contract. Annotations already confirm read-only, idempotent, non-destructive behavior, so the description complements these with specific return characteristics.

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 long with no wasted words. It front-loads the purpose and includes essential details (chronological order, contents, source of OCID) efficiently.

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

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

Given no output schema, the description adequately explains the return format (chronological OCDS releases showing progression). It could mention if there is any limit on the number of releases or sorting details, but the chronological ordering is specified. Overall, it is sufficient for a simple lookup tool.

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

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

With 100% schema coverage and a single parameter, the description adds context by noting the OCID comes from oc_tender_search/oc_recent. The schema already includes an example and description, so the added value is moderate but helpful.

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

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

The description clearly states the tool returns the full release history for a single contracting process by OCID. It uses a specific verb ('trace') and resource ('contracting process'), and distinguishes from sibling tools like oc_tender_search and oc_recent by referencing them as sources for the OCID.

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 it to trace how a specific government tender played out,' providing a clear use case. It also mentions that the OCID comes from oc_tender_search or oc_recent, guiding the user on prerequisites. However, it does not specify when not to use this tool (e.g., for multiple processes) or mention alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by listing data sources (OCDS publishers) and ordering (newest first). Does not contradict annotations. Minor omission: no mention of pagination behavior beyond the limit parameter.

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

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

Two sentences, front-loaded with main purpose, then filtering options. No wasted words. Efficient and well-structured.

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

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

No output schema, so description could have clarified return fields or format but does not. It covers countries and ordering, but lacks details on pagination or typical response structure. Acceptable for a simple list tool but could be more helpful.

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 3 parameters described). Description adds minimal extra: 'forgiving match' for country and context on lookback window. Does not significantly improve 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?

Description clearly states it retrieves most recently published government procurement releases across multiple OCDS publishers, newest first. It mentions specific countries and contrasts with a 'just came out' view, distinguishing it from sibling tools like oc_tender_search which likely supports broader search.

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

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

States optional filtering by country and lookback window. Provides clear context that this tool is for recent releases, but does not explicitly exclude cases where alternative tools (e.g., oc_tender_search) would be more appropriate. Lacks explicit 'when not to use' guidance.

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

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

Annotations already declare read-only, open-world, and idempotent behavior, lowering the burden. The description adds valuable context: data is refreshed weekly, results are deduplicated per contracting process (latest release), and the tool covers specific publishers. This goes beyond the annotation basics, though it doesn't mention pagination or rate limits.

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 substantial but well-organized: purpose, scope, query behavior, filters, return semantics, data refresh, and cross-reference. Each sentence carries unique information without redundancy, making it efficient despite the length.

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

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

For a tool with 7 parameters and no output schema, the description covers the essential return structure (one row per process with buyer, value, method, deadlines, awards), data source freshness, and country coverage. It also points to oc_coverage for freshness verification, making the set of instructions self-sufficient.

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

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

Schema coverage is 100%, providing baseline semantic clarity. The description enhances this by explaining the free-text query matches title, buyer, and description, and clarifies the meaning of min_value as a tender value floor. It also pre-validates the country list and category values, adding practical guidance 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 searches international public procurement data under the OCDS standard, specifying exact content (tenders, notices, awards) and geographic scope. This distinguishes it from siblings like oc_coverage or oc_recent by focusing on search rather than coverage or recent 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 recommends using oc_coverage first to check data freshness and country availability, providing clear guidance on when to use this tool relative to a sibling. It also describes the query and filter capabilities, implying the tool is appropriate for targeted searches across multiple publishers.

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 are all false (readOnly, idempotent, destructive), so the description carries the burden of disclosing behavior. It explains the claim_token mechanism, rate limiting ('Rate-limited to 5 per identifier per day'), that it's free, and how the team uses feedback. This is substantial behavioral context beyond the annotations and no contradiction exists.

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

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

Although longer than typical descriptions, every sentence earns its place. It is front-loaded with purpose, then systematically covers usage, scope exclusions, mechanics, and policies. No redundancy; the length is justified by the density of actionable information.

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

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

The tool has no output schema and sparse annotations, so description completeness is critical. The description fully covers what happens when filing (returns claim_token), how to follow up, rate limits, scope, and content guidance. It is complete for a feedback tool's context.

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

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

Schema coverage is 100% with parameter descriptions, so baseline is 3. The description adds extra value over the schema by explaining message quality ('don't paste the end-user's prompt', 'be specific') and the claim_token usage with a concrete example (pipeworx_feedback({claim_token:"pwfb_…"})). This exceeds baseline, earning a 4.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the action (send feedback) and the resource (Pipeworx tools), and distinguishes it from sibling research/query tools by focusing on feedback for Pipeworx-specific issues.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This fully differentiates from alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable details: data source (CF analytics-engine), no PII, caching behavior (5min-1h). 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?

Well-structured with bullet points. Every sentence adds value: return type, use cases, data source, caching. 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?

Despite no output schema, the description explains what is returned (top tools, packs, call volume). Also covers data provenance and caching. Fully sufficient for agent understanding.

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 described in schema with enum. Description adds semantic guidance on how window length affects results (hot vs steady-state), going 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 specifies exactly what the tool returns (top tools, packs, call volume) over a window, with a clear verb-resource combination. It distinguishes from siblings by focusing on aggregate trending rather than individual queries.

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

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

Three explicit use cases are provided (discovering hot sources, confirming popular tool, aligning needs). While no direct exclusions or alternatives are mentioned, the context is clear enough for appropriate selection.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral details: partition check threshold, Jaccard similarity anchor, placeholder filter, fill check against CLOB depth, return structure. No contradictions.

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

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

The description is long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is front-loaded with the main purpose. Every sentence adds value, though slightly verbose.

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

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

Given the tool's complexity (arbitrage detection with multiple modes, fill check, thresholds), the description covers edge cases like placeholder filtering, similarity checks, and book depth. No output schema, but return fields are well described.

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%. Description adds meaning for both event (slug or URL, single-event mode) and topic (seed question, cross-event scanning), plus explains default behavior without args.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between two modes (event vs topic) and the default no-args scan, making the purpose specific and 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?

Explicit guidance is given: no args for trending scan, event for specific market, topic for cross-event. It also explains when not to trade (if fill check shows no realizable edge). Compares to sibling polymarket_fill_risk.

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

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

The description extensively discloses behavioral traits beyond annotations: caching (1h KV), internal model families, response structure with diagnostics, edge calculations, slippage assumptions, filtering knobs, and Fed bet exclusion reasoning. This adds significant value over readOnlyHint and idempotentHint annotations.

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

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

The description is long but well-structured: purpose first, then segments, response fields, knobs, diagnostics. Every sentence adds value for such a complex tool. It could be slightly more concise, but the density is justified by 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?

Despite no output schema, the description fully explains the response structure (by_segment, fed_candidates, diagnostics), edge metrics, caching, and empty segment reasoning. It covers all aspects an agent needs to understand the tool's behavior and output, making it 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 coverage is 100%, so baseline is 3. The description adds meaning beyond schema for several parameters, e.g., explaining slippage_pp with context about Polymarket's fee structure and typical spreads, and detailing min_partition_leg_kelly vs min_kelly differentiation. Some parameter descriptions in schema are already clear, so overall score is 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 scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the verb (scan, return), resource (Polymarket markets), and purpose (discover betting opportunities). This distinguishes it from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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 avoids paging hundreds of markets, giving clear context. However, it does not explicitly mention when not to use it or name alternative tools, though the purpose is sufficiently clear for an agent to infer usage.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds significant behavioral context: it reads from daily snapshots with a 60-day TTL, decay numbers come from daily closes (not intraday), and response details like expired opportunities and snapshot gaps. 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 well-structured with sections for ARGS, RESPONSE, and LIMITS, front-loading the main purpose. While lengthy, every sentence adds value and justifies its length given the tool's complexity. Minor room for trimming but overall 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?

Despite no output schema, the description provides a detailed breakdown of response fields (tracked[], expired[], snapshot_dates[]) with explanations of trend, decay, lifespan, and gaps. It also covers limitations (60-day TTL, snapshotting start). This makes the tool fully understandable 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?

Both parameters have descriptions in the schema (100% coverage). The description adds meaning by explaining the lookback default (14), max (30 vs schema clamp 2-30), and window family examples (24hr, 1wk, 1mo). This adds context beyond the schema, helping agents understand how to use the parameters effectively.

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 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges, which likely provide raw snapshots, by focusing on time-series analysis and trend computation.

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

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

The description implies usage for analyzing edge persistence and decay over time, contrasting with raw snapshot retrieval (polymarket_edges). However, it does not explicitly state when not to use or list alternatives, though the context from sibling names provides some 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 indicate non-destructive, idempotent, safe read behavior. The description adds valuable behavioral context: it walks the order book, returns detailed fills and verdicts, and warns about risks like thin books and unhedged directional exposure. 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 detailed but every sentence serves a purpose: defining modes, parameters, return values, and risks. It is front-loaded with the main purpose. While somewhat dense, it remains clear for the complexity of the tool.

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

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

Given no output schema, the description fully enumerates all return fields (e.g., top_of_book, vwap_fill_price, verdict) and explains basket-mode specifics (thin_legs, forced_directional_risk). It also includes risk context about partial fills. This provides sufficient information for an agent to decide when to use the tool and what to expect.

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

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

Schema description coverage is 100%, but the description adds extra meaning: it explains side defaults (auto for basket), size_usd interpretation (max spend vs target proceeds), and clamp range (10–1,000,000) not present in schema. This adds value beyond the schema alone.

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

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

The description clearly states it checks realizable-vs-theoretical edge against live CLOB order-book depth, with explicit single-market and basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by advising use before acting on their signals, ensuring no confusion.

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

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

The description explicitly states when to use this tool: before any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above $500. It also warns against using it in cases of partial basket fills leading to unhedged positions, providing clear when-not conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds rich behavioral context: compatibility_warning scenarios (non-equivalent bet shapes, semantically unrelated events), temporal_alignment, and skipped_cross counters. 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 verbose but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds information, but it could be more concise. The length is justified by the complexity of the tool.

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

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

Given the tool has 3 parameters, no output schema, and complex behavior, the description is exceptionally thorough. It covers response format, safety fields, edge cases, and temporal alignment, ensuring the agent can use it correctly without additional context.

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 listing all 10 topic shortcuts and explaining the explicit parameters' purpose (overrides, custom pairings). This goes beyond the schema's enums and 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It provides specific details about modes and output, distinguishing 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 explains two modes (topic shortcuts and explicit tickers) and explicitly warns that pre-mapped topics often return compatibility_warning, guiding the agent to not rely on them. It stops short of naming specific alternative tools but provides sufficient context for when to use each mode.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. Description adds valuable context: scoping to identifier, dual behavior (retrieve vs list), and pairing with remember/forget. No contradictions.

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

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

Three sentences, no wasted words. Main action stated first, then usage context, then pairing. 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?

Given no output schema, description adequately explains return behavior (value or list of keys). Also mentions scoping and pairing. For a simple tool, this is complete.

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

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

Schema covers key parameter fully. Description adds crucial info: omit key to list all, and explains what the key retrieves. Adds value beyond schema.

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

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

Clearly states 'Retrieve a value' or 'list all saved keys', specifies the resource (saved values via remember), and distinguishes from siblings (remember, forget). Verb+resource+scope fully 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?

Explicitly tells when to use: to look up previously stored context without re-deriving. Mentions scoping to identifier. Names sibling tools (remember, forget) but doesn't explicitly say when not to use alternatives. Still clear and helpful.

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

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

Annotations provide readOnlyHint, idempotentHint, destructiveHint. Description adds key behavioral trait: setting mark_read:true flags events as read, changing state of persisted feed. It also mentions poll suitability and alternative endpoint, going beyond annotations.

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

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

Description is 5 sentences covering purpose, return format, filters, mark_read behavior, and polling info. It is mostly concise but could be slightly more structured; still 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?

For a read tool without output schema, description adequately explains return fields and core behavior. It mentions alternative access method, which adds completeness. Some details like pagination are implied via limit parameter but not explicitly stated.

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

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

Schema coverage is 100% with descriptions. Description adds value by explaining behavior of mark_read (flag returned events read so next call shows only newer ones), default limit, and suggesting filter usage (e.g., 'sec_8k').

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

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

The description states 'Pull fired events from your subscription feed' with specific verb and resource. It details return fields (source, citation_uri, raw event payload) and filter options, clearly distinguishing from sibling tools like list_subscriptions which manage subscriptions.

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

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

The description explains when to use (pipeline alerts from a subscription feed) and notes that polling works fine, with an alternative endpoint for scripts. It doesn't explicitly state when not to use, but the context is clear.

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

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

Annotations already declare read-only, idempotent, open-world. Description adds detail: fans out to SEC, GDELT/GNews, USPTO; explains soft-fail for patents; mentions return structure with citations. 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?

Description is a bit long but every sentence adds value. Front-loaded with example queries. Well-structured but could be slightly more concise.

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 aspects: parameters, multiple sources, fallback, return format (changes grouped by source, count, citation URIs). No output schema needed as description suffices.

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

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

Schema coverage 100% but description adds value: explains 'since' formats (ISO date, relative shorthand like '7d'), suggests typical window ('30d'), clarifies 'value' accepts ticker or CIK.

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

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

Clearly states it provides a change feed for a company in a time window, with specific example queries. Distinguishes from sibling 'entity_profile' which is for 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 tells when to use (recent changes) and when not (use entity_profile for static profile). Provides example queries and explains fallback behavior.

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

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

Discloses behavior beyond annotations: scoping by identifier, persistence duration (persistent for authenticated, 24h for anonymous), and the pair/forget relationship. 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 purpose, then usage, then details. Every sentence adds value with no fluff.

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

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

Covers purpose, usage, persistence, pairing, and scoping. No output schema needed; for a simple key-value store tool, all essential information is present.

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

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

Schema already describes both parameters comprehensively (100% coverage). Description adds context with examples and notes scoping, providing marginal additional 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 states the tool saves data for reuse across sessions, specifying key-value pair storage scoped by identifier. Distinguishes from sibling tools 'recall' and 'forget' by mentioning 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 says when to use ('when you discover something worth carrying forward') and provides context on persistence (authenticated vs. anonymous). Suggests pairing with recall and forget.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses internal cascading through multiple lookup endpoints, auto-disambiguation, and the specific citation URIs returned. This adds meaningful behavioral context not visible in annotations.

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

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

The description is a bit long but well-structured, front-loaded with recognizable query examples and a clear directive 'Use FIRST'. Each sentence adds valuable context (supported types, output fields, citation URIs) without unnecessary 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?

Despite having no output schema, the description fully explains what is returned for each entity type (ticker, CIK, RxCUI, citation URIs) and the input accepted. It covers purpose, usage, behavior, and parameters, making it self-sufficient for an agent.

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

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

The schema already documents both parameters with 100% coverage. The description mostly restates examples already present in the schema (e.g., AAPL, CIK) and adds no fundamentally new parameter semantics, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical/official identifier, providing specific examples ('ticker for...', 'CIK for...'). It sets it apart from sibling tools by emphasizing it maps names to IDs that other tools require, making its purpose unmistakable.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups. This provides strong when-to-use guidance and implies it should be prioritized over multiple alternative steps.

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 explains the tool probes each entity with ai_visibility_check, ranks results, and returns scores. This adds behavioral context beyond the annotations (readOnly, idempotent). It does not contradict annotations. Discloses that multiple probes are made, which is useful for agent planning.

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 5 sentences, concise, and front-loaded with the primary purpose. Each sentence adds value. Could be slightly tighter but overall efficient. No unnecessary 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 the return format (ranked list with score, confidence, signal density) and the process (probes each entity). Covers inputs and behavior sufficiently. Does not mention error handling or rate limits, but given the simplicity, it is adequately complete.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds extra semantics: entities array first entry is subject, size 2-8, and context applies to every probe. This goes beyond what the schema provides, enhancing understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using specific verbs like 'probes', 'ranks', 'surfaces'. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying it calls ai_visibility_check internally and focuses on competitive 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 gives an explicit use case ('competitive AI-marketing audits') and an example question. It implies when to use (comparing multiple brands) but does not explicitly state when not to use or mention alternatives like compare_entities. Slightly lacking exclusion guidance.

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

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

Annotations already declare idempotent, read-only, open-world behavior. The description adds critical behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and the failed source will be listed in 'sources_failed'. 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 packed with valuable information in a structured way, starting with the core purpose and then adding usage guidance, behavioral details, and limitations. Every sentence contributes meaningfully, and there is no redundancy 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 the tool's complexity (multiple data sources, partial failures, version defaults), the description covers all necessary aspects: purpose, usage, behavior, return format, and ecosystem limitations. It is fully self-contained and anticipates common agent questions.

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

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

Schema description coverage is 100%, so the parameter descriptions in the schema are already complete. The tool's description does not add new semantic information beyond what is provided in the schema, maintaining the baseline score of 3.

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

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

The description clearly defines the tool as a composite check for assessing npm packages, combining data from deps.dev and bundlephobia. It uses specific verbs ('scan', 'check') and explicitly distinguishes its scope from siblings by noting that other ecosystems are handled by different tools.

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

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

The description explicitly states when to use this tool: whenever an agent asks about safety, popularity, size, or cost of adding an npm package. It also clearly notes the limitation to npm ecosystem v1 and directs users to alternative tools for other package managers.

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 readOnly/idempotent annotations, it discloses truncation at 200K chars with flag, embedding model (BGE-base-en), windowing (500-char overlapping, cosine similarity), and offset output—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?

Several sentences, but each adds unique value (purpose, usage, pairing, technical detail, limit). Front-loaded with core action; could trim minor redundancy but still 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?

Covers purpose, when-to-use, technical behavior, constraints, and output characteristics (passages with offsets and scores) despite no output schema. Sufficient for an agent to invoke correctly.

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

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

Schema covers all 3 parameters (100% coverage). Description adds practical context: text max length, limit default and range, query style with examples, exceeding mere schema labels.

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?

Describes a specific verb-resource pair ('semantic search INSIDE a fetched record') with concrete examples (SEC 10-K, article) and contrasts with sibling ask_pipeworx_grounded.

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

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

Explicitly states when to use (record too big for prompt), why it's beneficial (saves context, returns only relevant passages with offsets), and pairs with an alternative 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?

The description adds significant behavioral context beyond annotations: it explains that subscriptions require authentication, lists supported types with parameters, details delivery channels with constraints (SMS cap, webhook auto-disable), and notes that the webhook secret is returned once. 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 well-structured and front-loaded with the core purpose. While it is somewhat lengthy, each sentence adds valuable information. Minor improvements could be made by grouping related details more succinctly, but overall it is 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?

Given the complexity of the tool (3 params, nested objects, multiple types, delivery channels) and no output schema, the description is thorough. It covers return value, prerequisites, type-specific parameters, delivery constraints, and webhook signing. No gaps are apparent.

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 rich semantic detail for each parameter. For type, it enumerates subtypes and gives examples. For params, it provides type-specific filter structures. For delivery, it explains each field with constraints and behavior (verification, caps, signing). This significantly enhances understanding beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It uses specific verbs and resources, and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context on when to use the tool (live-data event stream), prerequisites (Pipeworx OAuth account), and limitations (anonymous + BYO cannot persist). It also enumerates supported types and delivery channels. It does not explicitly mention when not to use or alternatives, but the context is sufficient.

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

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

Annotations already indicate readOnly, idempotent, non-destructive, openWorld. The description adds what the output contains (category-bucketed questions with tool+argument shapes) and that it teaches meta-tool invocation, which is 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?

Well-structured, starting with trigger phrases, then purpose, output description, and usage. Every sentence adds value; no redundancy. Front-loaded with key information.

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

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

Despite no output schema, the description fully explains the output format and use case. With rich annotations and clear parameter info, the description is complete for 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 covers 100% of parameters (single optional 'topic'). Description repeats the categories and adds context that topic focuses the output, but still enriches understanding beyond the schema baseline.

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

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

The description clearly states the tool is the onboarding entry point, returning category-bucketed example questions from the live catalog. It lists trigger phrases and distinguishes itself from siblings by positioning as the first tool to use when the agent doesn't know what to ask.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do.' Provides clear usage instructions: call with no arguments for full spread or pass 'topic' to focus. Implies alternatives like ask_pipeworx after learning meta-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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds valuable context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' 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, front-loaded with the main action ('Cancel a subscription by id.'), 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 explains the outcome (deactivation, preservation of historical events) and covers the single required parameter. No output schema needed as behavior is fully described.

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 'id'. The description mentions 'by id' and 'returned by subscribe', which reinforces the schema but does not add significant new meaning beyond it.

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

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

The description states 'Cancel a subscription by id.' with a specific verb and resource, and it distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. It lacks explicit exclusions but is still clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and not destructive. The description adds significant value by explaining that it replaces 4–6 sequential calls, details the verdict types (confirmed, approximately_correct, etc.), and describes the return format with citation and reasoning. It also explains the fallback mechanism, which annotations do not cover.

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

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

The description is relatively long but packed with valuable information. It front-loads typical usage patterns and is well-structured with separate sections for the two paths. A slightly more concise version could be achieved, but the content is not wasteful.

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

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

Given the complexity of the tool (two paths, multiple verdict types, citation) and the absence of an output schema, the description thoroughly explains return values (verdict, actual value with citation, reasoning) and the internal routing logic. It is complete enough for an AI agent to understand usage without external documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for tolerance_pct, explaining its purpose for hallucination detection and default behavior, which goes beyond the schema description. It does not repeat the claim parameter's 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 tool does natural-language claim verification against authoritative sources, distinguishing it from siblings like ask_pipeworx or deep_research. It specifies the two paths (SEC EDGAR for financial claims, grounded pipeline for others) and lists typical usage phrases.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It explains the two internal paths, providing context on when each is used, though it does not explicitly mention alternatives or when not to use.

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