airports

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

Annotations declare readOnly/openWorld/idempotent, and the description adds valuable behavioral context: the default free model (Workers AI Llama-3.3-70b), the cost implication of using Anthropic ('you pay Anthropic directly'), and the exact return shape (per-model {score, confidence, signals, raw_response} + combined view). No contradictions.

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

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

Two sentences, front-loaded with the core purpose, followed by operational specifics. Every sentence earns its place; no redundancy or filler, and the structure is easy to scan.

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

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

Despite having no output schema, the description states the return structure, default behavior, optional API key usage, and use cases. This is sufficient for an agent to decide when to invoke it, though it could hint at error scenarios or interpretation of scores.

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 each parameter already well-described (e.g., models definition includes the default and _apiKey requirement). The description repeats this information without adding new semantic value beyond what the schema provides, so 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 opens with a specific verb ('Probe') and resource ('one or more LLMs'), and clearly states the output ('score visibility 0-100 per model'). This distinguishes it from siblings like scan_competitor_ai_presence by focusing on general brand/topic awareness across multiple models.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly mention alternatives or when-not-to-use, but the context is clear enough for an agent to select this tool over similar ones.

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

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

Annotations already cover read-only, open-world, and idempotent hints. The description adds transparency by explaining how it works: routes to one of 5,529 tools, fills arguments, returns citation URIs, and is fast. It does not contradict annotations and gives a clear behavioral model, though it omits failure modes or rate limits.

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

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

The description is long, but every sentence earns its place: it covers use cases, examples, alternatives, and performance characteristics. It is front-loaded with the key directive 'PREFER OVER WEB SEARCH' and scans well despite being a single dense paragraph. Slightly more structure could improve scannability, but it remains highly functional.

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 (routing across 5,529 tools), the description covers all essential aspects for correct invocation: purpose, examples, parameter expectations (implied), return format (structured with citations), and when to step up to siblings. It omits edge-case behavior, but the coverage is solid for an agent to use it appropriately.

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 thoroughly documents all parameters (100% coverage) with each alias (q, text, query, prompt, input, question) described as a variant of 'question'. The description does not add parameter-level detail, but the schema already provides sufficient semantics, so 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: routing factual questions to authoritative sources and returning structured answers with citations. It uses specific verbs like 'routes' and 'returns', and explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, making it unmistakable.

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

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

It provides extensive when-to-use guidance: lists trigger phrases ('what is', 'look up', 'get the latest'), gives concrete examples, and explicitly names alternatives for edge cases (e.g., ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions). This goes beyond basic context to clear 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 goes beyond annotations by explaining that candidate routing improvements are enabled live, that no candidate is currently active so it matches ask_pipeworx exactly, and that results are compared against the stable router. It also clarifies that there is no fallback – it is a full working router. This provides important context for an experimental 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 a single dense paragraph of three sentences, each providing necessary information about beta status, current equivalence, and usage. It is appropriately sized for the tool's complexity, though slightly unstructured.

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 tool's experimental role and current behavior well, but it relies on knowledge of ask_pipeworx for core functionality details, and it does not specify the response format in the absence of an output schema. Given the tool is a beta variant of an existing tool, some gaps remain.

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 six parameters are aliases for `question` and the schema thoroughly documents each one with descriptions. The tool description adds no parameter-specific guidance, but with 100% schema coverage, the 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?

The description identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same tool set, arguments, and response shape. It distinguishes it by its experimental nature and live candidate routing improvements, though it does not explicitly state in plain terms that it answers natural language questions.

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 to use it exactly like ask_pipeworx when you want the newest routing, giving a clear usage context. It implies experimental instability but does not name alternative tools or exclusions explicitly.

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 state read-only, open-world, idempotent, non-destructive. The description goes further by detailing the exact success response shape, refusal reasons, the constraint of using only tool-result content, and the extra LLM call cost. This is rich behavioral context beyond what annotations provide.

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

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

The description is dense but well-structured: purpose, mechanism, return format, usage context, and cost comparison are all covered without fluff. It is front-loaded with the most important distinction and every sentence contributes useful information.

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

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

Given no output schema, the description fully explains return values on both success and refusal, including possible refusal reasons. It also covers the routing scope, cost tradeoff, and when to prefer the alternative, making it complete for an AI agent deciding whether and how to invoke the tool.

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

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

Schema description coverage is 100% with every parameter explained as an alias for 'question.' The description does not add new meaning to individual parameters, but the schema already fully documents them, so the 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?

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly identifying the tool as a grounded variant of ask_pipeworx. It distinguishes itself from siblings by emphasizing extraction from tool results only and explicit refusal behavior, making its purpose unambiguous.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' The reference to 'Same routing as ask_pipeworx' also clarifies the alternative and its relationship to the sibling tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, but the description goes far beyond them. It discloses fan-out behavior, resolver contract, blocking statuses (low_confidence_match, market_closed_or_inactive), illiquid warnings, and cancellation-rule risk (refund_50_50, resolves_no_on_cancel, etc.). This is rich behavioral context that annotations alone do not provide.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and is front-loaded with purpose and usage. Every sentence adds operational value; there is little redundancy. Slight deduction for length, but it's appropriate for the tool's complexity.

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

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

