Gnomad

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context: the default free model, the optional paid Anthropic probe with a BYO key, and the structured return format. No contradictions with annotations.

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

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

Three sentences, front-loaded with purpose, then configuration, then return format and use cases. Every sentence is informative with no wasted words or repetition of schema details.

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

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

For a 4-parameter tool with no output schema, the description covers purpose, configuration, return shape (per-model score/confidence/signals/raw_response + combined view), and use cases. It doesn't detail the contents of 'signals', but the overall guidance is sufficient for correct invocation and basic interpretation.

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

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

The schema already documents all 4 parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra value by naming the default model (Llama-3.3-70b) and clarifying the cost implications of _apiKey, which goes beyond the schema.

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

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

The description states a specific verb ('Probe'), a clear resource (LLMs about a business/brand/product/topic), and a distinctive output (visibility score 0-100 per model). This separates it from general-purpose siblings like search or deep_research, even without naming 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?

Explicit use cases are listed (AI-marketing audits, pre-launch brand checks, competitive monitoring), and the description explains model selection and cost conditions. However, it does not explicitly state when not to use this tool or name alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: it routes to 5,529 tools across 1,455 sources, fills arguments, returns stable pipeworx:// citation URIs, and notes it's a single fast call. This goes beyond the annotations, though it doesn't discuss error handling or rate limits.

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

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

The description is long but well-structured: it starts with a preference directive, explains the mechanism, lists example triggers, and then gives alternatives. It is front-loaded with the most critical usage information and every sentence earns its place given the tool's broad scope and many sibling tools. Slightly verbose but justified.

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

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

With no output schema, the description fully compensates by explaining the return format (structured answer with citation URIs), routing behavior, and tier compatibility. It also covers when to use alternatives and provides concrete examples. This is complete for an agent to invoke the tool correctly and anticipate results.

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

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

Schema description coverage is 100% (all properties, including aliases, have descriptions). The tool description provides example questions but no additional parameter-level semantics beyond what the schema already states. Baseline 3 is appropriate since 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 clearly defines the tool's purpose: answering factual questions about real-world entities, events, or numbers by routing to thousands of verified sources and returning structured answers with citation URIs. It explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making the purpose unambiguous and well-scoped.

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

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

The description provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE', and when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It even addresses breaking-news scenarios, giving the agent clear decision criteria for 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 declare read-only, idempotent, and non-destructive hints. The description goes further by explaining that the tool is a full working router (not a fallback), that it currently matches ask_pipeworx exactly, and that candidate routing improvements are enabled live. This adds meaningful behavioral context beyond the annotations.

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

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

The description consists of four sentences, each carrying a distinct piece of information: identity, current state, usage, and clarification that it is a full router. It is efficiently written with no wasted words, though slightly longer than the two-sentence high-scoring example.

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

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

The description explains the tool's relationship to ask_pipeworx, current state, usage guidance, and confirms it is fully functional. For a router with no output schema, it references the stable sibling's response shape, covering most contextual needs without explaining return format in detail.

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 covers 100% of parameters (question and 5 aliases) with descriptions for each. The description only references 'same arguments' without adding parameter-specific syntax or format details, so the baseline 3 applies given the schema's completeness.

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 a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and arguments, and with candidate routing improvements. This specific verb ('ask') and resource ('pipeworx beta') distinguish it from the sibling ask_pipeworx while explicitly naming the relationship.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. This gives a clear when-to-use context and names the alternative, though it does not explicitly provide a when-not-to-use caveat.

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 details refusal reasons, evidence verbatim quotes, additional LLM call cost, and data truncation scenarios. It adds significant behavioral context without contradicting annotations.

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

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

Though long, every sentence is informative: mechanism, output shape, refusal modes, use cases, and cost tradeoff. It is front-loaded with the core purpose and structured logically.

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 describes success and refusal return structures, including refusal_reason enum values. It also covers use cases, behavior, and cost trade-offs, making it complete for a complex tool.

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

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

Schema coverage is 100%, with all parameters documented as aliases for 'question.' The description adds no extra parameter-specific details beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states this is a hallucination-resistant answer mode for high-stakes reads, and explains the grounded extraction process using only tool results. It distinguishes itself from sibling ask_pipeworx by emphasizing evidence and refusal behavior.

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 whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups,' naming the alternative and providing clear when-to-use and when-not-to-use guidance.

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

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

The description goes far beyond the read-only annotations, disclosing resolver confidence contracts, status codes (low_confidence_match, market_closed_or_inactive), wide-spread tradeability warnings, cancellation-rule risk, and GDELT fallback behavior. This level of behavioral detail is exceptional and helps the agent handle edge cases correctly.

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 but uses clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose in the first sentence. Some redundancy exists (e.g., the market parameter example repeated), and it could be tightened without losing value, but the structure aids navigation.

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

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

Given no output schema, the description thoroughly documents response shapes, resolver behavior, fallback logic, and edge cases. It even quantifies risks (e.g., 10pp spread, 50¢ void settlement) and explains when analysis fields are suppressed. The tool is complex, and the description covers all major aspects, making it highly complete.

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

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

Schema coverage is 100%, so the schema already fully describes all three parameters (market, depth, include_raw). The description adds some context for the market parameter (slug/URL/question text) but this largely duplicates the schema. No new parameter-level detail is provided beyond what the schema properties already state.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also lists concrete classifiers and fan-out examples, clearly distinguishing it from sibling tools like polymarket_arbitrage or deep_research. The purpose is unambiguous and actionable.

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

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

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives numerous examples of when to apply the tool (BTC, Fed, Hormuz, Yankees WS, etc.) and describes safety/blocking paths, effectively teaching when to use and what to expect. While it doesn't explicitly name alternatives, the examples imply scope.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, and the description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS), specific metrics pulled (revenue, net income, cash, long-term debt, adverse-event counts), fiscal-year handling, sorting behavior, and citation URIs. This goes well beyond the annotations.

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

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

