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 the readOnly/openWorld/idempotent annotations, the description discloses key behaviors: it routes across 5,724 tools and 1,497 sources, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and makes one fast call. It also indirectly signals that verbatim evidence and confidence are not guaranteed here by directing those needs to ask_pipeworx_grounded, which is valuable behavioral context.

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

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

Though lengthy, every sentence earns its place: scope, source routing, examples, default status, and alternative tools are all decision-relevant. The structure front-loads the most important directive ('PREFER OVER WEB SEARCH') and then logically moves from general usage to specific routing examples to escalation paths.

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 natural-language query tool with no output schema, the description is remarkably complete: it covers input expectations, scope, source coverage, return format (structured answer with citation URIs), performance characteristics, tier availability, and clear escalation paths to sibling tools. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents the 'question' parameter and its aliases clearly. The description adds useful examples of valid queries but does not add new parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific purpose: answering factual questions about real-world entities, events, and numbers by routing to authoritative sources and returning structured answers with citations. It also explicitly distinguishes itself from web search, ask_pipeworx_grounded, and deep_research, making sibling differentiation immediate and clear.

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

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

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when-not-to-use alternatives ('for a hallucination-resistant single answer use ask_pipeworx_grounded; for broad/multi-part questions use deep_research'). It even covers breaking-news routing and notes that web search may also answer these questions, which removes ambiguity about tool 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?

The annotations already cover read-only, open-world, idempotent, and non-destructive behavior, so the description does not need to restate those. It adds substantial context: candidate routing improvements may be enabled live, no candidate is currently active as of a specific date, current behavior matches ask_pipeworx exactly, and it 'Falls back to nothing' because it is a full working router. This is candid and materially reduces uncertainty.

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

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

The description is front-loaded with the beta identity and the key fact that it is identical to ask_pipeworx. The four sentences each add useful context: beta status, current candidate state, usage rule, and no-fallback guarantee. Minor redundancy across 'identical router', 'matches ask_pipeworx exactly', and 'Use it exactly like ask_pipeworx' prevents a 5.

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

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

For a high-complexity, no-output-schema router, the description covers its purpose, current behavior, experimental relationship to the stable router, and the fact that it is fully functional. It does not independently describe the response format, but 'same response shape' points to ask_pipeworx, which is likely sufficient given sibling context. It could be stronger with an explicit statement about expected response content.

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 documents the required 'question' parameter plus five aliases. The description only says 'same arguments' as ask_pipeworx, which adds no new semantic value beyond the schema. Baseline 3 is appropriate because the schema already carries the parameter burden.

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

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

The description identifies the tool as the beta version of ask_pipeworx and calls it a 'universal router' over 5,724 tools with the same arguments and response shape. It clearly distinguishes itself from the stable ask_pipeworx sibling as the experimental edge. However, it does not explicitly describe the end-user outcome of routing (e.g., 'answers questions by selecting among tools'), leaving some inference to the agent.

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

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

It explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide what merges. This gives clear when-to-use context. It does not explicitly say to prefer ask_pipeworx for stable or production use, nor does it mention when to choose ask_pipeworx_grounded instead.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds substantial context beyond those hints: refusal semantics with specific refusal_reason enum values, verbatim evidence extraction, source and fetched_at in output, and the extra LLM call cost. No contradiction with annotations.

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

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

The description is dense yet well-organized: purpose, routing mechanism, return contract, refusal cases, usage guidance, and cost tradeoff all in a compact paragraph. Information is front-loaded and every clause contributes actionable detail.

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

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

Given the tool's complexity, lack of output schema, and the need for agents to assess when grounded answers are required, the description covers the full contract: success response shape, explicit refusal reasons, routing behavior, and cost implications. Nothing essential is missing.

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

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

Schema description coverage is 100% and all six parameters are aliases for the same natural-language question, which the schema already documents clearly. The description reinforces that the input is a question but does not add parameter-level meaning beyond what the schema provides.

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

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

