Unhcr

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

Annotations confirm read-only, idempotent, non-destructive behavior. The description adds that Workers AI is free, Anthropic requires a key and external payment, and the return format includes per-model details and a combined view. No contradictions with annotations.

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

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

The description is a single paragraph of four sentences, no wasted words. It front-loads the key action (probe and score), lists default model, special key requirement, return structure, and use cases. Every sentence earns its place.

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

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

Given 100% schema coverage and no output schema, the description adequately explains all parameters, return structure, and use cases. It could elaborate on the scoring methodology, but the information provided is sufficient for selection and inference.

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

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

All four parameters are described with added context beyond the schema. The description explains that 'entity' is the topic to probe, 'models' lists supported values, '_apiKey' is optional but needed for anthropic, and 'context' disambiguates common names. This adds meaningful guidance.

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 for knowledge about a business/brand/product/topic and scores visibility. It specifies the default model, return fields, and distinguishes among sibling tools by framing use cases like AI-marketing audits and competitive monitoring.

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 lists use cases (AI-marketing audits, brand checks, competitive monitoring) and mentions that the default model is free while Anthropic requires a key with BYO billing. However, it does not explicitly state when not to use this tool or directly compare to siblings.

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

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

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive; the description adds that it routes questions, fills arguments, and returns answers with stable citation URIs. This discloses the key externally visible behavior beyond structured hints. Minor details like latency or failure behavior are not covered, but the description carries sufficient behavioral context.

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

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

The description is long but front-loaded with the central preference rule, followed by scope, examples, and explicit sibling routing. It is dense rather than bloated, though there is a minor punctuation/formatting stumble around 'groundedness For'.

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

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

Despite having no output schema, the description tells the agent what to expect ('structured answer with stable pipeworx:// citation URIs') and covers the main alternative tools. It provides enough context for correct invocation of a broad router tool. Edge cases like unsupported question categories could be specified, but they are not essential for typical 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 description coverage is 100%, and the schema already documents 'question' and five aliases with examples. The description adds example phrasings and trigger words, but it does not need to compensate for missing schema information. Baseline 3 is appropriate because the structured schema does the heavy lifting.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and clearly states the tool routes questions to 5,798 tools across 1,517 verified sources and returns structured answers with pipeworx:// citation URIs. This identifies the tool as a router/QA tool and differentiates it from web search and siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'current'), example queries, and clear routing guidance: use ask_pipeworx_grounded for additional groundedness, deep_research for broad multi-part questions, and notes that breaking-news is already handled internally. This is strong when-to-use versus alternative 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 cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: no candidate is currently active so it matches ask_pipeworx exactly, it is a full working router, and it does not fall back to anything.

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

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

The description is compact and front-loaded with the core purpose, then explains current parity with the stable router and gives usage guidance. Each sentence adds value, though the middle sentence about the retired candidate is slightly specific.

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

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

Given that this is a beta variant of an existing tool, the description covers the current experimental state, parity with ask_pipeworx, usage intent, and response shape. There is no output schema, but referencing the sibling's response shape is sufficient because the tool is explicitly identical.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the required 'question' field. The description does not add parameter-level detail, but the schema already provides complete semantic coverage, so no compensation is needed.

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

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

The description clearly states this is the beta variant of ask_pipeworx: an identical universal router with the same 5,798 tools, arguments, and response shape, but with experimental routing improvements. It differentiates itself from the stable sibling ask_pipeworx and explains its current status.

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

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

The description explicitly tells the agent to use it exactly like ask_pipeworx when the newest routing is desired, and notes that results are compared against the stable router. It does not explicitly say 'use the stable version when you need stability,' but the beta/experimental framing implies that 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?

Beyond the readOnly/idempotent annotations, the description discloses important behaviors: it only uses tool result content, will refuse rather than invent facts, returns a structured refusal_reason, and costs one extra LLM call. This is rich, actionable transparency with no contradiction to 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 fairly long but every sentence carries essential operational information: behavior, return shape, refusal cases, usage context, and cost trade-off. It is front-loaded with the key behavioral distinction and structured so an agent can quickly extract decision-relevant facts.

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

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

With no output schema present, the description fully compensates by specifying the exact success and refusal response shapes, including refusal_reason values. Combined with the usage and cost guidance, an agent has everything needed to call this tool correctly and interpret its results.

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

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

The schema already fully documents the question parameter and its aliases, so the description does not need to add parameter-level detail. The description adds no parameter-specific semantics, but does not need to given 100% schema coverage, meeting the baseline.

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

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

The description clearly states a specific behavior: a hallucination-resistant, grounded answer mode that extracts answers only from tool results. It distinguishes itself from ask_pipeworx by explicitly contrasting the grounded extraction and refusal behavior, so an agent can select it correctly.

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

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