With no output schema, the description carries full responsibility for explaining return values. It thoroughly covers result.market fields, result.analysis fields, evidence keying, resolver contract (market_match_confidence, alternatives, suggestions), parent_event extraction, news fallback fields, safety statuses, and cancellation-rule handling. This is exceptionally complete for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning to the 'market' parameter by explaining how classification drives category-specific fan-outs (e.g., BTC bet → coingecko + fred + gdelt+gnous) and by describing response shapes tied to the input. This goes beyond the schema's simple type/format description, so a 4 is warranted.

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 opening line states a specific verb+resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It also gives concrete input examples (slug, URL, question text) and distinguishes itself from sibling tools by listing exact use cases like "should I bet on X." This clearly separates it from tools like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly says "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'," providing clear context for when to invoke the tool. However, it does not mention when not to use it or explicitly compare with alternatives, so it falls short of a full 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 declare readOnlyHint: true, openWorldHint: true, idempotentHint: true, and destructiveHint: false. The description adds useful context beyond these annotations by specifying that it returns kilometers and miles, and that it uses straight-line distance. 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 exceptionally concise, comprising two short sentences that front-load the action and resource. It includes a relevant example without any wasted words, achieving maximum information density.

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

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

For a simple, read-only calculation tool with an output schema and comprehensive annotations, the description covers all necessary aspects: input format, operation, and output units. There are no missing requirements given the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a concrete example ('JFK' to 'LHR') and reinforces the IATA code format, but the schema already fully explains both parameters as 'IATA code of origin/destination airport'. No deeper semantics are introduced.

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 verb 'Calculate' and resource 'straight-line distance between two airports', with an example that makes the purpose unambiguous. This distinguishes it from sibling tools like get_airport and search_airports, which provide different functionality.

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

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

The description implies when to use the tool (whenever straight-line distance between two airports is needed) and clarifies the input format via IATA codes. However, it does not explicitly mention alternatives or when not to use it, leaving a small gap in 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?

Goes well beyond annotations by disclosing data sources (SEC EDGAR/XBRL for companies, FAERS and FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. This is consistent with readOnlyHint, idempotentHint, and destructiveHint=false, with no contradictions.

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

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

The description is dense and front-loaded with trigger phrases and a strong preference instruction. While lengthy, each sentence contributes unique value—usage examples, data sources, sorting behavior, and efficiency benefit. Slightly overlong but appropriately structured 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?

For a tool with no output schema, the description thoroughly covers return format ('paired data + pipeworx:// citation URIs'), sorting behavior, data sources, and even handles edge cases like off-calendar fiscal years. It provides a complete picture for an AI agent to select and invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds significant meaning: it explains exactly what each type retrieves (10-K revenue, net income, cash, debt for companies; adverse-event counts, approval counts, trial counts for drugs) and clarifies value formats (tickers/CIKs vs drug names). This enriches the bare 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's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It uses a specific verb ('compare') and resource ('entities'), and differentiates from sequential lookups and siblings like entity_profile by focusing on multi-entity comparison in a single call.

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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also lists trigger phrases ('X vs Y', 'which is bigger') and notes it replaces 8–15 lookups, effectively distinguishing from alternative approaches.

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 annotations (readOnly, openWorld, idempotent, non-destructive) by disclosing behavior such as returning gaps[] with 'never invented', semantic excerpting, contradiction detection, latency expectations (15-60s, up to ~90s), and the meaning of depth modes. It reinforces the openWorldHint with 'gaps[] for facets the data couldn't answer' and adds critical operational context without contradicting annotations.

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

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

The description is long but every section serves a purpose: prerequisites, alternatives, core mechanism, use cases, edge cases, and performance. It is not tightly front-loaded (starting with account requirements rather than the core action), but the information density is high and logically organized. It earns a 4 for being comprehensive and mostly non-redundant, though it could be trimmed slightly.

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

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

Given the tool's complexity (2 params, no output schema), the description is exceptionally complete. It covers the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[]), the depth modes and their effects, error handling for topics outside the catalog, and timing expectations. An agent could confidently invoke this tool correctly based solely on this description.

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

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

Input schema already covers 100% of parameters, so baseline is 3. The description adds meaningful nuance beyond the schema: it explains that depth:'standard' is default and adds 'a gap-recovery hop', while 'thorough' is paid and adds 'a full iterative hop', plus the contradictions[] scan. It also clarifies that the question can be broad/multi-part and that decomposition is intentional, enriching the parameter meaning beyond the schema's basic descriptions.

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

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

The description clearly states the tool's verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call. It distinguishes itself from siblings by explicitly stating 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups. It is highly specific about the scope and output, making the purpose unambiguous.

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

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

Explicit guidance is given for when to use this tool vs alternatives: 'Best for broad/multi-part questions', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also covers account prerequisites and says 'If you are not signed in, use ask_pipeworx instead'. This is exemplary usage guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower. The description adds valuable behavior: returns top-N tools with names, descriptions, and full input schemas with curated examples, and guarantees 'no second schema lookup needed.' 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 well-structured, front-loading the core purpose and then efficiently covering usage, return value, and strategic advice. 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?

Given no output schema, the description adequately explains the return format (names, descriptions, full schemas, examples). It covers purpose, usage, and output, but doesn't address edge cases like empty results or relevance ranking, leaving a minor gap.

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 detailed descriptions for all six parameters, including aliases and limits. The description adds little beyond the schema, simply mentioning 'top-N' without specifying default/max, which the schema already covers. 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 opens with 'Find tools by describing the data or task,' providing a specific verb and resource. It further distinguishes this tool from siblings by listing the broad domains it covers and emphasizing its meta-discovery role ('Call this FIRST...').

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and advises calling it first when many tools are available. However, it doesn't name alternative tools or explicitly state when not to use it, so it lacks complete 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?

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context beyond that: it discloses the parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF, and specifically notes the USPTO PatentsView API sunset May 2025 with soft-fail behavior. It also details return fields and the 'names not supported' limitation. 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 every sentence earns its place. It front-loads with user examples, then states the core purpose, followed by structured return details. The semicolon-separated list of outputs is efficient. It could be slightly more condensed, but for a complex multi-source tool this 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 burden of explaining return values, and it does so thoroughly: cik + company_name, recent_filings (up to 5 with URIs), fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash), patents, news via GDELT→GNews fallback, and LEI. It also covers input constraints, source sunset, and fallback behavior. The description is complete for the tool's complexity.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds useful semantics beyond the schema: it provides ticker and zero-padded CIK examples ('AAPL', '0000320193'), explicitly states names are not supported, and instructs to use resolve_entity first if only a name is available. This adds practical guidance not present 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 the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple example queries ('Tell me about X', 'research Acme', 'brief me on Tesla') and distinguishes it from siblings by specifying it should be preferred over chaining single-pack lookups for holistic views. It also differentiates from resolve_entity by noting names are not supported.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives an alternative by stating 'names not supported (use resolve_entity first if you only have a name).' This provides clear usage context and 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?