The description is longer than minimal, but every sentence contributes: query examples, data sources, metrics, sorting, count limits, and output format. It is front-loaded with purpose and not repetitive.

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 is thorough: it covers input constraints (2–5 entities), data sources, per-type behavior, sorting, output shape (paired data + citation URIs), and efficiency benefit. Context is complete for an agent to select and invoke appropriately.

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

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

Schema descriptions cover 100% of parameters, so the baseline is 3. The description adds value by providing concrete examples (AAPL/MSFT, ozempic/mounjaro) and clarifying that values can be tickers/CIKs for companies and drug names for drugs, making parameter semantics more intuitive.

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: side-by-side comparison of 2–5 companies or drugs with explicit query examples. It distinguishes from siblings by emphasizing a single parallel call and contrasting with sequential single-pack lookups.

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 instructions with query triggers and a preference directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This effectively guides selection versus alternative approaches.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing account requirements, paid-tier limitations for 'thorough,' latency expectations (15-60s, up to ~90s), the never-invented guarantee via explicit gaps[], and the conditional presence of citation_uri. It also explains semantic excerpting and contradictions[] behavior. No annotation contradiction exists.

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

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

The description is long but every sentence contributes unique, actionable information. It front-loads the critical account requirement and then flows logically from purpose to usage guidance to depth behavior to output details to latency. Some redundancy exists (e.g., repeated references to ask_pipeworx), but overall structure earns its length.

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

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

With no output schema, the description fully compensates by describing the findings packet contents, gaps[], contradictions[], hop field, and citation_uri fetchability. It also covers data source scope, latency, auth, and alternatives. The tool is complex, and the description is remarkably complete for an agent to 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?

The input schema already provides detailed descriptions for both parameters (100% coverage), including quick/standard/thorough semantics. The description adds value by highlighting that depth:'thorough' requires a paid plan and clarifies the practical implications of each depth level. It also reinforces the question parameter's purpose with examples, though schema already covers 'Broad/multi-part is fine.'

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 what the tool does: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources… in ONE call' and 'Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL.' It also distinguishes itself from open-web search and sibling tools like ask_pipeworx, making its purpose unmistakable.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS… prefer ask_pipeworx.' It also states it is 'Best for broad/multi-part questions over structured data.' This is exemplary usage guidance with named alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe read-only operation. The description adds meaningful behavioral detail beyond the annotations: it returns top-N tools with names, descriptions, and full input schemas with curated examples, and explicitly states that each result is ready to call directly with no second schema lookup needed. This gives the agent confidence about the tool's output behavior without contradicting annotations.

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

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

The description is four sentences, each serving a distinct purpose: stating the action, giving usage context with domain examples, describing the return value, and providing priority guidance. It is front-loaded with the core verb, and every sentence adds value, though it could be slightly more concise by trimming the long list of domains.

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 (6 parameters, no output schema), the description provides sufficient context about what the tool does and what it returns (names, descriptions, schemas, examples). It explains the 'top-N' behavior and the 'ready to call directly' benefit. The only gap is that it doesn't specify the exact format of the returned top-N list, but since there is no output schema, this is a reasonable level of completeness.

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

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

Schema coverage is 100%, so the input schema already documents all six parameters. The description adds minimal extra meaning: it explains that the query is a 'data or task' description and mentions 'top-N' which relates to the limit parameter. While this is useful, it does not go beyond the schema's own descriptions, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It identifies the resource (tools) and the action (discover/look up), and explicitly lists example domains (SEC filings, FDA drugs, etc.), making its purpose unmistakable. It also distinguishes itself from sibling tools by framing itself as a meta-tool to discover the option set, rather than answering a specific query.

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 direct usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This explicitly tells the agent when to invoke this tool over alternatives, including a clear contrast with tools that provide a single answer.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses parallel fan-out behavior, specific data sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), the patent API sunset and soft-fail behavior, and the return structure. This significantly enriches the agent's understanding of what the tool does and its quirks.

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 densely packed with necessary information for a multi-source tool. It front-loads example queries, uses structured lists for outputs, and every sentence conveys essential constraints. Slightly verbose, but the length is justified by the tool's complexity.

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

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

With no output schema, the description enumerates all return fields (cik, filings with URIs, fundamentals, patents, news, LEI), explains the input format limitations, mentions fallback and soft-fail behavior, and gives a usage directive. It fully covers the context an agent needs to decide and invoke correctly.

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

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

Schema coverage is 100% for both parameters, but the description adds critical semantic detail: value accepts ticker or zero-padded CIK, explicitly states names are unsupported, and provides examples. This extra clarification goes beyond the schema's description, earning a 4.

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

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

The description opens with concrete example queries ('Tell me about X', 'research Acme') and immediately defines the tool as a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from sibling tools like resolve_entity and deep_research by stating its scope and preference, making its purpose unambiguous.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides exclusion criteria: 'names not supported (use resolve_entity first if you only have a name).' This is textbook usage guidance with clear alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the scope 'previously stored memory' and clarifies it targets data 'the agent saved earlier,' but it does not disclose permanence, error behavior (e.g., missing key), or any side effects beyond what annotations convey.

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

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

The description is three concise sentences, each serving a purpose: stating the action, giving usage scenarios, and linking to related tools. It is front-loaded with the core function and avoids redundancy.

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

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

For a simple 1-parameter destructive tool, the description covers purpose, usage, and relationships. It lacks explicit notes about irreversibility or behavior on nonexistent keys, but these are partially covered by idempotentHint and the tool's simplicity. Overall it is sufficiently complete.

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

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