The description gives explicit when-to-use guidance: use when answers will be quoted, cited, or acted on in high-stakes contexts. It also directly says to prefer ask_pipeworx for casual lookups and notes the extra LLM call cost, giving a clear decision rule.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, so the description does not need to repeat safety traits. The description adds minor context about response structure (e.g., response.total.applied is aggregate) but no significant behavioral disclosure 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 efficiently convey the purpose, grouping, row structure, and aggregate. Every sentence earns its place 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?

The description covers the core data and row structure, but does not mention pagination defaults (e.g., page, limit from schema) or explain the year range behavior. However, with good annotations and 100% schema coverage, it is largely adequate for a list tool.

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

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

Schema description coverage is 100%, but the description adds value by explaining that coo/coa use UNHCR 3-letter codes (referencing list_countries) and describing the row fields (procedure_type, app_type, dec_level, applied count) and aggregate, which are not detailed in the schema.

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

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

The description clearly states 'Asylum applications lodged, by year, country of origin (coo) and country of asylum (coa)', which specifies the verb (retrieve/query), the resource (asylum application counts), and the grouping dimensions. This contrasts with sibling 'asylum_decisions', making the tool's purpose distinct.

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?

No explicit guidance is provided on when to use this tool versus alternatives like asylum_decisions. The only reference is 'see list_countries' for codes, which is about input format, not usage context.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: row fields (dec_recognized, etc.) and that response.total aggregates the same 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?

Three sentences, front-loaded with purpose, each sentence adds necessary detail without waste. Examples in schema supplement but description itself is 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?

Given good annotations and full schema coverage, the description is complete for a data retrieval tool. It explains row fields and aggregation, though no output schema 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 covers 100% of parameters with descriptions. The description adds value by explaining that coo/coa take UNHCR 3-letter codes and referencing list_countries, providing context 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 returns 'Decisions on asylum claims, by year, country of origin (coo) and country of asylum (coa)' and specifies the breakdown fields (dec_recognized, etc.). It differentiates from siblings like asylum_applications by focusing on decisions, though not explicitly contrasting.

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?

No explicit when-to-use or when-not-to-use guidance. It implies usage for retrieving asylum decision data and references list_countries for codes, but lacks alternatives or exclusions.

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

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

The description provides extensive behavioral details: market resolution, classification, fan-out to data sources, evidence packet construction, safety checks (low-confidence short-circuit), closed market handling, wide-spread illiquidity flag, and cancellation rule parsing. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and the description adds context beyond them.

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

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

The description is comprehensive but very long (over 1500 words). While the first sentence front-loads the purpose, the rest is a dense block of text. It could benefit from clearer structure (e.g., bullet points or sections) to improve readability. The extensive detail is valuable but not 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?

Given the tool's complexity (multiple classifiers, fan-out examples, response shapes, resolver contract, safety conditions), and the absence of an output schema, the description is remarkably complete. It covers all essential aspects, including edge cases like cancellation rules, news fallbacks, and parent event extraction.

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

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