Annotations already declare destructiveHint and idempotentHint, and the description is consistent. It adds context about the nature of the data ('sensitive data') and when deletion is appropriate, going beyond the bare annotation.

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 focused sentences: the first states the action, the second provides usage scenarios and sibling pairing. No unnecessary words.

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

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

For a single-parameter delete tool with annotations covering destructive/idempotent behavior, the description covers purpose, usage, and pairing. It doesn't explain error handling for missing keys, but the idempotent annotation mitigates that.

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

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

The schema already provides 100% coverage for the single 'key' parameter with a description. The tool description mentions 'by key' but doesn't add meaningful semantics beyond the schema, so baseline 3 applies.

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

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

The description uses a specific verb 'Delete' and a clear resource 'previously stored memory by key,' making the tool's function obvious. It also distinguishes from sibling tools by referencing pairing with remember and recall, indicating this is the deletion counterpart.

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 states when to use the tool: when context is stale, task is done, or clearing sensitive data. This gives clear context, though it lacks an explicit 'when not to use' statement, so it's not a perfect 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 declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by explaining the behavior of fetching the page, extracting content, and emitting a markdown text blob, which goes beyond the annotation hints. 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 two sentences plus a concise bullet-like list of use cases. It front-loads the core purpose and process, with every sentence contributing meaningful information and 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?

For a tool with only 2 parameters, full schema coverage, and supportive annotations, the description thoroughly covers purpose, process, output format, and use cases. It does not delve into error handling or edge cases, but those are not essential for a clearly-scoped read-only tool, so 4 is appropriate.

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 both parameters (url and max_links) have clear descriptions in the schema. The tool description does not add parameter-specific details beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb 'Generate' and identifies the resource 'llms.txt file for any URL'. It details the process (fetches page, extracts title/description/key links, emits markdown) and includes use cases that distinguish it from sibling tools like scan_competitor_ai_presence, making the tool's purpose unambiguous.

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

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

The description explicitly lists three use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), providing clear context for when to use the tool. It does not explicitly name alternatives or state when not to use it, hence 4 rather than 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety and side-effect profile. The description adds the return fields but does not disclose any additional behavioral traits such as potential errors, caching, or data freshness. Given the strong annotation coverage, the description provides modest extra 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 two concise sentences, front-loaded with the action and scope, then a clear list of return fields. Every word earns its place, and there is no redundancy or filler.

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

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