Description states a specific verb (answer) and resource (routed through Pipeworx tool selection), and explicitly differentiates from ask_pipeworx by being hallucination-resistant and grounded in tool results. Even the name and title support the unique value proposition.

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 ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), lists example high-stakes domains, and notes the extra LLM call cost as a tradeoff. No ambiguity remains for the agent.

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?

Adds substantial behavior beyond annotations: account/paid-plan requirements, 15-90s latency, findings-packet shape, gaps[] never invented, contradictions[] for standard/thorough, semantic excerpting rather than head-truncation, and citation_uri only when resolvable. None of this is in the annotations, and nothing contradicts readOnlyHint, idempotentHint, or openWorldHint.

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: access constraints, alternatives, mechanics, return contract, latency, and failure behavior are all operationally relevant. It is front-loaded with the account requirement and sibling routing before deeper mechanics, and uses dense punctuation to keep it scannable.

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

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

With no output schema, the description carries the full return contract: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, hop field, gaps[], and contradictions[]. It also covers auth, pricing, latency, and boundary conditions, making it complete enough for an agent to invoke and interpret correctly.

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

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

The schema already documents question and depth at 100% coverage, so the baseline is 3. The description adds meaning for depth by explaining gap recovery and the thorough follow-up pass, and clarifies that broad/multi-part questions are acceptable; it does not materially extend the question parameter, hence not a 5.

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

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

States a precise capability: grounded multi-source structured research across 1,497 data sources in one call, with facet decomposition and parallel routing. It explicitly contrasts itself with open-web search and with ask_pipeworx, making its role unmistakable among the sibling tools.

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

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

Gives explicit when-to-use guidance with named alternatives: use ask_pipeworx for single lookups, for breaking/current-news topics, and when not signed in. It also provides concrete example questions for deep_research, leaving no ambiguity about the intended use case.

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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context by specifying the data returned (publisher, counts, freshness), the set of 18 countries, and the recommended ordering. It does not introduce contradictions or omit significant behavioral details.

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

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

The description is a single, informative sentence that front-loads the purpose and provides a useful country list. While the list is long, it is directly relevant to the tool's scope. It is not overly verbose and every part contributes to understanding 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's simplicity (no parameters, no output schema) and the presence of comprehensive annotations, the description is complete. It explains what data is returned, the geographic scope, and when to call the tool, leaving no critical 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?

The tool has zero parameters, so the schema and description do not need to explain parameter semantics. The baseline for no parameters is 4, and the description appropriately avoids over-explaining, making it easy to invoke.

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: it reports which open-contracting procurement data is available, including per-country publisher, counts, and freshness. It distinguishes itself from siblings by explicitly saying 'Call this first' to learn data availability before relying on it, making it a unique precursor tool.

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: 'Call this first to learn... before relying on it.' It implies the tool should be used before querying specific data, but does not name alternatives or when-not-to-use scenarios. This is clear context, though not fully exhaustive.

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 cover read-only and non-destructive behavior. The description adds behavioral detail beyond them: results are ordered chronologically, include all releases, and reveal the tender-award-contract progression. This helps an agent set expectations about the shape and ordering of the response.

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 filler, main purpose front-loaded, and each sentence contributes a distinct fact (input, output, use case). Ideal size for a simple read 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 low complexity (one param, no output schema), the description covers all essential information: how to obtain the input, what the output contains, ordering, and when to use it. The annotations cover safety, leaving no critical 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 coverage is 100% (ocid is described), but the description adds provenance ('as returned by oc_tender_search / oc_recent') and explains the role of OCID in identifying a single process, which is meaningful for the one parameter.

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

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

