Hgnc

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds transparency about cost (BYO key for Anthropic) and return structure (per-model score, confidence, signals, raw_response + combined view), which is valuable 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 four sentences, front-loaded with the core action, and every sentence adds value. No redundancy or fluff.

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

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

Given the rich annotations and high schema coverage, the description is adequately complete. It explains the return format despite lacking an output schema. Could mention pagination or response size, but not critical for 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?

With 100% schema coverage, baseline is 3. The description enhances meaning by clarifying the default model ('workers-ai' free), condition for _apiKey (only if 'anthropic' in models), and purpose of 'context' (disambiguation). This adds functional nuance 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 uses specific verbs ('probe', 'score') and clearly identifies the resource (LLMs' knowledge about a business/brand/product/topic) and the output (visibility score 0-100). It distinguishes itself from siblings by focusing on AI visibility scoring, which is unique among the listed tools.

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

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

The description lists relevant use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly state when NOT to use this tool or suggest alternatives among siblings. While context is provided, exclusion criteria are missing.

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 non-destructive behavior, so the description's added value is the routing behavior, the 5,743-tool scope, and the promise of stable citation URIs. This contextualizes what actually happens when the tool is invoked, though it does not discuss limitations like latency or routing failures.

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 logically organized: preference statement, core mechanism, usage patterns, examples, and alternatives. It is front-loaded with the most important guidance. Some redundancy exists in the long list of trigger phrases and examples, which could be trimmed without losing value.

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

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

For a complex meta-routing tool with no output schema, the description covers the essential context: what types of questions to route here, what the tool returns (structured answer with citation URIs), how to phrase input, and when to use other tools instead. Nothing critical is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%: the schema fully documents the single required 'question' parameter, its natural-language semantics, and all aliases (query, q, prompt, text, input). The description adds query examples and domain coverage, but no parameter-specific meaning beyond what the schema already 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 clearly states the tool's core function: it routes a natural-language question to the right one of 5,743 tools across 1,500 verified sources, fills arguments, and returns a structured answer with pipeworx:// citation URIs. This distinguishes it from web search and from siblings like ask_pipeworx_grounded and deep_research, which are explicitly named.

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

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

The description gives explicit when-to-use guidance: prefer it over web search for factual/current/structured-data questions, and 'start here for most questions.' It also names alternatives and the conditions for escalating: ask_pipeworx_grounded for a single hallucination-resistant answer with evidence, and deep_research for broad multi-part questions.

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, the description openly discloses the experimental nature, that no candidate is currently active, that behavior currently matches ask_pipeworx exactly, and that outputs are used for comparison to decide merges. It also explicitly warns there is no fallback, giving the agent an accurate model of expected 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 longer than average but front-loads the critical identity and usage information. Every sentence contributes useful context, though some redundancy exists between 'identical universal router' and enumerating the same tools, arguments, and response shape.

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

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

The description is complete for an experimental routing tool: it covers behavior, current state, usage context, alternatives, and response shape via reference to ask_pipeworx. It does not fully stand alone because it depends on the sibling tool for detailed invocation and response semantics, but the explicit 'identical to ask_pipeworx' statement mitigates this.

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 already has a clear aliasing description. The description adds only 'same arguments' as a general statement, which does not meaningfully supplement the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description identifies the tool as a beta version of ask_pipeworx and as an identical universal router with the same 5,743 tools, arguments, and response shape, which makes the core action clear. It distinguishes itself from the stable sibling and defines its experimental role, though it relies on the sibling's name for the primary 'ask/route' verb.

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

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

It explicitly says when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router, implying the alternative, and states it has no fallback and is a full working router, removing ambiguity about whether it's a stub.

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 the description enriches this by detailing the exact success return shape, explicit refusal reasons, the verbatim-evidence policy, and the extra LLM call cost. It clearly explains what happens when data doesn't directly answer, which is critical behavioral context beyond any 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?

The description is dense but every sentence earns its place: mode, mechanism, output contract, refusal contract, eligible use cases, and cost trade-off. It is front-loaded with the defining trait and uses compact structured notation for return values.

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

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

For a read-only grounded-answer tool with no output schema, the description is remarkably complete: it specifies the answer object, evidence behavior, confidence/source/fetched_at fields, refusal reasons, and comparison to the sibling tool. Nothing necessary for correct invocation or interpretation is missing.

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

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

The schema already covers 100% of parameters, including a clear description of 'question' and all six aliases. The tool description adds no additional parameter-level meaning, so the schema-heavy 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 a specific, distinctive purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly differentiates itself from ask_pipeworx by describing its grounded-extraction behavior and evidence-citing output, so an agent can tell them apart without inspecting schemas.

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

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

Usage guidance is explicit and actionable: use it 'whenever an answer will be quoted, cited, or acted on' and facts must not be invented, with examples like financial verdicts and legal claims. It also names the alternative and the condition for preferring it: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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, etc.), the description extensively details behavior: fan-out patterns per category, response shapes, evidence field structure, market_match_confidence levels, parent event extraction, news fallback mechanisms, safety conditions (low-confidence short-circuit, closed market handling), and resolution-rule risk. This far exceeds required disclosure.

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 quite long and dense, with multiple paragraphs and technical details. While well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), it could be trimmed by moving some details to external docs or examples. The front-loaded opening is good, but the length makes it less concise than ideal.

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 covers return values (market, analysis, evidence, resolver contract, parent_event, news fields) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). It leaves no significant gap for an agent to understand what to expect or how to handle special cases.

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% (all three parameters described in schema). The description adds significant value by explaining the 'market' parameter accepts slug/URL/question text, provides examples, clarifies 'depth' (quick vs thorough), and explains 'include_raw' effects on response size. This goes beyond the schema descriptions.

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

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