For a simple lookup tool with one parameter, a rich output schema (implied by 'has output schema: true'), and strong annotations, the description is largely complete. It covers the purpose, parameter, and return values. It does not mention error handling or invalid code behavior, but given the tool's simplicity and existing schema, this is a minor gap that does not undermine usability.

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% for the single parameter (iata_code) with a clear description. The tool description repeats the code examples ('JFK', 'LHR') already present in the schema, adding no new semantics. Since the schema already fully documents the parameter, the description does not significantly enhance parameter understanding.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('airport details by IATA code'). It also lists the specific details returned (name, city, country, coordinates, altitude, timezone). While it does not explicitly differentiate from sibling tools like search_airports, the 'by IATA code' scope implies a distinct lookup mechanism, making the purpose 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 implies usage context: when you have an IATA code, you can retrieve airport details. However, it does not explicitly state when to use this tool vs. the sibling search_airports, nor does it provide any exclusions or alternatives. The guidance is thus inferred rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds valuable context about the caller-specific scope ('the caller's') and the return payload (fields listed), which goes beyond the annotations. No contradictions or surprising behaviors are hidden.

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 short, information-dense sentences. The first states the action, the second lists return fields, and the third gives usage context. No filler words or redundant information. Front-loaded with the essential 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 read-only list tool with one optional parameter and no output schema, the description covers all essential aspects: what it does, what it returns, when to use it, and implicit scoping. The annotations cover safety, and the schema covers parameters, so the description rounds out the picture nicely.

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 provides 100% coverage for the single parameter include_inactive, including a description. The tool description does not add any additional meaning to the parameter, so the schema carries the burden. 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 verb 'List' and the resource 'the caller's active subscriptions', immediately distinguishing it from sibling tools like subscribe/unsubscribe. It also enumerates the exact returned fields (id, type, params, etc.), leaving no ambiguity about the tool's function.

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 provides usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool, though it doesn't explicitly mention when not to use it or alternatives. Still, the guidance is clear and practical.

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 minimal (all hints false), so the description carries the full burden. It discloses key behavioral details: claim_token mechanics for follow-up without an account, rate limit of 5 per identifier per day, daily digest consumption, roadmap impact, and that it's free and doesn't count against tool-call quota. These details go beyond what annotations or schema provide, offering rich contextual transparency.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose before diving into use cases, exclusions, and operational details. Every sentence earns its place: usage criteria, MCP boundary, token mechanism, rate limit, and roadmap impact. No filler or redundancy.

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

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

Given the tool's moderate complexity (nested context object, 4 params, no output schema), the description is highly complete. It explains the return value mechanism (claim_token) and how to read status later. Minor gaps exist, such as not explicitly describing the response format for the initial filing beyond the claim_token, but the core usage is 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?

Schema coverage is 100% and the schema descriptions are already detailed (e.g., enums, context fields). The description adds extra semantic value by advising users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, which clarifies message content. It also explains the claim_token parameter's dual use (follow-up vs. original filing). This slightly exceeds the baseline for full 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from sibling tools (e.g., ask_pipeworx, discover_tools) by focusing on feedback about Pipeworx tools themselves. The purpose is unambiguous and action-oriented.

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

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

The description provides explicit when-to-use conditions: bug, feature/data_gap, or praise. It also gives a strong exclusion criterion: do not use for tools from other MCP servers, and provides a fallback method ('file it with that server instead'). The 'Not sure?' clarification further guides the user. This is exemplary usage guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond these: it reveals the data source ('derived from CF analytics-engine'), privacy handling ('no PII'), the exact output granularity ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This fully discloses the tool's internal behavior and data provenance, exceeding the annotation baseline.

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

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

The description is well-structured and front-loaded: the first sentence immediately states what the tool returns, followed by a numbered list of use cases, and ends with technical notes on data source and caching. Every sentence contributes unique value with no filler. It is appropriately sized for a tool with this level of nuance.

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

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

The tool is simple (one optional parameter, no output schema) and the description covers all essential aspects: return value (top tools, top packs, total call volume), data source, privacy, caching, and usage context. Since there is no output schema, the description reasonably conveys the output structure by mentioning '(pack, tool, count)'. The combination of annotations and description provides complete context for an agent to select and invoke this tool.

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

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

The only parameter 'window' has 100% schema description coverage: the schema already explains the enum values and their semantics ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). The main description mentions the windows but adds no additional meaning beyond the schema. With high schema coverage, the baseline is 3.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' This is a specific verb ('Returns'), resource ('Pipeworx trending data'), and scope ('over a recent window'), and it distinguishes itself from siblings like discover_tools by focusing on current aggregated agent usage rather than general tool discovery. The 'Self-aggregating signal' phrase further differentiates it.

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 three explicit use cases: 'discovering what data sources are hot for current events,' 'confirming a popular tool is the canonical choice before asking your own question,' and 'seeing whether your use case aligns with what most agents need.' These give clear context for when to use the tool. However, it does not name alternative tools or explicitly state when NOT to use it, 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.

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

Beyond the readOnly/idempotent annotations, the description discloses material behavior: the 0.30 Jaccard semantic anchor, the placeholder-filter threshold (>20% returns null), and the fill-check against live CLOB depth with a clear 'do not trade it' warning when realizable_edge_pp ≤ 0. This is rich behavioral context 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 long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core call pattern. It earns its length by packing essential thresholds, examples, and response details without redundancy, fitting 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?

With no output schema, the description compensates by specifying the response shape (opportunities[] with gap_pp, suggested_trade, reasoning, and partition_check fields). It also covers edge cases, mode selection, and references polymarket_fill_risk, making it fully self-sufficient for an agent to invoke correctly.

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

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

Although the schema already covers both parameters with 100% coverage, the description goes substantially further by providing concrete slug/topic examples, explaining how each mode changes the scan (event walks child markets; topic flattens related events), and clarifying the semantics of the Jaccard filter. It adds meaning beyond the schema's property descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the three call modes (trending_scan, event, topic) and even names polymarket_fill_risk as the sizing alternative, so it stands apart from sibling tools.

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

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

Explicit when-to-use guidance is provided for each parameter combination: call with no args for trending_scan, pass event for a specific market, or pass topic for cross-event scanning. It also recommends event for specific markets and points to polymarket_fill_risk for custom sizing, fully covering 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?