Schema coverage is 100%: the only parameter 'key' is described as 'Memory key to delete.' The description's 'by key' and 'previously stored memory' add minimal context but do not elaborate on key format, where to find keys, or any additional constraints 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 function: 'Delete a previously stored memory by key.' It specifies the verb (delete), resource (memory), and identifier (key). The note 'Pair with remember and recall' distinguishes it from sibling memory tools.

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

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

The description gives explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names companion tools (remember, recall) but does not explicitly say when to use those over forget, nor does it state any exclusions.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds that the tool accepts two identifier formats, a mild behavioral trait, but does not disclose error handling or data scoping beyond that.

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, front-loaded with the core function. Every word earns its place with no filler.

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

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

For a simple read-only lookup with an output schema and clear annotations, the description is minimally adequate. However, the vague 'gene info + variants' and the undocumented dataset parameter leave some gaps in fully understanding the tool's capabilities.

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

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

The description explains that gene_symbol_or_id accepts a gene symbol or Ensembl ID, which adds meaning to that parameter. However, the dataset parameter is not explained, and with 0% schema description coverage, this leaves a gap for agents.

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 provides gene information and variants, and specifies accepted identifier types (gene symbol or Ensembl gene ID). This distinguishes it from related tools like variant and region, though the meaning of 'info' is slightly vague.

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

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

It gives context on what inputs are acceptable (gene symbol or Ensembl gene ID), which implies when to use the tool, but it does not explicitly mention alternatives or exclusions, such as when to use the variant tool instead.

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

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

Annotations cover side effects (readOnly, idempotent, non-destructive). The description adds process detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is ready to drop at site-root/llms.txt, which is useful beyond annotations. However, no information about error handling or rate limits is provided.

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

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

The description is concise and well-structured. It opens with the main purpose in the first sentence, follows with the process in the second, and closes with use cases. Every sentence provides distinct value with no filler.

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

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

Given the tool's simplicity (2 params, no output schema) and strong annotations, the description is complete. It explains what, how, output format, and use cases. The absence of an output schema is compensated by explicitly stating the output is a single text blob ready for site-root/llms.txt.

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 'url' and 'max_links' have descriptions. The description does not add significant semantics beyond the schema. It mentions 'any URL' and 'key links,' which are already implied by the parameter descriptions, 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 a specific action: 'Generate a production-ready llms.txt file for any URL.' It also explains the process (fetches page, extracts title/description/key links) and output format, making it distinct from sibling tools like ai_visibility_check or scan_competitor_ai_presence by explicitly focusing on producing an llms.txt file.

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 by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool, though it does not explicitly name alternatives or 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?

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond annotations by specifying the return fields and scoping results to 'the caller,' which clarifies the data boundary. No contradictions with annotations.

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

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

The description is two sentences long, front-loads the primary action and result, and then gives a concise usage pointer. Every word contributes either to understanding what the tool returns or when to use it, with no redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema, clear annotations), the description fully covers purpose, return contents, and usage context. It tells the agent exactly what to expect and why to call it, making it complete for effective invocation.

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

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

The single parameter (include_inactive) is fully described in the schema with 100% coverage. The description does not add extra parameter semantics, but the schema already provides sufficient meaning, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('List') and identifies the exact resource ('the caller's active subscriptions'). It also lists the returned fields, making the tool's scope unmistakable, and clearly distinguishes it from sibling mutation tools 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 explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool relative to subscription management, and implicitly contrasts with subscribe/unsubscribe operations.

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 only state non-readOnly, non-destructive, but the description adds substantial behavioral context: rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token mechanism for later retrieval, that it's free and doesn't count against quota, and guidance to avoid pasting user prompts. 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 moderately long but every sentence serves a purpose: purpose, usage, exclusions, claim_token behavior, rate limits, and cost. It is front-loaded with the core action and avoids redundant or filler language.

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 feedback tool with no output schema, the description fully covers the process: how to file, what to include, how to retrieve status updates, rate limits, and cost. It anticipates the reader's main questions and addresses them completely.

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

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

Although schema descriptions cover all parameters, the description enriches them with practical usage guidance: describing the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), advising to 'Describe the issue in terms of Pipeworx tools/packs', and specifying message constraints (1-2 sentences, 2000 chars max). This adds clear 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings like ask_pipeworx by focusing on feedback submission rather than asking questions, and enumerates the submission types (bug, feature, data_gap, praise).

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

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

Provides explicit when-to-use scenarios: bug (wrong/stale data), feature gap, praise. It includes a strong when-not-to-use exclusion: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' Also clarifies identification ('Pipeworx tool names are the ones this connection lists').

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

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

The description discloses several behavioral traits beyond the annotations: it is 'derived from CF analytics-engine', contains 'no PII, just (pack, tool, count)', and is 'Cached 5min-1h depending on window.' This adds meaningful context about data provenance, privacy, and caching that annotations do not provide.

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

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

The description is three sentences long, front-loaded with the core purpose, followed by use cases and then transparency details. Every sentence adds value with no redundancy, making it highly efficient and well-structured.

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

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

Given the tool's low complexity (one optional parameter, no output schema), the description is complete: it explains the return content (top tools, top packs, total call volume), the underlying data structure (pack, tool, count), and the caching behavior. This is sufficient for an AI agent to understand what the tool provides.

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

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

The schema already provides 100% coverage for the single 'window' parameter with its enum values and semantics. The description repeats the same information ('24h, 7d, or 30d' and 'Shorter windows surface what's hot right now') without adding new meaning, so the baseline of 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 states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('returns') and resource (trending Pipeworx calls), and distinguishes itself from siblings like discover_tools by emphasizing it is a 'self-aggregating signal' of agent activity, not a tool discovery catalog.

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

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

The description provides explicit use cases under 'Useful for:', including discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. It gives clear context for when to use the tool, but does not name alternative tools or state when not to use it, which prevents a 5.

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

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

The description reveals important behavioral traits beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false). It transparently explains the partition filter behavior, the semantic similarity threshold of 0.30 Jaccard, and the fill check caveat that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' This adds significant behavioral context beyond what annotations provide.

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

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