Schema coverage is 100%. The description adds meaningful information for each parameter: market input examples (slug, URL, question text), depth enum with default behavior, and include_raw with effect on response size. This goes well beyond the schema definitions.

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, with specific inputs (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from siblings by explaining the fan-out mechanism and comprehensive analysis, which is not present in other Polymarket tools like polymarket_edges.

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

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

The description explicitly states when to use the tool ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It also warns about low-confidence resolutions and closed markets, which implicitly advises against use in those cases. However, it does not explicitly mention alternatives or exclusion scenarios for other use cases.

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 behavior. The description adds that off-calendar fiscal years are handled correctly and results are sorted by primary metric, which is useful beyond the annotations.

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

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

The description is verbose but well-structured: starts with natural language triggers, then explains behavior per type, then sorting and return. Each sentence adds value, though it 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?

No output schema, but the description mentions returning paired data and citation URIs. It covers data sources and sorting. Lacks specifics on time range or data recency, but overall sufficient for a comparison 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%. The description enriches both parameters: for 'type', it explains the data source per entity type (SEC EDGAR vs FAERS); for 'values', it clarifies format (tickers/CIKs vs drug names) and constraints (2-5 items).

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

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

The description explicitly states it performs side-by-side comparison of 2-5 companies or drugs, pulling specific financial or adverse-event data. It distinguishes from siblings by stating it replaces 8-15 sequential single-pack lookups, contrasting with tools like entity_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?

Clear trigger phrases ('X vs Y', 'which is bigger') and a directive to prefer over sequential lookups. While it doesn't list alternatives for non-comparison cases, the context is well-defined.

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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description goes far beyond that by disclosing auth requirements, paid tier constraints, parallel decomposition, gap recovery hops, contradictions scanning, citation fetchability guarantees, semantic excerpting behavior, and expected latency ranges. No annotation 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?

The description is long and dense, but nearly every clause earns its place by conveying operational constraints, alternatives, or return behavior. It is front-loaded with the most critical gate (account requirement) and the fallback tool. The structure is somewhat sprawling with many parentheticals, making it less crisp than ideal, but still effective.

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

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

For a two-parameter tool with no output schema, the description thoroughly covers the return packet (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), latency, auth, tool routing, and failure behavior. An agent has enough context to select and invoke the tool correctly without needing the output schema.

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

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

Schema coverage is 100% for both parameters, but the description adds meaningful depth semantics beyond the schema: it explains what each depth level does operationally (quick=single hop, standard=gap recovery + contradictions, thorough=paid iterative chase), and clarifies that the question can be broad and multi-part because decomposition is the point.

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

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

The description names the specific verb and resource: 'grounded multi-source research' across 1,517 structured data sources in one call. It explicitly distinguishes itself from open-web search and from ask_pipeworx for single lookups, making sibling differentiation 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 states explicit when-to-use guidance: best for broad/multi-part questions over structured data, and when not to use it: 'For a single lookup use ask_pipeworx instead.' It also names the alternative for unsigned-in users and notes the paid-tier requirement, providing actionable routing conditions.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns top-N relevant tools with full input schemas and curated examples, ready to call. No contradictions; behavioral details extend annotations.

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

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

The description is concise (~100 words) and well-structured: first sentence states purpose, second lists domains, third explains return format, and final sentence gives usage hint. Every sentence contributes necessary information.

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

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

The description explains return format (tools with schemas and examples) and usage directive, but lacks information on error handling or no-results behavior. Given the tool's discovery nature and annotation support, completeness is adequate.

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

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

Schema description coverage is 100%, but the description adds value by explaining the query parameter accepts multiple aliases (task, q, description, search). This clarifies parameter flexibility beyond the schema's individual 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 explicitly states the tool finds tools by describing data or task, lists many domains, and distinguishes itself from sibling tools by instructing to call it first for browsing options.

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

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

The description provides clear usage context ('Use when you need to browse, search, look up, or discover what tools exist') and a specific directive to call it first. It lacks explicit when-not scenarios but is sufficient for the intended discovery role.

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

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

The description goes far beyond the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing fan-out behavior, soft-fail handling (USPTO sunset May 2025), the meaning of empty returns ('a real "no data", not a bug'), the sources_used/sources_failed mechanism, and the resolved:false path for private companies. It also reveals that an fda_products empty result is expected for non-biologics companies, preventing false-positive interpretation. No contradictions with annotations.

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

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

The description is long, but it is packed with necessary behavioral and return-value detail that an agent needs in the absence of an output schema. It front-loads user phrases and the core directive before diving into output fields. The structure is somewhat run-on — a single dense paragraph with semicolon-separated sections — but every sentence earns its place, so the length is justified.

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

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

Given there is no output schema and the tool fans out across many sources, the description documents each return section (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) and their caveats, plus the success/failure reporting mechanism. It also covers all three input forms and the private-company failure mode. An agent has everything needed to call it correctly and interpret responses 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, but the description adds real value: it gives concrete examples for each accepted value shape, explains that names resolve via SEC EDGAR company-name match, and clarifies that 'type' accepts 'company' or 'ticker' interchangeably. This enriches the schema rather than merely repeating it, though the schema already carries the core definitions.

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 user-phrase examples, then states the exact function: 'full cross-source profile of a US public company in ONE parallel call.' It explicitly distinguishes itself from chaining single-pack lookups and from related siblings like compare_entities and resolve_entity by naming the holistic use case. The verb 'profile' plus the resource scope (US public company across SEC/XBRL/patents/etc.) leaves no ambiguity about what the tool does.

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?

Usage is explicitly conditional: use when the user asks for a holistic view or says 'tell me about X' / 'research Acme', and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also states acceptable inputs (ticker, CIK, company name), the private-company edge behavior, and what 'type' values mean. This is clear when-to-use guidance with no reliance on inference.

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 mark destructiveHint=true. Description adds value by explaining why you'd use it (clear sensitive data) and that it pairs with other tools. No contradiction with annotations; idempotentHint is not elaborated but not contradicted.

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, no wasted words. Front-loaded with the core action. Efficient and to the point.

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 destructive tool with one parameter and no output schema, the description covers purpose, usage, and relationships. No gaps for the intended 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 covers the single parameter 'key' with a description. The tool description does not add new information about the parameter beyond what the schema provides. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the verb ('Delete') and the resource ('previously stored memory by key'). It distinguishes from sibling tools 'remember' (store) and 'recall' (retrieve) by explicitly pairing with 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?

Provides specific scenarios for use: when context is stale, task done, or clearing sensitive data. Implicitly advises against use when memory is still needed. Mentions complementary tools to guide lifecycle.

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 safe (readOnlyHint, idempotentHint, etc.). The description adds behavioral details: fetching the page, extracting title/description/key links, and emitting standard markdown. This goes beyond annotations to explain the exact process.

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

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

The description is concise (3 lines), well-structured, and front-loaded with the tool's primary action. Every sentence adds value, and there is no redundancy or fluff.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description is fully complete. It explains input, output format, and use cases, covering all necessary context for an agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description does not add significant new semantics beyond the schema; it merely reiterates that max_links controls the number of link entries. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for any URL, with a specific verb ('generate') and resource ('llms.txt file'). It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on creating the standard file format.

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

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

The description lists concrete use cases (client's site indexing, personal project drafting, competitor auditing), providing clear guidance on when to use. However, it does not explicitly state when not to use or compare with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds pagination details, field list, and that it is a large list. No contradictions.

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

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

Single, well-organized paragraph that front-loads purpose, then usage, then item fields. Every sentence is informative and efficient.

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

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

With no output schema, description explains each item's fields and pagination behavior completely. Adequate for a reference list 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 covers 100% of parameters with descriptions. Description adds context: 'raise limit or page through' and explains 1-based page and response.maxPages. 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?

The description clearly states it is a reference list of countries/territories tracked by UNHCR, used to map names to codes for other tools. It distinguishes itself from sibling tools by specifying its role in providing codes for coo/coa parameters.

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 map country name to code for filtering in other tools. Mentions pagination behavior. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint=false. Description adds default exclusion of inactive subscriptions and lists return fields, which is useful but not essential 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. Front-loaded with the core purpose, then important 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?

Given the tool's simplicity (one optional parameter, read-only, no output schema needed), the description fully covers what the agent needs: 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% with one optional boolean parameter. Description clarifies default behavior (active only) and purpose of parameter by mentioning 'active' subscriptions, adding value beyond schema.

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

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

Clearly states 'List the caller's active subscriptions' and enumerates return fields. Distinguishes from sibling tools subscribe/unsubscribe by describing its role in review.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', giving concrete when-to-use scenarios.

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, providing no safety or side-effect hints, so the description carries the full burden. It reveals rate limiting ('Rate-limited to 5 per identifier per day'), the anonymous claim_token flow, that feedback is free and doesn't count against quota, and that the team reads digests daily — all valuable behavioral context beyond the schema.

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

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

The description is substantial but every sentence serves a purpose: what it does, when to use, when not to use, how to format feedback, the claim_token flow, rate limit, and cost. It is front-loaded with the core verb and resource, then layers details logically. No fluff or repetition of schema field definitions.

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 and a nested context object, the description must clarify return behavior and usage boundaries. It explains that anonymous filing returns a claim_token and that passing it later returns status/resolution. It covers prerequisites (no account needed), limitations (rate limit), and scope (only this connection's tools). This is complete for the tool's purpose.

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 meaning beyond the schema: it explains how to use claim_token for later lookup ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), and constrains message content ('describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). The type enum is also mapped to concrete scenarios.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx by focusing on reporting issues about the Pipeworx connection's own tools.

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

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

Provides explicit when-to-use guidance for each feedback category and an unequivocal exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' Also gives a decision heuristic for identifying Pipeworx tools ('Pipeworx tool names are the ones this connection lists').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value beyond these by noting the data source (CF analytics-engine), no PII, and caching behavior (5min-1h), providing useful behavioral context.

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

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

The description is concise (few sentences) and front-loaded with the main result. Every sentence adds utility, including the use cases and data details. No wasted words.

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

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

Given no output schema, the description still explains the return content (top tools, top packs, call volume, with (pack, tool, count) tuples). It mentions caching and data provenance, making it sufficiently complete for a simple read-only 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% with one parameter (window) and enum. The description adds meaning by explaining that shorter windows surface hotness and longer show steady-state demand, providing semantic guidance beyond the enum.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window. It uses specific verbs ('Returns') and resources, and distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on trending signals.

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

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

Three explicit use cases are listed (discovering hot data sources, confirming canonical choice, checking alignment). It does not explicitly state when not to use, but the positive guidance is clear and distinguishes 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?

Discloses extensive behavioral details beyond annotations: trending scan scope (top ~200 markets), mode-specific logic (date-axis ordering, partition check, Jaccard similarity threshold, placeholder filtering), fill check against live CLOB depth, and conditions for not trading. No contradiction with annotations.

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

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

Description is comprehensive and well-organized, starting with overall purpose then detailing each mode. Every sentence adds value, though length is justified by tool complexity. Slight room for more structured formatting.

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 lack of output schema, description fully explains response structure (opportunities array with fields, partition_check object in event mode) and includes fill check safety guidance. Covers all aspects 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?

Schema coverage is 100% but description adds substantial meaning: distinguishes event (single-event mode) vs topic (cross-event mode), provides concrete examples of valid slugs and seed questions, explains recommended usage for event, and details each mode's processing.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by detailing unique mechanisms and explicitly referencing the fill check.

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

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

Provides explicit when-to-use guidance for three modes: no args for trending scan, event for a specific market (recommended), and topic for cross-event scanning. Includes examples of valid inputs and explains cross-event mode catches patterns single-event misses.

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 rich behavioral details: caching at KV level keyed on all knobs, three model families with specific methodologies, response structure including diagnostics, and warnings for market moves exceeding edge. 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 thorough but verbose, spanning multiple paragraphs. It is well-structured with front-loaded purpose and clear sections for model families, response structure, and knobs. However, some details (e.g., exact gate relaxation parameters) could be trimmed or moved to parameter descriptions for brevity.

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 (9 parameters, three segments, no output schema), the description is remarkably complete. It explains the edge calculation, segment compositions, response fields (including diagnostics and Fed candidates), caching behavior, and even why certain bets are excluded. Everything an agent needs to understand and use the tool 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 covers all 9 parameters with descriptions (100% coverage). The description adds meaningful context beyond the schema, such as explaining the tradeable-edge filters (max_spread_pp, min_liquidity), the rationale for default slippage (20-50bp due to bid/ask), and how min_partition_leg_kelly works specifically for partition arbs.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today' and distinguishes itself from siblings by focusing on data-driven edge discovery without needing to page through hundreds of markets.

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 ('what should I bet on today'), but does not explicitly exclude alternatives or compare to sibling tools like polymarket_arbitrage or polymarket_edge_tracker. It implies the tool is for initial discovery rather than deep analysis.

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 behavior. The description adds significant behavioral details: response structure (tracked, expired, snapshot_dates), computation of decay, and limitations (60-day TTL, daily closes). No contradiction with annotations.

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

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

Description is verbose but well-structured with clear sections for arguments and response. Every sentence adds value. Slightly longer than necessary but 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?

Given no output schema, the description thoroughly explains the response fields and caveats (history depth, decay calculation). It covers all necessary context for a tool with two optional parameters and no output schema.

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

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

Schema coverage is 100%, so schema already documents both parameters. The description adds marginal value by restating defaults and allowed values for 'window' (24hr, 1wk, 1mo) and 'days' (default 14, max 30). Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay over time, answering whether an edge is fresh or old. It uses specific verbs like 'tracks' and 'answers', and the explanation distinguishes it from sibling 'polymarket_edges' by focusing on time-series rather than a single snapshot.

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 (when needing historical edge trend), but does not explicitly state when not to use it or mention alternatives. However, the distinction from 'polymarket_edges' is implied, so it earns a 4 rather than a 5.

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 mark readOnlyHint, openWorldHint, idempotentHint true. The description adds significant behavioral context: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage, etc.), explains basket vs single-market logic, warns about thin legs and forced directional risk. No contradictions.

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

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

Description is long but well-structured with clear sections for single-market and basket modes, uses bold for keywords. Every sentence provides unique value; slight redundancy in introducing modes could be trimmed, but overall it's appropriately dense for a complex 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 meticulously documents return values for both modes, including edge cases like thin_legs, max_clean_notional_usd, and forced_directional_risk. Covers sizing constraints (default, clamp 10–1,000,000) and the rationale for use. Fully enables correct agent invocation.

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

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

Schema coverage is 100%, but the description adds crucial meaning beyond schema: explains default side logic for baskets, clarifies size_usd interpretation (max spend vs target proceeds for single-market; settlement notional for basket), and emphasizes the mutual exclusivity of market and event parameters.

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 starts with a clear, specific verb-resource phrase ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and immediately distinguishes two modes: single-market and basket. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by explaining when to use this tool for execution feasibility checks.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains why (theoretical overround not capturable, partial basket fills create unhedged directional risk), providing clear context for when not to skip this check.

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

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

Even though annotations already indicate read-only, idempotent, non-destructive behavior, the description goes far beyond them: it discloses compatibility warning semantics, gross vs net spreads, the fees_note policy, null temporal_alignment meaning, and skipped/unclassified leg handling. This is exemplary transparency for a read-only analysis tool.

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

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

The description is long, but it is organized with labeled sections and caps for key mode/response/safety concepts. Nearly every sentence carries distinct information needed to interpret the output correctly, though it could be tightened without much loss.

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 must document return semantics, and it does: response legs, top_spreads_pp, compatibility flags per entry, skipped counters, temporal alignment semantics, and fee disclosure. An agent has enough context to invoke the tool and interpret its results.

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

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

Schema coverage is 100%, so the parameters are already documented. The description adds meaningful interaction semantics: explicit ticker/slug overrides the topic-mapped side, and both modes run the identical matcher. It also expands the topic enum with the full shortcut list, adding value 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 states a specific function: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It is clear about the resource and the two modes, but it does not explicitly name sibling tools or state how it differs from them, so it falls short of full differentiation.

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

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

The description clearly explains when to use the topic mode versus explicit ticker/slug mode and warns that most pre-mapped topics return compatibility warnings and are not tradeable. It does not name alternative tools for single-venue analysis or arbitrage, but it gives solid context for using this tool correctly.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds valuable behavioral context: it explains the breakdown behavior of boolean parameters (coo_all/coa_all break totals down by dimension) and warns about code format differences (UNHCR vs. ISO3). No contradictions with annotations.

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

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

The description is a single, well-structured paragraph. It front-loads the main purpose, lists categories, then explains filtering and the important code note. Every sentence adds value with no repetition or fluff. Efficient and 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?

Given the complexity of the tool (8 parameters, no output schema), the description covers the key aspects: categories, filtering, breakdown behavior, and code format. It does not describe the return format (e.g., paginated table), which is a minor gap, but the annotations and examples partly compensate. Overall, it is quite complete for a read-only data retrieval 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 meaning by explaining the breakdown behavior of coo_all/coa_all ('breaks the totals DOWN by that dimension') and clarifying the code format for coo/coa. It also provides examples with parameters. This adds value beyond the schema definitions.

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 retrieves data on forcibly displaced and stateless persons by year and country, with specific categories (refugees, asylum_seekers, etc.). The verb 'forcibly displaced & stateless persons by year and country' is specific, and it distinguishes itself from siblings like asylum_applications by focusing on population stocks rather than flows.

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

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

The description provides explicit guidance on using UNHCR 3-letter codes (not ISO3) and recommends using list_countries first. It explains the filtering by coo/coa and the breakdown behavior of coo_all/coa_all. However, it does not explicitly state when to use this tool vs. sibling tools like asylum_applications or asylum_decisions, leaving the comparison implicit.

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. The description adds that data is scoped to the user's identifier and that omitting key lists all keys, both useful 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 three sentences, each adding value: function, usage context, and scope/pairing. It is front-loaded and 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 simple 1-param read-only tool, the description covers retrieval, listing, scoping, and relationships to sibling tools, providing sufficient context for correct usage.

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

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

The schema already describes the key parameter and its behavior (omit to list all). The description restates this without adding new semantic details, so no extra 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?

The description clearly states the tool's function: retrieve a saved value by key, or list all keys when key is omitted. It provides specific examples like 'user's target ticker' and distinguishes from related tools remember and forget.

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

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

It explicitly advises using recall when needing to look up previously stored context without re-deriving it. It mentions pairing with remember and forget but does not directly contrast with sibling tools beyond that.

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

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

The description states that setting mark_read:true flags events as read, implying state modification, but annotations declare readOnlyHint=true, indicating the tool does not change state. This is a direct contradiction, so score is 1.

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

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

Description is front-loaded with purpose, uses clear language, and every sentence adds useful information without redundancy. Six sentences efficiently cover functionality, alternatives, and parameters.

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

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

Despite no output schema, the description explains return fields and mark_read behavior. It covers filtering, limits, and provides an alternative access method. The tool is fairly complete for understanding usage.

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

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

Schema coverage is 100%, and the description adds value by providing examples (e.g., filter type 'sec_8k') and explanatory context for parameters like since and mark_read, beyond the schema's brief descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the return fields (source, citation_uri, payload) and filtering options. It distinguishes itself from sibling tools like 'ask_pipeworx' and 'subscribe' by focusing on retrieving existing alerts.

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

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

Provides usage context: mentions polling works fine and gives an alternative API endpoint for scripts/dashboards. However, it does not explicitly compare to sibling tools or state when not to use this tool.

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

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

The description adds substantial behavioral context beyond annotations: multi-source fan-out, fallback logic (GDELT → GNews), API sunset status (USPTO soft-fail), and return format structure (changes grouped by source, total_changes count, pipeworx:// URIs). The annotations (readOnlyHint, idempotentHint) are consistent and reinforced by the description.

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

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

The description is front-loaded with query examples and structured into sources, parameters, and sibling comparison. It is slightly verbose but every sentence adds value; no redundancy. The length 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 the tool's complexity (multiple sources, fallback, sunset, no output schema), the description covers all critical aspects: input parameter semantics, output structure, source behavior, and alternative tool. It provides complete guidance for an AI agent to understand and invoke the tool correctly.

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

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

All three parameters have descriptions in the schema (100% coverage). The description adds practical usage details: 'since' accepts ISO date or relative shorthand with examples, recommends '30d' or '1m', and clarifies that 'value' can be a ticker or zero-padded CIK. This goes slightly beyond schema but not dramatically.

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

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

The description begins with specific query patterns ('What's new with X', 'latest on Y'), then clearly states the tool returns a change feed for a company in a recent window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It distinctly differentiates from sibling entity_profile by stating when to use that instead, achieving high specificity and resource identification.

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 when to use the tool (for 'What's new' queries with a time window) and when not to (use entity_profile for static profile regardless of window). It also provides fallback behavior for news sources, giving clear context for selection among sibling tools.

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

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

Adds key behavioral context beyond annotations: scoping by identifier, persistence differences between authenticated (permanent) and anonymous (24-hour) sessions. Annotations declare idempotentHint=true, which aligns with the description's implication that overwriting the same key replaces value. 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?

Extremely concise: 4 sentences covering purpose, usage context, behavioral details, and companion tools. No filler, every sentence adds value. Front-loaded with the primary 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 write tool with no output schema and only two required parameters, the description covers all necessary context: data type, scope, persistence, and integration with related tools. Complete and self-contained.

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 description provides limited added parameter meaning beyond schemas. It gives examples of possible values for the 'value' parameter (findings, addresses, etc.), which is helpful but not substantial. Baseline of 3 is appropriate.

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

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

Description clearly states the tool saves data for later reuse, specifying key-value pairs and scoping. It distinguishes from siblings 'recall' and 'forget' by directly mentioning them as companions. The verb 'save' and resource 'data' are specific and actionable.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward' with concrete examples (ticker, address, preference). Mentions pairing with recall and forget. Lacks explicit when-not-to-use or comparison to alternative tools beyond these siblings, but sufficient for practical 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 declare read-only, idempotent, and open-world hints, and the description goes far beyond them: it discloses graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), ambiguity handling ('when a name matches more than one instrument it asserts nothing'), and output labeling ('every identifier is labelled with the source that established it'). It also reveals the internal cascade ('replaces 2-3 manual lookups'), which is useful behavioral context. 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 and long, but every sentence earns its place given the tool's complexity (two entity types, multiple identifier systems, ambiguity rules, failure modes). It is front-loaded with purpose and the 'Use FIRST' directive before diving into details. Some cleanup is possible—parenthetical asides run long and bullet points would improve scanability—but the structure is logical and the length is justified.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: it lists what is returned for each type, how unresolved identifiers are represented ('stated explicitly under `unresolved`'), and what happens on ambiguous matches. It also covers failure behavior, accepted input forms, and internal cascading. An agent has everything needed to invoke this 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, but the description adds substantial meaning beyond the schema. It explains what 'value' should be in context ('For a bond that is the ISSUER exactly as printed'), gives concrete examples ('AAPL', 'ozempic'), and clarifies why trailing security-class words fail ('the FIGI lookup matches instrument names'). This is exactly the kind of parameter enrichment that prevents mis-invocation.

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

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

The description states a clear, specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates supported types (company, drug) with concrete identifier outputs (CIK, ticker, LEI, FIGI, RxCUI), and the example queries make the purpose instantly recognizable. It also differentiates from siblings by positioning itself as the 'first' step when an ID is needed, which separates it from entity_profile or ask_pipeworx.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' The description also explains when NOT to use it indirectly (ambiguous matches return figi_candidates rather than asserting), and provides critical input-formatting rules ('Pass the ENTITY NAME ONLY... never the question's full noun phrase'). This is clear, actionable routing that leaves little to inference.

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, idempotent, non-destructive. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density per entity. No contradiction.

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

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

Two sentences, no wasted words, front-loaded purpose. 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 specifies return: ranked list with score, confidence, signal density per entity. Parameters fully covered by schema (100%). Sufficient for selection and invocation.

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

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

Schema coverage is 100%, baseline 3. Description adds context for 'entities' (first entry treated as subject) and 'context' (disambiguates common names), but does not significantly augment the schema for models or _apiKey.

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

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

Description uses specific verb 'compare' and resource 'AI visibility across multiple entities', with clear outcome: 'ranks by score, surfaces which is most/least recognized'. Distinct from sibling ai_visibility_check which is single-entity.

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 use case 'competitive AI-marketing audits' and gives example question. Could be improved by stating when not to use (e.g., single entity), but context is clear.

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

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

Annotations already cover safety and idempotency. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia timing (5-30s), and the sources_failed field. This goes beyond the annotations, though it could explicitly mention that the tool is safe to call repeatedly.

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 a front-loaded purpose, though it is somewhat lengthy. Every sentence adds value, but some could be tightened slightly (e.g., the list of fields could be abbreviated).

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 comprehensively details return values (summary fields, per-advisory detail, links, alternative versions) and error behavior (sources_failed). It covers all essential aspects for agent decision-making.

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 nuance: scoped packages are accepted, and version defaults to latest published. This provides clarity beyond the schema alone.

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

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

The description clearly states the tool's purpose: a composite check for npm packages covering license, advisories, bundle size, and tree-shake support. It uses a specific verb ('scan') and distinguishes from siblings by noting the NPM-only scope in v1.

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 provides usage scenarios ('is X safe / popular / small', 'what does adding lodash cost me'). Also specifies when not to use (non-npm packages should use deps.dev:version directly), giving clear guidance on alternatives.

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

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

The description reveals key behavioral traits beyond annotations: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, input cap of 200K chars with truncation warning, and output includes character offsets. This adds substantial value beyond 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 a single well-structured paragraph that front-loads purpose, then provides usage guidance, and ends with technical details. Every sentence adds value without redundancy.

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

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

For a tool with no output schema, the description still mentions output contains passages with character offsets and similarity scores. While a full return structure isn't specified, it gives sufficient info for an agent to use the outputs. Input parameters and behavior are fully covered.

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 description coverage, the baseline is 3. However, the description adds meaningful context: explains query as 'natural-language query' with examples, specifies default/range for limit, and clarifies text max size. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool performs 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the difference in usage patterns, making it easy for an agent to select appropriately.

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

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

Explicitly advises to use when a record is too big for the prompt, explains how it saves context, and directly pairs with ask_pipeworx_grounded for a clear workflow. This provides strong guidance on when and how to use the tool vs 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 idempotentHint=true and destructiveHint=false, and the description adds context: subscription creation is not a read operation, it is idempotent, and it requires authentication. It also discloses that webhooks return a secret once and auto-disable after failures. 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 thorough yet well-structured: it opens with the core action and return value, then covers requirements, types, and delivery options. It is slightly long but every sentence adds value, and the most critical information (purpose) is front-loaded.

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

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

Given the tool's complexity (multiple subscription types, nested parameters, multiple delivery channels, authentication requirements, and rate limits), the description covers all essential aspects: what it does, prerequisites, type-specific details, delivery configuration, and behavioral notes (webhook signing, auto-disable). No output schema exists, but the return value is stated. The description is complete for an AI agent to use correctly.

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

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

Schema coverage is 100% with decent descriptions, but the tool description goes much further: it provides concrete examples for each subscription type (e.g., sec_8k with items, polymarket_edge with topics), format specifications for delivery (SMS, email, webhook with HMAC details), and additional constraints (phone verification, rate limits). This adds significant value 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 a subscription ID. It distinguishes from sibling tools like list_subscriptions, recent_alerts, and unsubscribe by specifying its role as creation.

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 mentions the requirement of a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. It also details delivery channels with their constraints (SMS verification, 10/day cap). While it doesn't explicitly contrast with sibling tools like recent_alerts for pulling, the context is strong enough for informed use.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds that the response includes category-bucketed questions and exact tool+argument shapes, providing useful behavioral context beyond annotations. No contradictions.

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

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

Description is clear and well-structured with examples, though moderately lengthy. Every sentence adds value, 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?

For a simple tool with one optional parameter, no output schema, and robust annotations, the description fully explains the response format, usage scenarios, and integration with other tools.

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 one optional string parameter. Description elaborates on possible topic values and effect of omission, adding practical context beyond the schema description.

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

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

The description clearly states the tool's purpose as the onboarding entry point, returning categorized example questions with tool argument shapes. It distinguishes itself from siblings like discover_tools by positioning itself as the first call for new users.

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

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

Explicitly says to call with no arguments for full spread or pass a topic to focus, and to use this tool first when unsure of Pipeworx capabilities. Provides clear guidance on when and how to use.

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

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

Discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts, adding significant behavioral context beyond annotations.

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

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

Three concise sentences, each providing essential information with no redundancy or fluff.

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

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

Given 1 parameter, no output schema, and annotations, the description covers purpose, usage, behavior, and parameter semantics completely.

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 for the single 'id' parameter. Description adds context about ownership enforcement, which is parameter-related and valuable beyond the schema.

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

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

Clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'list_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?

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage context. Lacks explicit alternatives, but the ownership constraint is a strong guideline.

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/non-destructive annotations, the description adds crucial behavioral context: the internal routing (SEC EDGAR/XBRL fast path vs grounded pipeline), the full set of verdicts, and the critical caveat that 'could_not_verify' means the check did not happen and must not be treated as evidence. This is genuinely helpful and goes beyond annotation defaults.

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 purposeful, front-loading with example trigger phrases. It's longer than average, but every sentence adds needed context for a complex tool. The heavy em-dash parentheticals make it slightly harder to parse, so it's not a perfect 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?

There is no output schema, so the description carries the full burden of explaining return values. It lists the verdict classes, the structured/grounded actual value with citation, reasoning, and error semantics. It also covers fallback routing and caller guidance. For a tool of this complexity, the description is remarkably complete.

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

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

The input schema already provides strong descriptions for both parameters (claim and tolerance_pct), with 100% schema coverage, so the baseline is 3. The description adds minimal parameter-specific nuance—mostly repeating the tolerance semantics already in the schema ('exact percent-delta math'). It doesn't compensate with extra detail beyond what's structured.

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 natural-language trigger phrases and clearly states the tool performs 'natural-language claim verification against authoritative sources.' It identifies the resource (claims) and the verb (verify/validate), and it distinguishes itself from sibling research/Q&A tools by specifying the exact use case: checking if a user statement is factually correct.

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

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

The description explicitly instructs 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear usage context. It also notes that the tool replaces 4–6 sequential calls, but it does not name specific alternative sibling tools or provide explicit exclusions (when not to use), so it falls short of a 5.

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