Beyond the read-only/idempotent annotations, the description discloses significant behavioral traits: caching at the KV level for 1 hour, internal threshold changes (Run 8 relaxed gates), why fed_candidates are excluded, the 24h-move warning, and detailed filter logic. This gives the agent a rich understanding of runtime behavior.

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

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

The description is extremely long and dense, covering many edge cases and internals. While it is structured with clear sections and no filler, its length may reduce skimmability. It is more than necessary for basic usage, but each sentence does add some value.

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

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

With no output schema, the description fully documents the response structure, including by_segment, fed_candidates, and _diagnostics. It also explains why segments may be empty and what each field represents, ensuring the agent knows exactly what to expect from the tool.

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

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

The input schema already has 100% documentation coverage, but the description adds context beyond the schema. It explains the 'TRADEABLE-EDGE KNOBS' and clarifies subtle interactions like min_partition_leg_kelly applying to per-leg Kelly rather than parent-level, which is not obvious from 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 opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and differentiates it from siblings by emphasizing Pipeworx data and the 'what should I bet on today' use case.

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

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

The description provides clear usage context with 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so it lacks explicit 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description extensively discloses response structure, semantics of trend and decay_pp_per_day, the meaning of snapshot gaps, and limits like TTL and daily closes. This goes far beyond what annotations provide, making the tool's behavior highly predictable.

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

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

Although long, the description is exceptionally well-structured and dense with information. It opens with the core purpose, then organizes args, response format, and limits in clearly labeled sections. Every sentence earns its place, with no filler.

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

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

The description compensates for the lack of an output schema by fully specifying the response object (tracked, expired, snapshot_dates) and their semantics. It also covers historical limitations (TTL, snapshot gaps) and data nuances (net slippage), making the tool fully understandable without external context.

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

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

The schema covers both parameters (days, window) with descriptions, so baseline is 3. The description adds meaningful context: days is a lookback with default 14 and max 30, and window refers to a snapshot family, tying parameters to the snapshot architecture. This enhances understanding beyond the raw 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 a specific purpose: tracking edge persistence and decay from daily snapshots. The verb 'tracker' plus the phrase 'Answers "how long has this edge existed and is it shrinking?"' makes the function unambiguous, and the contrast with fresh vs. old edges distinguishes it from sibling 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 provides clear context for when the tool is relevant: when assessing whether an edge is still worth taking based on its age and decay. It does not explicitly name alternative tools or provide when-not-to-use guidance, but the context strongly implies this is for historical persistence analysis rather than current edge discovery.

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

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

The description discloses several behavioral traits not captured in annotations: it 'walks the ladder,' requires one of market or event, returns a verdict, and warns about partial fills creating 'unhedged directional position.' It also adds safety context (forced_directional_risk, thin_legs) and explains the consequences of misuse, which annotations alone do not provide.

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 appropriately so for a dual-mode tool with complex return fields. It is front-loaded with the core purpose, then logically broke into SINGLE-MARKET, BASKET, and usage guidance; no sentence is filler. Could be slightly tightened but structure earns high marks.

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?

Even without an output schema, the description enumerates every important return field for both modes (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, profit_usd, thin_legs, etc.), mentions edge cases (partial fills, thin books, forced directional risk), and clarifies defaults and clamps. It is fully self-contained for an agent to know what to expect and when to use it.

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

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

Schema coverage is 100% (baseline 3), but the description adds meaningful semantics beyond raw schema: size_usd is 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional' for basket; side has explicit default behavior per mode. It also clarifies the mutually exclusive requirement of market vs event, which the schema only implies.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes three modes (single-market, basket, and auto), and the unique value proposition is evident from the start, establishing it as distinct from sibling tools like polymarket_arbitrage and 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?

Usage guidance is explicit and actionable: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk rationale (thin books, unhedged directional positions), giving agents clear criteria for when this tool is required versus optional.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses detailed behavioral traits: the compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the caveat that pre-mapped topics often yield non-tradeable results. This is a textbook example of adding behavioral transparency beyond structured metadata.

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

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

The description is lengthy and detail-dense, but it is front-loaded with the core purpose and then structures the remaining content with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every detail serves a purpose; however, given the sheer volume, a more condensed version might serve agents better. It earns a 4 for good structure and no waste, but not a 5 due to length.

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

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

With no output schema and complex edge cases, the description carries the full burden of explaining return values and safety conditions. It thoroughly describes the response shape (leg-by-leg prices, matched spread, compatibility_warning, temporal_alignment, skip counters) and interprets when results are valid. This is complete enough for an agent to invoke and evaluate 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?

The schema already documents all three parameters with 100% coverage, satisfying the baseline of 3. The description adds meaningful interaction semantics: how topic auto-fetches events, how explicit tickers override the mapped side, and the concept of custom pairings. This elevates parameter understanding beyond simple type/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 opens with a specific noun phrase identifying the exact function: "Cross-venue spread between Kalshi and Polymarket for the same resolving question." It immediately distinguishes itself from siblings by naming both venues and the concept of a spread, and further explains the available modes and output, leaving 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?