The description is long but organized with section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it easily scannable. Every sentence carries essential information—there is no filler. The initial sentence front-loads the purpose, and the structured subsections cover caveats and edge cases without redundancy.

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

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

Despite no output schema, the description clearly explains the response shape ('opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), and in event mode partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'). It also covers failure conditions, filters, and the interaction with fill_check, making the tool fully understandable for an AI agent without additional context.

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

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

Schema coverage is 100% for parameters, but the description enriches the semantics beyond the schema. It provides concrete examples for both 'event' and 'topic' modes, explains the comparative strengths of each mode, and details what happens under the hood (e.g., 'walks child markets, checks date-axis / threshold-axis ordering'). The description adds substantial meaning beyond the schema's basic parameter descriptions.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes the tool from siblings like polymarket_edges and polymarket_fill_risk, which focus on different aspects of Polymarket analysis.

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 guidance on when to use each mode: 'Call with NO args for a trending_scan of the top ~200 markets by weekly volume; pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also names an alternative for custom sizing: 'For custom sizing use polymarket_fill_risk.' This provides clear when-to-use and when-not-to-use context.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond these by detailing the model families, response structure, caching behavior, diagnostics, and the 24h-move warning. It adds significant context on what the tool does internally and why, without contradicting the annotations.

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

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

The description is long but exceptionally well-structured: it leads with a one-sentence summary, then uses bolded section labels to organize details on model families, tradeable-edge knobs, and response top-level. Every sentence conveys distinct information about functionality, constraints, or behavior; there is no filler or redundancy.

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

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

Given the absence of an output schema, the description thoroughly explains the response top-level (by_segment, fed_candidates, _diagnostics) and the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also explains why segments can be empty via diagnostics. This makes the tool's behavior understandable without needing a separate output spec.

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

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

The input schema already provides thorough descriptions for all 9 parameters (100% coverage). The description adds some extra nuance—e.g., explaining that min_kelly does not apply to partition arbs and that min_partition_leg_kelly applies to per-leg Kelly—which enriches understanding but is not strictly necessary given the schema's detail.

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 precise statement—'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price'—which clearly identifies the action, resource, and scope. It further distinguishes itself from likely siblings by specifying the use case ('what should I bet on today') and the response segmentation.

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 clearly states the intended usage ('discover opportunities without paging hundreds of markets') and provides context on filters and exclusions (e.g., Fed bets). However, it does not explicitly name alternative tools like polymarket_arbitrage or polymarket_edge_tracker for other use cases, so it lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds critical behavioral context: snapshots are written only on cache-miss, gaps imply no scan that day, 60-day TTL limits history, decay is computed on daily closes net of slippage, and expired opportunities have lifespan data. This far 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?

While dense, the description is well-structured into ARGS/RESPONSE/LIMITS sections and front-loads the core value proposition. Every sentence adds specific information — 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?

No output schema exists, so the description compensates by detailing the exact response shape: tracked[] with edge_pp_net time-series, trend, decay per day; expired[] with lifespan_days; snapshot_dates[]. It also states history limits and data-generation conditions, making the tool fully understandable.

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 both parameters fully (100%). Description adds clarity that `days` is the lookback (default 14, max 30) and `window` selects the snapshot family (default 1wk), complementing the schema's clamp/default details.

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

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

Description explicitly states 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and poses the core question it answers ('how long has this edge existed and is it shrinking?'). This clearly differentiates from sibling tools like polymarket_edges (which likely provides current edges) and polymarket_arbitrage.

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

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

The description implies usage by explaining that edge age changes trade interpretation ('a fresh wide edge and a 3-week-old wide edge are different trades'). It provides defaults and limits but does not explicitly name alternatives or when-not-to-use scenarios.

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

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

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds rich behavioral context: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), and details partial-fill risk and 'forced_directional_risk' naming. This goes far beyond the annotations' safety profile and describes actual execution 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 long but every sentence earns its place. It is structured with clear labeled sections (SINGLE-MARKET, BASKET, USE THIS), front-loads the core purpose, and packs both operational details and risk warning without redundancy. It is dense but 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?

The tool is complex (two modes, no output schema), yet the description fully covers inputs, outputs, mode-specific behavior, risk interpretation, and usage context. It even names returned fields (vwap_fill_price, capture_ratio, thin_legs, etc.) and the dominant loss mode, making it self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description substantially enriches parameter meaning. For example, it clarifies that size_usd is 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional — shares per leg, each paying $1' in basket mode. It also explains side defaults and auto-detection in basket mode, adding semantic depth 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (SINGLE-MARKET vs BASKET) and explicitly names sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate its role as a pre-trade risk check.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains consequences of not using it (theoretical overround not capturable, partial fills create unhedged directional risk), giving clear context and alternatives.

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

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

This description goes far beyond the readOnlyHint/openWorldHint annotations by detailing exact behavioral traits: the compatibility_warning conditions (matched_pairs, skipped_cross_type), temporal_alignment fields, and the meaning of true/false alignment. It also explains the semantic distinctions of skipped_cross_type vs. skipped_cross_subtype, which is transparent about how it handles non-equivalent bet shapes.

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 every sentence carries substantial information about modes, response fields, safety fields, and limitations. The use of capitalized section labels (TWO MODES, RESPONSE, SAFETY FIELDS) aids scanning. It could be split into subsections for even better structure, but it earns its length given the tool's complexity.

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

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