Description states a specific verb-resource pair ('returns every OCDS release... for a single contracting process') and identifies the key input (OCID). It differentiates from sibling search tools by emphasizing a single-process pull versus oc_tender_search/oc_recent, and clearly explains the output value.

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 when to use by saying 'Use it to trace how a specific government tender played out' and points to oc_tender_search/oc_recent as the source of the OCID, signaling the preceding step. It lacks an explicit exclusion statement (e.g., 'do not use for listing'), but the context is clear enough.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the burden on the description is lower. The description adds relevant behavioral context beyond those annotations: results come from a weekly-refreshed feed, are ordered newest first, and represent a snapshot of recent releases rather than a live or exhaustive search. This gives the agent an accurate sense of data freshness and scope.

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 main purpose is front-loaded and the language is mostly efficient, but the long parenthetical list of countries largely duplicates information already present in the country parameter's enum. The final sentence also somewhat restates the first sentence's purpose, though it adds the weekly-refresh context. It is reasonably concise but not tightly optimized.

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 filtered-list tool with three optional parameters, no output schema, and safety annotations, the description plus schema provide enough context for an agent to select and invoke the tool correctly. It names the data source, scope, refresh cadence, sorting, and filtering options. It does not describe the exact output structure, but that is not essential given the tool's straightforward nature.

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 parameters are already well documented. The description adds a little value by mapping 'adjust the lookback window' to the days parameter and 'filter to one country' to the country parameter, but it does not meaningfully extend the schema's explanations, especially for the limit parameter.

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

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

The description clearly identifies the tool as returning the most recently published government procurement releases, sorted newest first, with optional country and lookback-window filtering. This distinguishes it from sibling tools like oc_tender_search by framing it as the 'what public tenders just came out' view rather than a general search. The only minor blemish is that the country list omits Argentina while the schema includes it, but the core purpose is 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?

The description provides clear context for when to use the tool: when you need recently published tenders or contract awards across OCDS publishers, with optional country and time-window filtering. It does not explicitly name alternatives or state when not to use them, so it stops short of a 5, but the intended use case is concrete and easy to apply.

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 carry readOnly/openWorld/idempotent hints, and the description adds substantial non-obvious behavior: the query is auto-translated 'alongside its equivalents in the language of the country you filter to,' the response 'echoes every spelling it searched in query_match,' and results are deduplicated to 'one row per contracting process (latest release).' It also discloses the weekly refresh cadence, giving the agent an accurate staleness expectation.

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: purpose, geographic scope, multilingual behavior, filter list, return shape, freshness, and sibling guidance are each covered once with no filler. The core purpose is front-loaded in the first clause, and the most decision-relevant facts (coverage, freshness, alternative tool) come last in a natural order.

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

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

With no output schema, the description compensates by stating exactly what is returned: 'One row per contracting process (latest release) with buyer, value, procurement method, deadlines, and award details when present.' For a 7-parameter, all-optional, no-output-schema tool, the description covers selection, invocation, result interpretation, and data caveats — nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by explaining the interaction between query and country (language-equivalent searching) and clarifying min_value as a 'tender value floor' and days as 'recently released.' Most filter names are reiterated rather than deepened, but the multilingual query behavior is genuinely additive semantics.

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

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

The description opens with a specific verb and resource — 'Search international public procurement — government tenders, contract notices, and contract awards published under the OCDS Open Contracting Data Standard' — and narrows scope via the publisher list and countries covered. It also distinguishes itself from a sibling by telling the agent to 'Use oc_coverage first,' so an agent can tell it apart from related OCDS tools.

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

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

The description gives clear context for when to call it (querying tenders/awards with filters across 18 publishers) and explicitly routes the agent to a sibling: 'Use oc_coverage first to see which countries have data and how fresh it is.' It does not, however, state exclusions or mention sibling tools oc_process_history and oc_recent, so it stops short of covering the full when/when-not picture.

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?

Beyond the read-only and idempotent annotations, the description discloses matching behavior, compatibility warning codes, fee handling as gross rather than net, skipped leg categories, and the exact meaning of null temporal_alignment. This leaves little room for an agent to misinterpret side effects or output semantics.

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 structured in labeled blocks (modes, response, safety fields, fees, skipped counters) and front-loads the core purpose. Some caveats are repeated across the warning-code section and the flag descriptions, so a small amount of tightening would be possible.

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?

Because there is no output schema, the description fully carries the burden of explaining the return shape: leg-by-leg prices, top_spreads_pp sign convention, compatibility_warning and codes, temporal_alignment behavior, fees_note, and skipped counters. For a three-parameter read-only 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 coverage is complete for all three parameters, and the description adds meaningful interaction details: topic enumerates the ten shortcuts, the explicit ticker and slug parameters override the mapped sides, and either mode still runs the identical token-overlap matcher.

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 leads with the exact resource: the cross-venue spread between Kalshi and Polymarket for the same resolving question. It then details two modes and the matched output, and the cross-venue framing is specific enough to distinguish it from the Polymarket-focused sibling tools.

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

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