The description offers two clear usage modes (topic shortcuts vs. explicit tickers) and explicitly warns when results are unreliable: "most pre-mapped topics return compatibility_warning today" and "aligned:false means spreads are mathematically meaningless." It does not explicitly name alternative tools for different conditions, so it stops short of a 5, but the context is strongly usage-oriented.

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, lowering the burden on the description. The description adds valuable context by explaining scoping (anonymous IP, BYO key hash, account ID) and the special behavior of omitting the key argument to list all keys, which goes beyond what annotations convey.

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 (three sentences) and front-loads the primary action. Each sentence provides distinct, necessary information: the operation, use case, and scoping/companion tools, with no redundant wording.

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

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

For a simple tool with one optional parameter and no output schema, the description is comprehensive. It covers the operation, usage scenario, scoping, and relationships with sibling tools, so the agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to retrieve (omit to list all keys)', matching the description closely. The description adds contextual value by connecting the key to values 'previously saved via remember', reinforcing the parameter's role in the memory workflow.

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

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

The description uses specific verbs ('Retrieve', 'list') and clearly states the resource (values saved via remember), making the tool's function unambiguous. It also distinguishes itself from siblings by explicitly naming remember and forget as companion operations, which clarifies its unique role in the memory lifecycle.

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

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

The description provides clear context for when to use the tool ('look up context the agent stored earlier'), and explicitly pairs it with remember and forget. However, it does not explicitly exclude alternative tools or list when-not-to-use scenarios, though the internal memory use case is well implied.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral detail: each event carries source, citation_uri, and raw payload; mark_read flags events; feed is persisted; and the same feed is available via HTTP. 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?

Four sentences, front-loaded with the core purpose, and each sentence delivers unique, non-redundant information. No filler or wasted words.

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

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

With no output schema, the description adequately covers return payload details, filtering options, mark_read semantics, and the alternative HTTP access point. It is complete for a read-only tool with well-documented parameters and annotations.

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 each parameter is described. The description supplements with a concrete filter example ('sec_8k'), clarifies mark_read side effects, and explains the returned event structure, 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 clearly states the function: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts the evaluator has written to your persisted feed'. This specific verb+resource distinguishes it from sibling tools like list_subscriptions and recent_changes.

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: filtering by type and since, polling behavior, and the alternative HTTP endpoint for scripts. It does not explicitly name sibling alternatives or exclusions, but the practical guidance is sufficient.

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

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

Beyond the readOnly/idempotent hints, the description discloses the exact data sources, fallback behavior, soft-fail condition for USPTO, rate-limit handling, and return shape (changes[] grouped by source). 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?

Though long, the description is front-loaded with use cases and every sentence carries critical operational detail (sources, fallback, parameter formats, output summary). No fluff; the density is justified by tool 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?

With no output schema, the description compensates by outlining the response structure (changes[], total_changes, citation URIs). It also covers data source fallback and limitations, making it complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds significant value by explaining `since` formats (ISO and relative shorthand), typical usage ('30d' or '1m'), and giving concrete examples for `value` (ticker or CIK). This exceeds baseline interpretation.

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

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