With no output schema, the description must explain return values, and it does thoroughly: leg-by-leg prices, matched spread, top_spreads_pp, compatibility_warning with two distinct cases, temporal_alignment, and the skipped_* counters. This is more than sufficient for an agent to understand what the tool returns and how to interpret 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?

The input schema already covers 100% of parameters, so baseline is 3. The description adds meaningful context about parameter interactions: the `topic` parameter is a shortcut that auto-fetches matching events, while kalshi_event_ticker and polymarket_event_slug explicitly override the mapped side. This explains the mode behavior beyond what the schema descriptions state.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly identifying the tool's function and resource. It goes further to specify two distinct modes (topic shortcuts vs. explicit tickers) and the output structure (leg-by-leg prices, matched spread, top_spreads_pp), making it distinguishable from related tools like polymarket_arbitrage.

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

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

The description gives strong usage context: it explains when the spread is a 'real signal' and when it isn't, and includes a critical caveat that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not explicitly name alternative tools or say 'use this instead of X,' but the context is clear enough for an agent to decide when this tool is appropriate.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context about scoping (anonymous IP, BYO key hash, or account ID) and the source of retrieved data (saved via remember), which is beyond the structured metadata.

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

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

The description is three sentences long, front-loaded with the primary action, and uses examples efficiently. It is informative without being verbose, though slightly more detail is included than strictly necessary.

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 retrieval tool with one optional parameter, no output schema, and clear annotations, the description provides sufficient context including usage guidance, scoping, and relationship to siblings. It does not explain return format, but that is 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?

The input schema already fully documents the optional key parameter with a description, so schema coverage is 100%. The description repeats 'omit the key argument' but does not add new parameter-level semantics 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 retrieves a value saved via remember or lists saved keys when the key argument is omitted. It uses specific verbs ('retrieve', 'list') and explicitly names sibling tools (remember, forget), distinguishing this tool's 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 explains when to use the tool ('look up context the agent stored earlier') and provides concrete examples (target ticker, address, research notes). It also mentions pairing with remember and forget, giving clear alternative/complementary usage, though it doesn't explicitly state when not to use.

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

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

Annotation contradiction: readOnlyHint is true, but the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state mutation. This directly contradicts the read-only annotation. The description does add useful details about return fields and the feed, but the contradiction undermines transparency.

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

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

The description is concise and front-loaded with the core purpose. Four sentences cover the return payload, filtering, mark_read semantics, and an alternative access method. Every sentence adds useful information without redundancy, making it highly efficient.

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

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

With no output schema, the description compensates by explaining return fields (source, citation_uri, raw payload). It covers filtering, mark_read side-effects, and polling behavior. Missing details like pagination or error handling, but sufficient for a tool with well-described parameters and modest complexity. The annotation contradiction is a notable gap, but this dimension focuses on overall completeness.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by providing an example type ('sec_8k'), clarifying the ISO timestamp format for 'since', and explaining the side-effect of 'mark_read' on subsequent calls. This exceeds the baseline.

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

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

The description clearly states the tool 'pulls fired events from your subscription feed' and 'returns the most recent alerts,' specifying both the action and the resource. This distinguishes it from siblings like list_subscriptions, which list subscriptions rather than 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?

The description gives practical usage context: filtering by type and since, setting mark_read, and notes that 'polls work fine.' It also points to an alternative HTTP endpoint for scripts, though it doesn't explicitly exclude other tools or name sibling alternatives. Clear context without explicit exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavioral context: parallel fan-out across SEC EDGAR, GDELT-to-GNews fallback on rate limits/5xx, and USPTO soft-fail due to PatentsView API sunset. It also describes the return shape, including source-grouped changes and citation URIs.

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: user-intent phrasing, source fallback details, `since` format and recommendation, return structure, and explicit alternative. It is front-loaded with natural-language triggers before diving into technical specifics.

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

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