The description opens with a clear verb+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies three input formats (slug, URL, question text) and explicitly lists use cases ('should I bet on X'). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on different tasks.

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

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

The description explicitly states when to use this tool ('Use for "should I bet on X"...') and provides context about what it does. However, it does not explicitly name alternative tools or give clear 'when not to use' guidance, missing the chance to fully differentiate from siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context: it specifies the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), mentions off-calendar fiscal year handling, and notes sorted results. This goes 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 efficient but somewhat verbose. It front-loads example queries and key instructions, earning its length with dense information. Minor redundancy like 'side-by-side comparison' and 'parallel call' is acceptable.

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 (two entity types, sorting, citation URIs), the description is highly complete. It explains what data is pulled for each type, how results are sorted, and mentions the response includes paired data and citation URIs. No output schema is present, but the description adequately covers return format.

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

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

Schema coverage is 100% with both parameters described. The description adds semantic value by explaining that 'values' expects tickers/CIKs for companies and drug names for drugs, and provides examples (e.g., ['AAPL','MSFT']). This enriches the schema definition.

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 'compare' and the resource 'entities' (companies or drugs). It provides concrete natural language examples and distinguishes itself as a side-by-side comparison tool, differentiating it from sibling tools like entity_profile.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear when-to-use guidance. It details the two entity types (company/drug) and their respective use cases, but lacks explicit when-not scenarios.

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

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

Annotations already mark this read-only, idempotent, and non-destructive, but the description adds substantial behavioral detail: account and paid-tier requirements, parallel facet routing, gaps[] for unanswered facets, contradictions[] only on standard/thorough, citation_uri only when fetchable, semantic excerpting of large records, and latency expectations. No contradiction with annotations.

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

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

The description is dense and front-loaded with the most critical gate (account requirement and alternative), and every major topic gets covered. It is somewhat long and contains mild redundancy around the multi-source/decomposition concept, but the length is mostly justified given no output schema and 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?

With no output schema, the description correctly shoulders the burden of explaining return values: findings packet, verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and citation fetchability. It also covers account requirements, depth behavior, and timing, leaving no material gap for an agent deciding whether and how to call 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%, but the description adds meaningful depth semantics beyond the schema: it maps each depth value to hops, gap-recovery behavior, and the contradictions[] scan, and clarifies that 'question' is natural-language and broad/multi-part by design. This materially improves an agent's ability to choose parameters.

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

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

The description names a specific action ('research'), a concrete resource (Pipeworx's 1500 structured data sources), and a clear mechanism (decompose into facets, route to tools in parallel, return a findings packet). It also explicitly contrasts itself with open-web search and with ask_pipeworx, making sibling differentiation immediate.

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 ('broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx instead'), including the account/tier gate. Saying 'this is NOT open-web search' and naming the alternative tool removes ambiguity about tool selection.

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

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

Annotations already set readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results include 'full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed,' which provides practical behavioral insight 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 relatively concise given the information it conveys. It is front-loaded with the core purpose and structured to list examples. Could be slightly shorter, but every sentence serves a purpose.

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

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

Despite no output schema, the description fully explains the return value: 'names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' It also covers when to use it, making it contextually complete.

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

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

Schema description coverage is 100%. The description explains the query parameter and its aliases, and implies a limit via 'top-N,' but does not detail the limit parameter. This meets baseline expectations but adds marginal value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and explains it returns top-N tools with schemas, ready to call. This differentiates it from sibling tools like search_within or deep_research.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set.' Provides usage context with examples. While it doesn't explicitly state when not to use it, the guidance is clear and contextually complete.

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds rich behavioral context beyond them: the soft-fail for USPTO patents, the GDELT→GNews fallback, the expectation-setting that fda_products will legitimately be empty for small-molecule companies ('that is expected, not a failure'), and the 'empty section is a real no data, not a bug' semantics for sources_used/sources_failed. It also discloses the resolved:false + notes behavior for private companies instead of a bare failure. This is exemplary edge-case disclosure.

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

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

The description is front-loaded with trigger phrasings and the core purpose, and nearly every sentence carries information. However, the return-value enumeration is one massive run-on sentence that is hard to scan, and the eight example phrasings at the start are somewhat redundant. It is comprehensive but structurally dense; a list or shorter clauses would improve parseability without losing content.

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

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

For a complex multi-source fan-out tool with no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: the source list, the return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, contracts, fda_products, hiring, news, LEI), the sources_used/sources_failed semantics, and both edge cases (private companies, expected-empty sections). Nothing an agent needs to correctly set expectations is missing.

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

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