The description clearly states this is a change feed for a company over a time window, covering SEC, news, and patents. It uses specific verbs like 'change feed' and explicitly distinguishes from sibling tool entity_profile, telling the agent when to use which.

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 query examples ('What's new with X'), explains the fallback logic (GDELT to GNews), and names the alternative tool entity_profile for static profiles. This is direct when-to-use guidance with 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?

Beyond annotations, the description discloses persistence and scoping behaviors: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours' and 'scoped by your identifier'. This adds meaningful context consistent with the idempotentHint annotation.

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

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

Four focused sentences, front-loaded with the core action. Each sentence adds value: purpose, when-to-use, storage format, and persistence/companion tools. No redundant 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?

For a simple two-parameter tool with no output schema, the description is fully complete. It covers purpose, usage, scope, persistence, and related tools, making it easy for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with detailed key/value descriptions, so the baseline is 3. The description adds purpose and scope context but does not introduce new parameter-specific semantics beyond what the schema already provides.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Save data the agent will need to reuse later'. It distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete'.

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: 'Use when you discover something worth carrying forward' with concrete examples. It names alternatives (recall, forget) but does not explicitly state when not to use the tool, so a near-perfect score is warranted.

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 beyond the read-only/idempotent annotations by disclosing internal cascading lookups, source labeling of identifiers, explicit handling of unresolved identifiers, and graceful degradation when GLEIF/OpenFIGI are unavailable. It also mentions ownership data when LEI resolves. This is rich behavioral context not present in annotations or 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 dense but structured: it opens with examples, states the core purpose, gives direct usage guidance, then details each supported type. Every sentence adds value, though the length is slightly above average. It is well-organized but could be trimmed without losing essential guidance.

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

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

With no output schema, the description carries the full burden of explaining return values. It details the identifiers returned for company (CIK, ticker, LEI, FIGI, ownership) and drug (RxCUI, ingredient, brand, citation), including the `unresolved` field. It also covers fallback behavior and internal cascading, making it fully adequate for 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% with detailed descriptions for both parameters. The description reinforces what the schema already states (e.g., accepting ticker/CIK/name for company) but adds little new parameter-level meaning. The mention of FIGI when a ticker is implied is a slight addition, but the heavy lifting is done by 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's purpose: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It gives concrete usage examples and differentiates from siblings by saying "Use FIRST whenever you have a name but need an ID." It also lists supported entity types and the specific identifiers returned, making its scope unambiguous.

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

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

The description explicitly states when to use the tool: "Use FIRST whenever you have a name but need an ID." It also notes that it replaces 2-3 manual lookups, which gives context. However, it does not provide explicit when-not-to-use guidance or name alternative tools, so it falls short of the highest bar.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also discloses return fields (score, confidence, signal density), which is useful beyond annotations.

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

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

The description is three succinct sentences, front-loaded with the primary action. Every sentence earns its place: purpose, operation, use case, and output. There is no fluff or repetition.

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 4 parameters, no output schema, and moderate complexity, the description covers the core aspects: what it does, how it works (probe, rank, surface), when to use it, and what it returns. The lack of an output schema is compensated by explicitly listing returned fields (score, confidence, signal density).

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema—it references 'your brand + N competitors' but the schema already explains first entry as subject. No additional parameter semantics are provided.

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 with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling ai_visibility_check by focusing on multi-entity comparison and ranking, and from compare_entities by mentioning AI visibility scoring.

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

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

The description provides clear context for when to use the tool, explicitly stating it is 'Useful for competitive AI-marketing audits' and giving an example query. However, it does not explicitly mention when not to use it or provide alternatives, though it implicitly contrasts with ai_visibility_check by describing probing behavior.

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

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

Even though annotations already declare readOnlyHint and idempotentHint, the description adds valuable behavioral detail: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and the sources_failed field will list timeout issues while the rest still returns. This goes 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 information-dense but every sentence earns its place: main purpose, fan-out targets, exact use cases, ecosystem limitation, partial failure behavior, latency, and return fields. It is front-loaded with the core purpose and contains no fluff.

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

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

Given there is no output schema, the description thoroughly lists the full return structure (summary block fields, per-advisory detail, links, alternative versions) and covers partial failure behavior, latency, and ecosystem constraints. This makes it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% for both parameters, and the schema already explains package name (including scoped packages) and version defaulting. The description does not add parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ("check") and resource (npm package), and distinguishes it from siblings by describing the composite fan-out across deps.dev and bundlephobia. It answers the exact question "should I add this npm package to my project".

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 when-to-use guidance is given: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'". It also excludes non-NPM ecosystems and directs the user to deps.dev:version directly for PyPI/Maven/Cargo/Go, providing clear 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, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations: the bundled map of 150 hubs, the behavior of returning all primary airports for multi-airport cities, and the limitation that city lookup only works for bundled airports.

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

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

The description is two sentences, with the first stating input types and the second explaining scope and limitation. All sentences earn their place, with no fluff or redundancy, and the key information 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 output schema exists and annotations cover safety, the description is complete: it explains input types, behavior, scope, limitations, and an alternative for non-bundled airports. The tool is simple (1 param) and the description fully covers usage context.

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

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

Schema coverage is 100% (query described as city or IATA code with examples), so baseline is 3. The description adds meaning by explaining that city lookup relies on a bundled map of 150 top hubs and that multi-airport cities return all primary ones, which is not in the schema.

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

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

The description uses a specific verb ('look up') and resource ('airport'), and clearly distinguishes the tool's scope by specifying input modes (city name or IATA code) and the bundled map limitation. This separates it from sibling tools like get_airport or more comprehensive search alternatives by explicitly noting the top-150-hub limitation.

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 states when to use the tool: for city name or IATA code lookups within the bundled map of 150 hubs. It also provides when-not guidance: for airports not in the bundle, pass an IATA code or use the aviationstack pack for full-text name/country search, naming an alternative.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description reveals significant behavioral details: the embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), length cap (200K chars), truncation flagging, and the presence of offsets for verification. This adds substantial context beyond what annotations provide and contradicts nothing.

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

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

The description is longer than two sentences but remains focused and front-loaded with the core purpose. Every sentence adds value, from the use case to the technical details. The degree of implementation detail is slightly more than necessary, but it is efficiently packed and logically ordered.

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

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

With no output schema, the description sufficiently explains return values (passages with character offsets and similarity scores). It covers the input requirement (text and query), the use case context, the pairing with sibling tools, and edge behavior (truncation). This makes the tool's behavior fully transparent 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 description coverage is 100%, so the baseline is 3. The description adds some context (e.g., text examples like SEC 10-K body, query examples), but these largely mirror the schema descriptions. The description does not introduce new parameter-level details beyond the schema, so a 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 a specific verb+resource: "Semantic search INSIDE a fetched record." It includes concrete outputs (top-N passages with character offsets and similarity scores) and distinguishes from siblings like ask_pipeworx_grounded by explaining its role in a workflow (fetch first, then search inside).

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 this tool: "Use when the record is too big to cram into the prompt." It also names an alternative and pairing: "Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document." This provides both when and 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?