Even without an output schema, the description covers the structured return (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It explains multi-source behavior, fallback logic, and soft-fail conditions, making the tool's behavior fully understandable in context.

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

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

Schema coverage is 100% for all three parameters, so the baseline is 3. The description adds a recommended monitoring window ('30d' or '1m') and reiterates `since` formats, but this is guidance rather than new semantic meaning for `type` or `value` beyond what the schema already provides.

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

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

The description explicitly identifies a change feed for a company over a time window, with specific verbs like 'Fans out' and 'Returns'. It clearly differentiates itself from the sibling entity_profile by contrasting dynamic changes with the static profile.

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

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

The opening examples ('What's new with X', 'latest on Y') signal when to use the tool. The final sentence explicitly directs users to entity_profile when a static profile is needed, providing a clear when-not-to-use instruction and 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 readOnly, idempotent, and non-destructive behavior, and the description adds the 25kb size recommendation, which is a useful performance/completeness constraint. However, it does not disclose coordinate system (e.g., hg19 vs hg38), what happens for larger regions, or dataset-specific behavior. 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 a single front-loaded sentence with no filler words. Every part ('Variants in a genomic region' and '≤25kb recommended') adds essential information, making it perfectly concise.

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

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

The presence of an output schema and rich annotations reduces the burden on the description. The size recommendation is helpful, but the description omits critical context such as the reference genome build, coordinate convention, and dataset semantics. Overall, it is minimally adequate but leaves gaps that could cause incorrect usage.

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

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

Schema coverage is only 25% (only 'chrom' has a description). The description adds that start/stop define a genomic region and recommends a maximum size of 25kb, giving some meaning to those coordinates. Yet it does not specify units or coordinate convention, and the 'dataset' parameter is entirely unexplained, so the description only partially compensates for the low schema coverage.

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

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

The description clearly states the tool returns variants within a genomic region, which distinguishes it from 'variant' (likely a single variant) and 'gene' tools. However, it lacks an explicit verb like 'retrieve' or 'list,' and the title 'Region' is generic, making the purpose slightly less crisp than it could be.

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 only usage guidance is the '≤25kb recommended' size limit, which implies a constraint but does not explain when to prefer this tool over alternatives such as 'variant' or 'search.' No sibling tools are named, and there is no guidance for larger regions or dataset 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?

Adds valuable context beyond annotations: persistence details (authenticated users persistent, anonymous 24h), scope by identifier, and storage semantics. Does not contradict the idempotentHint=true or readOnlyHint=false annotations, though it does not explicitly address key-collision/overwrite 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?

Three sentences, front-loaded with the core purpose, followed by usage guidance and pairing details. Zero wasted words; 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?

For a simple two-parameter write tool with no output schema, the description covers purpose, use cases, persistence, scope, and companion tools. The annotations supply safety profile, and no critical behavioral or return-value info is needed for an agent to 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% with descriptions for both key and value. The description reinforces parameter meaning with real-world examples (e.g., 'subject_property', 'target_ticker') and explains the key-value pair scoping, adding useful context beyond the raw schema.

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

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

The description clearly states 'Save data the agent will need to reuse later' with a specific verb and resource, and distinguishes itself from sibling tools 'recall' and 'forget' by framing storage, retrieval, and deletion as a paired workflow.

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 when' guidance with concrete examples (resolved ticker, target address, user preference), and names alternatives ('Pair with recall to retrieve later, forget to delete'), making when-to-use vs. alternatives 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 readOnly/idempotent annotations, the description discloses multi-source fallback behavior ('degrades gracefully'), source labels for identifiers, explicit `unresolved` field, and ownership info from LEI. It also mentions that each call cascades through several endpoints, replacing 2-3 manual lookups.

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

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

The description is verbose but well-organized, with a query-examples lead-in, a core purpose statement, and a type-by-type breakdown. While it earns its length by covering multiple data sources and edge cases, the density makes it slightly heavier than necessary.

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 exists, so the description compensates by enumerating the returned identifiers for each type, the unresolved field, and the graceful degradation behavior. It fully covers the two supported types and their input variants, making it complete for an agent to understand the tool's capabilities.

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 both parameters with examples, and the description adds substantial output semantics: for `company` it lists the fields returned (CIK, ticker, company_name, LEI, FIGI) and for `drug` (RxCUI, ingredient, brand, citation). This goes beyond the schema's brief type descriptions, clarifying what the resolved value will contain.

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

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

The description clearly states the tool resolves names to canonical identifiers, with examples ('ticker', 'CIK', 'LEI', 'RxCUI') and the directive 'Use FIRST whenever you have a name but need an ID.' It distinguishes from siblings by framing itself as the prerequisite identity lookup for other tools.

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

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

Provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also specifies the two supported entity types and their input formats. However, it does not explicitly name alternative tools or state when not to use it (e.g., when ID already known), so it falls short of a full 5.

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

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

The description adds rich behavioral context beyond the annotations: it explains that the tool 'probes each entity' with ai_visibility_check, 'ranks by score', and returns a 'ranked list with score, confidence, signal density per entity.' It also discloses the conditional _apiKey requirement and the special treatment of the first entity ('First entry treated as the "subject" for narrative'). These details are not present in the annotations and significantly enhance transparency.

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

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

The description is two sentences: the first states the primary action and process, the second provides the use case and expected return. It is concise, front-loaded with the main verb, and every clause adds value (method, ranking behavior, use case, output format). No filler or redundancy.

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

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

Given the tool's moderate complexity (4 parameters, 1 required), the description covers all critical aspects: what it does, how it works (via ai_visibility_check), why to use it (competitive audits), what output to expect (ranked list with score/confidence/density), and parameter nuances. The absence of an output schema is compensated by the explicit mention of the return fields. It is complete for an agent to select and invoke correctly.

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

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

While the schema describes each parameter at 100% coverage, the description adds crucial semantic nuances: it states that models is optional and default to workers-ai, that _apiKey is required only for 'anthropic' in models, and that entities has an order-dependent meaning ('First entry treated as the "subject" for narrative'). These elaborated interpretations go beyond the schema's basic descriptions, clarifying parameter relationships and defaults.

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: 'Compare AI visibility across multiple entities side-by-side.' It uses a specific verb ('Compare'), names the resource ('AI visibility'), and distinguishes itself from the sibling tool ai_visibility_check by emphasizing the multi-entity comparison aspect. The phrase 'surfaces which is most/least recognized' further specifies the output and scope.

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

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

The description provides explicit guidance on when to use the tool: 'Useful for competitive AI-marketing audits' and includes a concrete example ('does Claude know about us as well as our competitors?'). It also names the underlying tool (ai_visibility_check) for individual probes, implicitly indicating the alternative for single-entity checks. This is clear context with an implicit exclusion for non-comparative use.

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

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

Beyond the read-only, idempotent hints, the description discloses important behavioral traits: it fans out across two external services, handles partial failures gracefully, mentions that bundlephobia's first measurement can take 5-30 seconds, and explains the 'sources_failed' field. This gives a clear picture of runtime behavior 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 concise yet information-dense. It is structured logically: purpose, usage, return value, ecosystem scope, and failure behavior. Every sentence adds unique information, and there is no fluff or repetition.

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

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

Despite lacking an output schema, the description specifies the exact return field names (is_latest, license, published_at, etc.), explains partial failure behavior, latency expectations, and ecosystem limitations. This is a complete description for a complex composite tool.

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

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

The schema already provides 100% coverage for the two parameters (package and version), so the baseline is 3. The description does not add significant new semantics beyond what the schema states; it indirectly references versions through 'version history' and 'new version' but doesn't elaborate on parameter formats or constraints.

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

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

The description clearly states the tool's purpose: a composite check for 'should I add this npm package to my project', combining deps.dev and bundlephobia data. The verb 'scan' and specific resources (npm package, deps.dev, bundlephobia) are explicit, and it distinguishes itself from siblings by being a single-call composite.

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 usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clearly delineates when NOT to use it by noting that other ecosystems (PyPI/Maven/Cargo/Go) fall under deps.dev:version directly, guiding the agent to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations by explaining the 'autocomplete-style' matching behavior and the specific return format (Ensembl IDs and symbols). This is valuable but does not disclose additional edge cases or limitations, so a 4 is appropriate.

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

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

The description is two sentences with zero waste. The first sentence states the action, scope, and output; the second provides usage guidance. Every word earns its place, and key information is front-loaded.

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

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

For a one-parameter search tool with a rich output schema and strong annotations, the description covers purpose, usage, and return format sufficiently. It explains that this is a resolver for partial identifiers, which is complete for the tool's intended context.

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

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

The schema has 0% description coverage for the 'query' parameter, so the description carries the burden. It compensates by defining the query as 'free-text' and specifying it can resolve 'partial gene names or symbols'. The schema examples show gene names and rs IDs, but the description itself adds the crucial semantics of partial matching. This is meaningful but not exhaustive, warranting a 4.

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

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

The description clearly states the tool performs an 'Autocomplete-style search across gnomAD genes and variants by free-text query' and specifies the output as 'matching Ensembl gene IDs and symbols'. It also distinguishes itself from sibling tools by explicitly framing it as a resolver to use 'before calling gene or variant'.

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 to resolve partial gene names or symbols before calling gene or variant'. This implies when not to use it (when you already have exact identifiers) and names the alternative tools (gene, variant), giving clear contextual direction.

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?

While annotations already declare readOnly, openWorld, idempotent, and non-destructive, the description adds rich behavioral details beyond those hints: exact embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), 200K char cap with truncation flag, and output specifics (character offsets and similarity scores). This goes far beyond the structured hints and sets accurate expectations for the agent.

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 function, followed by usage rationale, integration workflow, and technical constraints. Every sentence contributes unique information—no filler or redundancy. The structure is optimized for quick parsing.

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 explains the return format (passages with offsets and scores), handles edge cases (truncation flagged), and provides integration context with a sibling tool. The schema is simple and well-described, and the description fills all essential context gaps for a read-only search utility.

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 3 parameters with descriptive text (text max ~200K, query with examples, limit with default). The description restates some of these details (e.g., max chars) and mentions 'top-N passages', but does not add meaningfully new param-level semantics beyond the schema. With 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as performing semantic search within a supplied text, using an explicit verb+resource structure ("Semantic search INSIDE a fetched record"). It distinguishes itself from siblings by emphasizing the 'inside' aspect and by providing concrete examples (SEC 10-K body, article) that show scope. The pairing with ask_pipeworx_grounded further clarifies its niche without ambiguity.

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

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

Explicitly states when to use: "Use when the record is too big to cram into the prompt", and explains the benefit (saves context). It also describes a complete workflow with ask_pipeworx_grounded, indirectly indicating when not to use (when whole document grounding is acceptable). This provides clear, actionable guidance on tool selection.

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

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

The description adds substantial behavioral context beyond annotations: OAuth requirement, SMS phone verification and daily cap, webhook auto-disable after 10 consecutive failures, HMAC signing, and the one-time return of webhook_secret. Annotations (readOnlyHint false, idempotentHint true) are not contradicted; the description enriches them with operational specifics.

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 (approx. 150 words) but densely packed with necessary information. It is front-loaded with the core action and returns, then progressively covers requirements, types, and delivery. While every sentence adds value, the length could be slightly trimmed without losing clarity, so a 4 instead of 5.

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

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

For a creation tool with no output schema, the description covers return value ('Returns the new subscription id'), prerequisites, available types, delivery channels, and follow-up retrieval methods. It omits detailed examples for two of the five types (patent_grant, clinical_trial), but the schema fully documents those, so the description remains complete enough for an agent.

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

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

Although schema coverage is 100%, the description adds valuable semantics with concrete examples for each type (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) and detailed delivery channel behavior (E.164 format, verified phone, cap, webhook signing). This goes well beyond the baseline.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation and listing supported types and delivery channels.

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 prerequisites ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)'), delivery alternatives ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'), and conditions for SMS ('phone must be verified at /account first'). This gives clear when-to-use context, though it does not name direct sibling alternatives for creation.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns a dynamic, live catalog-derived list of category-bucketed example questions, each with the exact tool and argument shape. It also clarifies the effect of omitting or passing the topic parameter. No contradictions with annotations.

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

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