It gives explicit mode guidance: use one of the ten topic shortcuts, or provide kalshi_event_ticker plus polymarket_event_slug for custom pairings, and notes that both modes run the same matcher. It also sets expectations that most pre-mapped topics return compatibility warnings and that pre-mapped is not tradeable, but it stops short of naming sibling tools as 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 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: it cascades through multiple lookup endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, explicitly lists unresolved identifiers under 'unresolved' rather than omitting them, and asserts nothing when a name matches multiple instruments (returning figi_candidates). It also explains that it resolves non-equity instruments like bonds, which is a non-obvious behavior. This goes well beyond the annotation hints.

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 dense. It front-loads the usage directive ('Use FIRST whenever you have a name but need an ID') and then organizes information by supported types. While it is a wall of text, every sentence carries operational value—examples, edge cases, degradation behavior, and input format warnings. It could be slightly trimmed (e.g., the CID citation URL might be less critical), but it is structured logically and earns its length.

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

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

Despite no output schema, the description covers return behavior comprehensively: what identifiers are returned (CIK, ticker, LEI, FIGI), how ambiguous names are handled (figi_candidates), how unresolved identifiers are presented (under 'unresolved'), and graceful degradation if upstream sources fail. It also addresses non-US issuers and non-equity securities. For a tool with two types and multiple internal sources, the description leaves no significant gap an agent would need to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description significantly enhances parameter understanding: it explains that for company input you can pass ticker, CIK, ISIN, or name, and specifically warns about bonds (pass the issuer exactly as printed, avoid trailing security-class words). It also clarifies the drug type accepts brand or generic names. This is crucial operational guidance that prevents common errors and goes beyond the schema's basic field descriptions.

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

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

The description states a specific verb ('resolve') and a clear resource (user-spoken names to canonical identifiers). It provides concrete query examples ('What's the ticker for...', 'find the CIK for...') and explicitly frames the tool as the go-to for name-to-ID conversion. It distinguishes itself from sibling tools implicitly by covering multiple identifier types in one call, and the purpose is unambiguous.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is a direct when-to-use directive. It also provides guidance on input formats (e.g., passing exactly the issuer name for bonds, not the full noun phrase) and explains what to expect for ambiguous matches (returns figi_candidates rather than asserting). It clarifies that it replaces 2-3 manual lookups, reinforcing its role versus other tools.

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

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

Description 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?

Despite annotations already declaring readOnlyHint and idempotentHint, the description adds critical caveats: could_not_verify means the check did not happen and must not be treated as evidence, while unsupported means no source covers it. It also discloses routing behavior and the percent-delta math, going well beyond the annotation surface.

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

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

The description is dense but every sentence earns its place: examples, usage, routing, verdict list, caller warning, and efficiency note. It is front-loaded with the most important information and remains scannable despite its length.

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

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

Given no output schema, the description carries the burden of explaining return values, and it does: verdict options, actual value with citation, reasoning, and error semantics. It also covers two distinct execution paths and edge cases (could_not_verify vs unsupported), making it 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?

Input schema already documents both parameters, but the description adds meaningful extra semantics: tolerance_pct is described as overriding the wording-implied tolerance, with a range (0.5–50), a default cap at 5, and a use-case hint (set 1–2 for hallucination detection). This enriches what the schema alone provides.

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

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

The description opens with concrete natural-language examples ("Is it true that…", "fact check", "verify the claim that…") then defines the tool as "natural-language claim verification against authoritative sources." It clearly distinguishes itself from siblings by focusing on fact-checking with a specific verdict set, rather than general search or research.

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

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

The description states "Use whenever the agent needs to check whether something a user said is factually correct" and explains the two processing paths (SEC/XBRL for company-financial claims, grounded pipeline for anything else). It does not explicitly name alternative tools or exclusion cases, but the usage context is clear.

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