Given the annotations already declare readOnlyHint=false, openWorldHint=true, etc., the description adds valuable behavior context: the OAuth account requirement, phone verification for SMS, and a 10/day cap. It also discloses the return value (subscription id). These details go beyond what the annotations provide, though they do not cover every edge case (e.g., webhook auto-disabling, which is in 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 dense but every sentence serves a purpose: purpose, return value, prerequisite, supported types with examples, and delivery channels. It is front-loaded with the main action and structured logically, with no filler or redundant content.

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

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

Despite having no output schema, the description states the return value (subscription id) and comprehensively covers the main behavior: types, parameters, delivery options, and constraints. The webhook details are left to the schema, which is acceptable given the schema's richness. The tool's complexity is well addressed.

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

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

The schema already provides 100% parameter coverage with detailed type-specific examples. The description adds interpretive meaning beyond the schema, such as explaining that items:["5.02"] means an officer change in an 8-K filing, and clarifying the semantics of the delivery feedback fee. This enriches the raw schema, but the schema itself is already strong, so the added value is moderate.

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 verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It lists supported subscription types and distinguishes this tool from siblings like list_subscriptions and unsubscribe by focusing on creation and returning a new subscription id.

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 provides clear context for use (proactive monitoring), explicitly states a prerequisite ('Requires a Pipeworx OAuth account') and a limitation ('anonymous + BYO cannot persist subscriptions'), and mentions an alternative for consuming the feed via recent_alerts or a GET endpoint. However, it does not explicitly name alternative tools for managing subscriptions (e.g., list_subscriptions), so it falls slightly short of full explicit when-not/alternatives guidance.

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

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

The annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context beyond these: it explains that it draws from a live catalog, returns a specific output structure (category-bucketed questions with tool/argument shapes), and that passing no arguments gives the full spread while passing a topic focuses results. This goes beyond what the annotations provide, though it doesn't go into exhaustive detail about response formatting.

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

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

The description is a single dense paragraph but every sentence contributes useful information: purpose, usage context, parameter behavior, and return value. It's somewhat long, but not wasteful. The structure could be improved with bullets, but the current format is still scannable and information-rich.

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 (0 required parameters, 1 optional) and the absence of an output schema, the description fully covers what it does, when to use it, how to call it, and what to expect in return. It explains the categories, the optional `topic` parameter, and the fact that it draws from a live catalog. No gaps remain.

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 provides 100% coverage for the single parameter `topic`, listing the exact valid values and explaining that omitting it yields a cross-category spread. The description adds only a brief example ('e.g. "finance", "pharma", "betting"'), which doesn't significantly enhance the schema's meaning. Thus, a 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?

The description clearly states the tool's function: it returns category-bucketed example questions with the exact tool and argument shape to answer them. It explicitly identifies itself as the onboarding entry point ('What can I ask Pipeworx?') and distinguishes it from siblings by saying 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also mentions alternatives by naming the meta-tools (ask_pipeworx, entity_profile, compare_entities) as things you'll learn to call. However, it doesn't explicitly state when not to use this tool, so it stops 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.

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

The description discloses that the row is deactivated rather than deleted, which adds meaning beyond destructiveHint=false in annotations. It also clarifies ownership enforcement. This goes beyond the minimal annotation context, though it doesn't cover idempotency or error behavior.

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

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

Two sentences with no redundancy. The first sentence states the action, the second provides crucial behavioral details. Every word 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?

For a single-parameter tool with available annotations, the description covers the core behavior, ownership rules, and post-cancel state. It doesn't mention return values or error cases, but these are less critical for a simple cancel operation.

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 describes the id parameter (100% coverage), including its source from subscribe. The description simply says 'by id' without adding new syntax or format details, so it meets the baseline for high 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 begins with 'Cancel a subscription by id,' which clearly identifies the action and target. It distinguishes from siblings like subscribe and list_subscriptions by describing the cancellation semantics and ownership constraint.

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 (to cancel a subscription) and includes important constraints (ownership enforcement, soft-delete effect). However, it doesn't explicitly mention alternatives or when not to use it, which would push it to 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 declare read-only, idempotent, and open-world behavior; the description adds substantial context beyond these: the two pipeline paths (SEC EDGAR/XBRL for financial vs grounded pipeline for others), the full verdict taxonomy, and the crucial warning that could_not_verify is a failed-check signal, not evidence for/against the claim, while unsupported means no source coverage. This prevents serious misinterpretation of results.

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

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

The description is information-dense yet well-organized: trigger phrases, core purpose, usage condition, pipeline behavior, return values, and a critical caller caveat. Every sentence earns its place, and the structure front-loads the most important operational detail early for agent guidance.

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

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

With no output schema, the description fully covers the return contract: verdict values, grounded/structured actual value with pipeworx:// citation, and reasoning. It also explains the two routing paths and failure semantics, making the tool self-contained for an agent to invoke and interpret results correctly. No important gap remains.

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, so the baseline is 3. The description adds value by explaining that tolerance_pct overrides the claim-wording default, is capped at 5, and should be set to 1–2 for hallucination detection. It also provides claim examples that illustrate what natural-language claims look like, aiding parameter selection.

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

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

The description explicitly states the tool's function: natural-language claim verification against authoritative sources, with concrete trigger phrases like "fact check" and "verify the claim that…". It clearly distinguishes itself from sibling research/search tools by focusing on verdict generation for factual claims, not open-ended 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 clear usage context: "Use whenever the agent needs to check whether something a user said is factually correct." It also explains the routing between financial and non-financial claims and notes it replaces multi-step manual verification. However, it lacks explicit external alternatives or when-not-to-use conditions, so it stops short of full exclusion guidance.

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