The description is information-dense but still readable, starting with common query phrasings to quickly orient the reader. It covers purpose, return format, usage with/without parameters, and when to use it. It is slightly long due to the list of categories, but every sentence contributes useful information without redundancy.

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

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

There is no output schema, but the description thoroughly explains what the tool returns: category-bucketed example questions with exact tool names and argument shapes. It also covers invocation variants (no args vs. topic), the categories available, and the tool's role in onboarding. For a tool of this simplicity, the description is complete and leaves no significant gaps.

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

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

The input schema already provides a description of the 'topic' parameter with focus area options, giving 100% schema coverage. The description enhances this by showing concrete example values (e.g., 'finance', 'pharma', 'betting') and explaining that omitting it returns a cross-category spread, which adds meaning beyond the schema's static list.

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 the onboarding entry point for Pipeworx, with a specific verb ('returns') and resource (category-bucketed example questions). It distinguishes itself from siblings by positioning itself as the 'use FIRST' tool and by referencing meta-tools like ask_pipeworx, entity_profile, and compare_entities, which is particularly useful for navigation.

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

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

The description gives explicit when-to-use guidance ('Use this FIRST when you do not yet know what Pipeworx can do for you') and mentions how to learn to call meta-tools. It does not explicitly state when not to use it or name alternatives like discover_tools, but the 'use FIRST' directive strongly implies it is not for direct research. This is clear context without full exclusionary 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 the tool as read-only, idempotent, and non-destructive. The description adds context about returning data from exome and genome datasets and specific fields, but does not reveal additional behavioral aspects such as rate limits or authentication. With rich annotations, this is acceptable.

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, focused sentence that front-loads the main action and includes essential return details without unnecessary fluff. Every part 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 a clear purpose, explicit output fields, and annotations covering safety, the description is complete for a straightforward fetch tool. The presence of an output schema means return values need no further elaboration.

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

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