Schema coverage is 100%, so the baseline is 3; both parameters already have descriptive schema text. The description adds value beyond that: concrete accepted values ('AAPL', '0000320193', 'Moderna'), the explicit statement that type values are interchangeable, name-resolution behavior via SEC EDGAR, and the resolved_from/resolved_to output behavior when a name is passed. The examples and resolution semantics genuinely aid 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 opens with concrete user phrasings ('Tell me about X', 'brief me on Tesla', 'everything you know about $TICKER') followed by a precise statement of function: 'full cross-source profile of a US public company in ONE parallel call'. It specifies the resource (US public company), the action (cross-source profile), and the scope (SEC, XBRL, patents, contracts, FDA, H-1B, news, GLEIF), making it unmistakable what this tool does and how it differs from a narrow single-source lookup.

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

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

Gives explicit routing guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This states the condition (holistic view) and what to prefer it over. However, it does not name specific sibling tools (e.g., resolve_entity for a bare CIK lookup, compare_entities for comparisons), so an agent must infer the full boundary against the 30+ siblings rather than being told.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false, so the description correct that this is a destructive write operation. The term 'delete' is consistent. No additional behavioral details about idempotency or missing keys are provided, but annotations already cover the key aspects.

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 efficient sentences: one for the core action, one for usage context. No wasted words. Front-loads the purpose. Ideal conciseness.

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 deletion tool with one parameter and no output schema, the description is sufficiently complete. It covers purpose, usage context, and sibling relationships. Minor omission: no mention of return value or error behavior, but this is acceptable for such a straightforward 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?

Schema coverage is 100% and the description adds no extra parameter meaning beyond the schema's 'Memory key to delete'. Baseline 3 is appropriate as the schema already fully documents the single parameter.

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

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

The description clearly states 'Delete a previously stored memory by key.' The verb 'delete' is specific and the resource is precisely identified. This distinguishes it effectively from siblings like 'remember' and 'recall'.

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

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

Explicit guidance is given: 'Use when context is stale, the task is done, or you want to clear sensitive data...' and it recommends pairing with siblings 'remember' and 'recall', leaving no ambiguity about when to use this tool.

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

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

Beyond annotations (readOnly, idempotent, etc.), description adds that it fetches the page, extracts title/description/key links, and emits standard format. Output is a single text blob, ready to deploy. Fully transparent.

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

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

Three sentences, front-loaded with main purpose. Each sentence adds value. Could be slightly more concise but overall efficient.

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

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

With two parameters, rich annotations, and no output schema, the description covers function, output, and use cases. Complete for a simple read‑only tool.

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

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

Schema coverage is 100%, both parameters are described. Description adds no new information beyond what is in the schema (e.g., default 25, max 50 is already in schema). 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?

Clearly states the tool generates an llms.txt file for a given URL, with specific details about extraction and output format. Differentiates from sibling tools by describing its specific 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?