The description mentions 'from exome and genome datasets', which hints at the dataset parameter, and the schema already describes transcript_id. However, the dataset parameter values are not fully explained in the description, leaving some ambiguity. With 50% schema coverage, the description partially compensates.

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 fetches gnomAD variant data for an Ensembl transcript, specifying the action (fetch), resource (transcript), and key output fields. It distinguishes from sibling tools like gene or variant by focusing on transcript-level data.

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

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

The description implies usage when the user has an Ensembl transcript ID and wants variant data, with clear context on input and output. It does not explicitly mention alternative tools or exclusion cases, but the context is sufficiently clear for typical use.

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

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

The description discloses key behavioral traits beyond annotations: ownership enforcement, deactivation rather than deletion, and the impact on historical events via recent_alerts. This complements the annotations (e.g., destructiveHint false) and gives the agent a clear picture of side effects.

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

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

The description is two sentences long, front-loaded with the core action, and contains no redundant information. Each sentence adds distinct value (action, ownership, deactivation behavior).

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 single-parameter tool with annotations and a complete schema, the description fully covers the behavioral context. It explains the ownership rule, the non-destructive nature, and the relationship to recent_alerts, which is sufficient for an agent to use the tool correctly.

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

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

Although the schema already describes the 'id' parameter with 100% coverage, the description adds meaningful constraints: the id must belong to the caller's own subscription. This provides semantic value beyond the schema's basic type/description.

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

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

The description clearly identifies the action ('Cancel a subscription by id') and the resource, and distinguishes itself from sibling tools like subscribe and list_subscriptions. The added detail about ownership enforcement and deactivation clarifies the tool's specific scope.

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

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

The description provides clear context for when to use the tool (canceling a subscription) and includes a constraint (ownership). However, it does not explicitly mention alternatives or give when-not-to-use guidance, though the action itself is unambiguous given the tool name and context.

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

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

Annotations already flag readOnly/idempotent/non-destructive, and the description goes further by disclosing the return verdict set and critically explaining that 'could_not_verify' means the check did not happen and is NOT evidence for or against the claim, while 'unsupported' means no source exists. This prevents misinterpretation and is not contradicted by the annotations.

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

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

The description is long but dense, with each segment adding value: trigger phrases, routing, return values, error semantics, and efficiency. The list of natural-language phrasings could be trimmed, but it is front-loaded with the use case and the critical caveats are included.

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 payload: six verdict values, actual value with citation, reasoning, and error object. It also covers both routing paths and the critical distinction between 'could_not_verify' and 'unsupported', making the tool self-contained.

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

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

The input schema already documents both parameters with 100% coverage. The description adds practical guidance beyond the schema: a real-world claim example and explicit tolerance advice ('set 1–2 for hallucination detection') plus the default cap of 5, which helps the agent use 'tolerance_pct' correctly.

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 identifies the tool as natural-language claim verification ('fact check', 'verify the claim that…') and specifies scope: fact-checking user statements against authoritative sources. It also distinguishes from siblings by explicitly separating the structured SEC EDGAR fast path for company-financial claims from the grounded pipeline for all other factual claims.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing guidance: company-financial claims use SEC EDGAR, any other claim falls through to the grounded pipeline. It does not name exclusions or alternative tools, but the routing and efficiency note ('Replaces 4–6 sequential calls') give clear when-to-use context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. However, the description adds no behavioral context beyond the identifier formats, such as what data is returned, whether it queries external databases, or how it handles invalid IDs. With annotations present, the description needn't restate safety, but it also provides no additional transparency value, resulting in a low score.

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 short—a single fragment—which is concise, but it sacrifices structure. It lacks a proper sentence with a verb, making it feel truncated rather than efficiently written. Every word earns its place, but the under-specification reduces the quality of the structure, similar to the 'Process' example though less extreme.

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

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

The tool has only 2 parameters, an output schema, and strong annotations, so the description has less work to do. It adequately communicates the primary input format, which is the core usage. However, it omits context about when to prefer this tool over sibling tools, dataset behavior, and what the output represents (though output schema covers return values). It is minimally viable but has clear gaps in context.

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

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

The schema covers 50% of parameters (only 'dataset' has a description). The description adds meaning to 'variant_id' by providing concrete examples of accepted formats (chr-pos-ref-alt and rsid), which is useful and compensates partially for the schema gap. However, it does not explain possible 'dataset' values beyond showing 'gnomad_r4' in an example. The parameter semantics are improved but not fully clarified.

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 'Variant by chr-pos-ref-alt (e.g. "1-55051215-G-A") or rsid.' clearly indicates the resource (genetic variant) and provides example identifiers, but it lacks an explicit action verb like 'lookup' or 'retrieve'. This makes the purpose somewhat implied rather than directly stated. It does distinguish the tool from sibling tools by focusing on variant identifiers, but the missing verb lowers clarity.

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 no guidance on when to use this tool versus alternatives like 'gene' or 'region'. There is no mention of preferred contexts, exclusions, or alternative tools. The only hint is the input format examples, which are more about parameter semantics than usage context. This fails to help an agent decide when to select this tool.

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