Provides explicit use cases (getting a client's site indexed, drafting for own project, auditing competitor). Does not explicitly contrast with siblings or mention when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds marginal value by listing return fields and indicating 'Keyless', but does not elaborate on behavioral nuances 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 a single sentence that efficiently conveys purpose and return data. It is slightly lengthy due to enumeration of fields, but not verbose. 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 tool's simplicity (one parameter, no output schema, and thorough annotations), the description is fully adequate. It provides all necessary context for an agent to select and invoke the tool correctly.

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

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

The input schema already describes the single parameter with examples and coverage at 100%. The description confirms the parameter's purpose but adds no additional semantic value beyond the schema.

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

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

The description clearly states the tool performs an exact lookup of a human gene by its official HGNC symbol, specifying what is returned. It distinguishes itself from the sibling tool search_genes by emphasizing exact lookup vs. fragment search.

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

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

The description explicitly instructs to use search_genes first when unsure of the exact symbol or when having only a name fragment. This provides clear guidance on when to use this tool versus an alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds specific return fields and the optional include_inactive parameter, which is not contradicted by 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, front-loading the core purpose and usage, with 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?

Given a single optional parameter and no output schema, the description adequately lists return fields and provides usage context. It is complete enough for a simple list tool with strong 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?

With 100% schema coverage, the baseline is 3. The description adds minimal meaning beyond the schema: it mentions 'active subscriptions' and 'cancelled subscriptions' which align with the include_inactive boolean, but does not elaborate further.

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: 'List the caller's active subscriptions'. It also specifies the return fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from siblings like 'subscribe' and 'unsubscribe'.

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

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

The description provides guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies when to use but does not explicitly state when not to use or mention alternatives, though sibling tools cover related actions.

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

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

Annotations provide no safety hints (all false), so the description carries the full burden. It discloses key behavioral traits: 'Filing without an account returns a claim_token', the ability to poll status with that token, rate limiting ('Rate-limited to 5 per identifier per day'), and cost ('Free; doesn't count against your tool-call quota'). It even explains the team's reading cadence and roadmap impact.

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 earns its place: purpose, use cases, exclusions, token mechanics, rate limits, and cost. It is front-loaded with the core action and branches into important caveats. While longer than average, the complexity of the tool justifies the length.

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

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

For a tool with no output schema and four parameters, the description fully covers the context needed to invoke it correctly: when to use it, what to include in the message, how to use claim_token for follow-up, rate limits, and quota behavior. It even notes the team reads digests daily and that feedback influences roadmap, which helps the agent understand the tool's impact.

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

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

The input schema already covers all parameters comprehensively (100% coverage), so the baseline is 3. The description adds beyond the schema by explaining the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructing users to describe issues in terms of Pipeworx tools rather than pasting end-user prompts. This enriches parameter understanding without duplicating schema content.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies the resource (Pipeworx team) and the action (sending feedback), and distinguishes it from sibling tools like ask_pipeworx by focusing on reporting issues rather than asking 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 provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This 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 readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: cache intervals (5min-1h depending on window), data source (CF analytics-engine), and privacy (no PII). 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 a single paragraph that front-loads purpose and use cases, then adds behavior/parameters. Every sentence adds value with no fluff.

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

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

For a read-only, cached trending tool with one parameter and rich annotations, the description covers all needed aspects: what it returns, when to use, caching behavior, and data source. No output schema is needed since the description explains returned structure (top tools, top packs, call volume).

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 described enum. The description adds practical guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' and notes the default (24h).

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

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

The description opens with a clear verb+resource: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume...'. It distinguishes itself from sibling tools (many search/ask tools) by focusing on trending usage aggregation.

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

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

Three specific use cases are provided: discovering hot data sources, confirming canonical tool, and checking alignment. It does not explicitly say when not to use, but the use cases are clear and helpful.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are baseline, but description adds rich behavioral detail: monotonicity checks, partition_sum, Jaccard similarity threshold (≥0.30), placeholder filter, fill check with theoretical vs realizable edge. All behaviors are disclosed 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 long but well-structured: starts with a summary, then breaks into modes with clear headings. Every sentence adds necessary detail. Could be slightly tighter by removing some explanatory asides (e.g., '— should ≈1; deviations >3pp emit...') but overall appropriately sized for the complexity.

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

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

Given no output schema, the description fully explains the response structure (opportunities array with fields, partition_check object). It covers all modes, edge cases (placeholder filter, similarity check), and fallback behavior (fill check). No gaps remain for the agent to guess.

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 short descriptions. The description adds significant meaning: explains event mode accepts full URLs, topic mode searches related events, and what each mode does. However, for such a complex tool, the description could add even more parameter-specific examples or edge cases. Still, it adds good value.

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

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

Description starts with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', a specific verb+resource+scope. It clearly distinguishes three modes (no-arg, event, topic) and notes when to use each, though does not explicitly differentiate 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?

Explicit guidance: 'Call with NO args for a trending_scan...', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan'. Provides examples of slugs and seed questions. Also warns when not to trade (realizable_edge_pp ≤ 0) and suggests polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: internal model details (FRED log-returns, GDELT volume ratio, favorite-longshot bias correction), caching (1h at KV level), diagnostic information (_diagnostics with funnel counters), and edge computation specifics (edge_pp_net, slippage, Kelly calculations). This significantly exceeds annotation coverage.

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

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

The description is long but well-structured: purpose, model segments, opportunity fields, knobs, response structure, and caching. Each section earns its place given the tool's complexity. Front-loaded with purpose and segments, though the density may challenge quick scanning.

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

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

Given 9 parameters, no output schema, and complex nested response, the description is remarkably complete. It details each segment's logic, response top-level fields (by_segment, fed_candidates, _diagnostics), tradeable-edge knobs, and caching behavior. Even without output schema, the agent understands exactly what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context for several parameters: explains why min_kelly is per-leg, distinguishes min_partition_leg_kelly from min_kelly, provides examples and rationale for defaults (e.g., slippage_pp default 0.3 with explanation). This adds value beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the unique value proposition ('what should I bet on today') and distinguishes from sibling tools by describing the distinct segments (model_driven, structural_arbitrage, concentrated_longshot) and internal logic.

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 indicates when to use this tool (discover opportunities without paging hundreds of markets) and provides guidance via tradeable-edge knobs (min_liquidity, max_spread_pp) and diagnostics for empty segments. However, it does not explicitly mention when not to use it or compare to specific siblings, though the detailed functionality implies appropriate use cases.

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

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

The description provides extensive behavioral details beyond the annotations: it describes the output structure (tracked[], expired[], snapshot_dates[]), explains computed fields like trend and decay_pp_per_day, and notes data limitations (60-day TTL, daily closes, not intraday). This fully informs the agent about the tool's 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 somewhat lengthy but well-structured: it starts with the core question, then details response fields, then limits. Every sentence adds value, though it could be slightly more compact without losing clarity.

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

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

With no output schema, the description fully specifies the return format and fields. It covers tracked opportunities with time-series, expired opportunities with lifespan, and snapshot dates, plus data limits and interpretation notes. This 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 description coverage is 100%, so the schema already documents both parameters. The description repeats the defaults and clamping behavior but adds no new semantic information beyond what the schema provides. Thus 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: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from siblings like polymarket_edges by focusing on the time-based nature of edges, answering 'how long has this edge existed and is it shrinking?'

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

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

The description explains when to use this tool: when you need to know edge age and decay, noting that a fresh wide edge and an old wide edge are different trades. It does not explicitly list when not to use it or compare to alternatives, but the context with sibling tool names gives implicit guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it checks live order book depth, returns fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and per-leg details. It also explains the difference between single-market and basket modes. 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 well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and front-loads the core purpose. Each sentence adds value without redundancy. Despite being detailed, it remains focused and efficient, earning its length.

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

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

Given the tool's complexity (two modes, four parameters, no output schema), the description is highly complete. It explains both modes, return fields, usage thresholds, and warnings. Without an output schema, the description effectively documents return values, making it self-sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by providing default values for side and size_usd, clarifying interpretation for buys vs sells and basket mode, and explaining the 'auto' default for side in basket mode. This adds context and helps agents understand parameter usage.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two modes (single-market and basket) and differentiates from siblings like polymarket_arbitrage by explicitly stating when to use this tool before acting on signals.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about thin books and partial fills converting arb to directional risk, helping agents decide when to invoke this tool.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses deeply relevant behavior: matching is keyword/word-overlap based rather than source-verified, unknown legs are never paired, temporal_alignment null does not mean aligned, compatibility codes can be non-empty even with matched pairs, and spreads are gross because Kalshi fees are not modeled. This is exceptional transparency for a tool with no output 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 long and dense, but almost every sentence earns its place given the tool's complex safety semantics and the absence of an output schema. It could be better structured with bullet points and more restrained capitalization, and it risks overwhelming an agent, but it is front-loaded with purpose and modes before the detailed caveats.

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

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

With no output schema and a multi-field response including raw prices, spread entries, safety codes, skipped counters, flags, temporal alignment, and a fees note, the description covers essentially everything an agent needs to interpret results safely. It also explains the semantics of null temporal_alignment and the non-tradeable gross-spread caveat, making it complete for a complex read-only tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds substantial meaning: topic is a pre-mapped macro shortcut, the two explicit parameters override the topic-mapped side, and both modes execute the identical token-overlap matcher with the same disclosures. The description also explains the semantics of pairing modes far beyond the schema's per-parameter text.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, which is a specific resource and scope. It does not explicitly differentiate itself from sibling tools like polymarket_arbitrage or polymarket_edges, so an agent would need to infer why to pick this one over those alternatives.

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, including two modes (topic shortcuts vs explicit ticker/slug pairings) and emphasizes that both modes run the same matcher. It also warns that most pre-mapped topics currently return compatibility_warning and that pre-mapped does not mean tradeable. It does not explicitly state when to use this tool over sibling arbitrage/edge tools.

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

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

Annotations indicate read-only, non-destructive, idempotent behavior. Description adds scoping detail (by identifier) and confirms retrieval action, which aligns with annotations. No contradictions.

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

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

Three concise sentences with the core action front-loaded. Every sentence adds value: retrieval action, usage examples, scoping, and pairing with siblings.

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

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

Adequately covers the tool's behavior given its simplicity, annotations, and single parameter. No output schema needed; the purpose and scope are clear.

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

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

Schema covers 100% of the single optional parameter. Description adds the crucial detail that omitting the key lists all saved keys, which is not in the schema description.

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

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

Clearly states it retrieves a saved value by key or lists all keys if omitted. Distinguishes from sibling tools remember and forget by using specific verbs and mentioning pairing.

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 describes when to use: to look up previously stored context without re-deriving. Mentions pairing with remember and forget, but does not state when not to use it.

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

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

Discloses return fields (source, citation_uri, payload) and the mark_read side effect on subsequent calls. Adds context beyond annotations, though the idempotentHint may be slightly contradicted by mark_read's state change.

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

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

Front-loaded with main purpose, five sentences long. Efficient but includes a trailing sentence about alternative GET that could be tighter. No wasted words.

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

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

No output schema, but description covers return fields, all parameters, polling behavior, and alternative access. Comprehensive for a read-oriented tool.

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

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

Schema coverage is 100%, so baseline 3. Description enriches parameters by explaining type filter scope, since format, and mark_read behavior, adding value beyond schema descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed' with a specific verb and resource. It distinguishes from sibling tools like list_subscriptions by focusing on alert events.

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?

Mentions polling is fine, provides an alternative GET endpoint, and explains filter options. Lacks explicit when-not-to-use against siblings, but context is clear enough.

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

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

The description explains the tool fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO with soft-fail behavior. It states it makes 'ONE parallel call' and returns structured data with citations. These details go beyond the annotations (readOnlyHint, etc.), which are already accurate.

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

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

The description is detailed but efficient, front-loading with example queries and structuring logically. Every sentence contributes meaning. It could be slightly more condensed but is not overly verbose.

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

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

Given the complexity (multiple sources, fallback, no output schema), the description is complete. It specifies return format (changes[], total_changes, citation URIs), mentions limitations (USPTO soft-fail), and contrasts with 'entity_profile'. 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?

All parameters are described in the schema (100% coverage). The description adds context: 'since' formatting (ISO vs relative) and recommendations, and examples for 'value'. This adds moderate 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 that the tool provides a change feed for a company over a recent time window, with examples of natural language queries. It distinguishes itself from the sibling tool 'entity_profile' by explicitly stating when to use the alternative.

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 examples of when to use ('what's new', 'latest on Y') and recommends 'entity_profile' for static profiles. It offers guidance on the 'since' parameter with typical values like '30d'. However, it does not exhaustively list all non-use cases or 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?

Adds key behavioral details beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour TTL for anonymous sessions. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

Four sentences, front-loaded with purpose, no wasted words. Efficiently conveys all necessary information.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers behavioral aspects, usage guidance, and pairing with related tools. Complete for effective use.

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

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

Schema coverage is 100% with good descriptions. The description adds context about the purpose of key-value pairs and gives examples of what to store, 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?

Description clearly states the verb 'save', the resource 'data', and the scope 'across this conversation or across sessions'. It distinguishes from sibling tools by 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?

Explicitly says 'Use when you discover something worth carrying forward...' and explains why (so you don't have to look it up again). Does not explicitly state when not to use, but context is clear.

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

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

Beyond the read-only/idempotent annotations, the description discloses important behavior: it returns figi_candidates when multiple instruments match, marks unresolved identifiers explicitly, labels identifiers by source, and degrades gracefully when GLEIF or OpenFIGI is unavailable. This gives the agent a clear model of expected results and failure modes.

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 and front-loaded, but it is a single sprawling paragraph with heavy nesting, parentheticals, and at least one garbled clause ('more than one instrument it asserts nothing...'). The content is mostly valuable, but the structure makes it harder to parse than it should be.

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 compensates well by describing return content: figi_candidates, unresolved, source labels, RxCUI citation, and fallback behavior. It also covers acceptable inputs, supported types, and the internal cascade effect. An agent has enough context to invoke this tool correctly in most realistic scenarios.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial value. It explains accepted input formats for company and drug types, gives realistic examples, and warns against passing full noun phrases like 'NEW YORK ST DORM AUTH revenue bonds' instead of the entity name. This is far more actionable than 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 the tool's function: resolving a user-spoken name to canonical identifiers such as CIK, ticker, LEI, FIGI, and RxCUI. It names the supported entity types and gives concrete examples. It does not explicitly differentiate itself from sibling tools like resolve_xref, though the 'identifiers other tools require as input' phrasing implies its role.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains which input forms are accepted and covers edge cases like non-equity instruments. However, it never names an alternative tool or states when not to use this one, so it stops short of full when/when-not 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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context: it is 'Keyless' (no auth needed), returns the same full record as get_gene (clarifies output format without needing an output schema), and the term 'Reverse-lookup' sets clear behavioral expectations. No contradiction with annotations.

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

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

The description is extremely concise: one sentence for purpose, a brief example, a list of accepted IDs, and the keyless note. Every sentence adds value. It is front-loaded with the core action ('Reverse-lookup'). No wasted words.

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

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

Given the tool's simplicity (2 parameters, no nested objects, no output schema), the description covers input types, the mapping concept, output shape (same as get_gene), and authentication (keyless). It does not detail the output structure, but referencing get_gene leverages existing knowledge. Slightly incomplete for agents unfamiliar with get_gene, but adequate overall.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds concrete examples (e.g., Entrez '672', Ensembl 'ENSG00000012048') but does not explain the meaning beyond what the schema already provides. It reinforces that the ID is external, which is helpful but not essential. 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 function: 'Reverse-lookup: map an external database id to its canonical HGNC gene.' It provides a concrete example ('What gene is Entrez 672?' -> BRCA1) and lists all supported ID types. It distinguishes itself from sibling 'get_gene' by noting it returns the same record, implying get_gene uses canonical symbols instead.

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 specifies when to use the tool (when you have an external ID and need the HGNC gene) and lists all accepted ID types. It mentions 'Keyless' indicating no authentication overhead. However, it does not explicitly state when not to use it or name alternative tools, though the sibling list and mention of get_gene provide implicit 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 cover safety and idempotency. Description adds mechanics (calls ai_visibility_check, ranks results) but no new behavioral warnings. Adequately transparent but not exceptional.

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 core function, then use case and output. No redundancy, every sentence earns its place.

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

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

With no output schema, description provides output details (ranked list with score, confidence, signal density). Sufficient for agent to understand use and behavior. Minor gap: error handling or rate limits not mentioned.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context beyond schema: first entity as subject, models options with api key requirement, context for disambiguation. Adds meaningful value.

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

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

The description clearly states it compares AI visibility across multiple entities and ranks them, with a specific use case (competitive audits). It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic comparison).

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 usefulness for competitive AI-marketing audits and gives a concrete example question. Implies when to use versus single-entity check, but lacks explicit exclusion scenarios.

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

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

Annotations already indicate readOnly, idempotent, openWorld, non-destructive. Description adds behavioral context: partial failures, bundlephobia latency (5-30s), and sources_failed listing.

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

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

Description is thorough but slightly long. Every sentence adds value; front-loaded with purpose. Could be more concise but not wasteful.

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

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

Covers all necessary aspects: what it does, input parameters, return fields, error handling, fallback, limitations. Compensates for lack of output schema.

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

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

Schema already describes both parameters. Description adds meaning: scoped packages accepted, default version behavior (latest), and implicit format expectations.

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

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

The description clearly specifies the composite check for adding npm packages, covering safety, popularity, and size, and distinguishes from siblings by noting ecosystem scope and alternative 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?

Explicitly states when to use (agent asks about package safety/popularity/size) and when not to use (non-npm ecosystems point to deps.dev:version directly).

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 safe, idempotent, read-only behavior. Description adds that it returns lightweight matches ranked by score and is keyless, providing useful context beyond annotations.

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

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

Two efficient sentences with no wasted words. Front-loaded with purpose and examples.

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

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

No output schema, but description explains return fields (hgnc_id, symbol, relevance score) and ranking. Sufficient for a search tool with rich 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 already covers both parameters with descriptions (100% coverage). Description reinforces with examples (e.g., 'breast cancer', 'p53'), adding practical value beyond schema.

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

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

Description clearly specifies fuzzy search across symbols, names, and aliases with concrete examples. Effectively distinguishes from sibling 'get_gene' which retrieves full records.

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 directs users to call get_gene for full records after searching. Implies this tool is for quick lightweight lookups; could add when not to use (e.g., when exact ID is known).

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 describing embedding model (BGE-base-en), chunking (500-char overlapping windows), truncation at 200K chars with flag, and return fields (offsets, similarity scores). Discloses no destructive behavior consistent with annotations.

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

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

Single paragraph with high information density; front-loaded with core functionality. Slightly dense but every sentence serves a 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?

Fully specifies return values (top-N passages with offsets and scores), explains truncation behavior, and paired with annotations provides a complete picture for agent invocation without output schema.

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

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

Schema has 100% description coverage; description adds value through natural-language query examples and explains internal processing (chunking, embedding) that aids understanding of how text and query interact.

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

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

Description clearly states the tool performs semantic search inside a fetched record, using specific verbs and resource, and differentiates from sibling tools by referencing ask_pipeworx_grounded.

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

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

Explicitly advises use when records are too large for prompts and mentions pairing with ask_pipeworx_grounded; lacks explicit 'when not to use' but provides strong contextual guidance.

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

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

Description states 'Returns the new subscription id' implying non-idempotent creation, but annotations set idempotentHint=true, creating a contradiction. It does not clarify idempotency behavior. Other behavioral traits like OAuth requirement are disclosed, but the idempotency contradiction is a significant gap.

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

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

Description is informative but slightly lengthy; each sentence has purpose. Front-loaded with purpose and requirement, then examples and delivery details. Could be trimmed slightly without losing clarity.

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

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

Given no output schema, description explains return value (subscription id). Covers all parameters, prerequisites, type-specific nuances, and delivery options with constraints. Sufficient for an AI agent to correctly 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 coverage is 100%, but description adds extensive context: lists all type enum values with examples, explains params structure for each type, and describes delivery channels with field-level constraints (SMS requires verification, webhook signing secret). This adds significant value beyond schema.

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

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

Description clearly states 'Create a proactive monitoring subscription' with specific verb 'Create' and resource 'subscription'. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation. The supported types and delivery channels are detailed.

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?

Specifies prerequisite (Pipeworx OAuth account) and provides type-specific filter examples and delivery constraints (SMS verification, cap). Though it does not explicitly say when to avoid this tool, the context with sibling names makes it clear. Could mention listing existing subscriptions as an alternative.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds that it returns category-bucketed example questions drawn from a live catalog of thousands of tools, providing useful behavioral context beyond annotations.

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

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

The description is a single paragraph that front-loads aliases and core purpose. While slightly long, every sentence adds value. It could benefit from bullet points for readability, but it's well-structured overall.

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

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

Given the tool's simplicity (one optional parameter, no output schema) and many siblings, the description is remarkably complete. It covers purpose, usage guidance, parameter semantics, and return format, leaving no critical gaps.

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

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

Schema coverage is 100%, but the description adds significant value by listing example topic values and explaining the effect of omitting vs specifying a topic (full spread vs focused). This helps the agent understand parameter usage beyond schema alone.

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

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

The description clearly states the tool's purpose: an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It lists multiple alias phrases, differentiating it from sibling tools by specifying it should be used first when unsure about Pipeworx capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains call patterns (no arguments for full spread, topic for focus). While it doesn't state when not to use it, the context is clear and helpful.

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

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

Annotations indicate non-read-only, idempotent, non-destructive. Description adds ownership enforcement, deactivation rather than deletion, and that historical events remain via 'recent_alerts'. This provides rich behavioral context beyond annotations without contradiction.

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

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

Two sentences, front-loaded with action and subject, followed by important behavioral detail. No redundant or 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?

Describes side effects (deactivation, history kept) and references 'recent_alerts' for context. Lacks return value information, but for a cancellation tool this is a minor gap. Overall sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with clear parameter description ('Subscription id (uuid) returned by subscribe'). Tool description mentions 'by id' but adds no new semantics. 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?

Description clearly states the verb 'Cancel' and the resource 'subscription'. It distinguishes from sibling tools like 'subscribe' by specifying ownership enforcement and the deactivation (not deletion) behavior, with history preserved via 'recent_alerts'.

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

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

Explicitly says when to use: to cancel a subscription by id. Mentions ownership enforcement, giving clear context. Could be improved by explicitly stating when not to use or listing alternative tools, but the information is adequate.

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?

With annotations indicating read-only, open-world, idempotent behavior, the description adds critical behavioral context: the meaning of could_not_verify vs unsupported (including that could_not_verify is not evidence), the two pipeline paths, and the fact that it replaces multiple sequential calls. This significantly exceeds what the annotations declare.

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

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

The description is relatively long but every sentence carries information: usage examples, the two-path routing, verdict options, and error semantics. It is front-loaded with the trigger phrases and purpose, and 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?

There is no output schema, so the description adequately explains the return value: a verdict, the actual value with citation, and reasoning, plus the special meanings of could_not_verify and unsupported. It covers input, behavior, and important caveats, making it complete for its complexity.

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

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

The schema already provides 100% coverage, including a detailed description of claim and tolerance_pct. The tool description does not add additional parameter-specific semantics beyond the schema, so the 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 clearly identifies the tool as natural-language claim verification against authoritative sources, with examples of user phrasings and a specific output (verdict). It distinguishes itself from generic research tools by describing the two-path routing and the composite nature of the 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?

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct', which gives clear when-to-use. It also distinguishes between company-financial and other claims. However, it does not name alternative sibling tools or state when not to use it beyond that context.

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