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, openWorldHint, idempotentHint, and non-destructive behavior, so the description is not burdened with safety disclosure. It adds meaningful behavioral context: the tool delegates to other tools, fills arguments automatically, and returns answers with stable citation URIs. It does not contradict the annotations, though it omits failure modes or limitations.

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

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

The description is front-loaded and well-organized with a domain list, trigger phrases, and useful examples. However, it is redundant: 'even if web search could also answer it' appears twice, and the final 'START HERE' sentence largely repeats the opening preference. Not 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 router tool with no output schema, the description covers selection cues, delegation behavior, and return shape at a practical level. It gives enough examples to convey the expected input format and explains the citation output. It lacks guidance on what happens when no source matches and does not distinguish among same-family siblings, leaving a small but real gap.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the natural-language question. The description adds only examples and task-level framing, not additional parameter syntax, constraints, or formatting guidance. This meets the baseline for a fully documented schema but does not exceed it.

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

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

States a concrete routing/fetching behavior: it routes questions to one of 5,798 tools across verified sources and returns a structured answer with stable pipeworx:// citation URIs. It clearly distinguishes itself from web search for factual/current/historical questions, but it does not differentiate itself from closely named siblings like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

Provides extensive when-to-use guidance: a domain list, trigger phrases like 'what is', 'look up', 'find', and 'current', and a strong 'START HERE' recommendation. It also names web search as an alternative to prefer this tool over. However, it never states when not to use it or how to choose among sibling research/search tools, so it stops short of full exclusion guidance.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds important context: candidate routing improvements can be enabled live, no candidate is currently active, it falls back to nothing, and it is a full working router. 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 front-loaded with the beta identity and equivalence to ask_pipeworx, and nearly every sentence carries useful behavior information. There is some mild redundancy between 'currently matches ask_pipeworx exactly' and 'use it exactly like ask_pipeworx,' but it remains reasonably compact.

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?

It covers the important operational details: current state, no fallback, live-candidate behavior, and same response shape. Since there is no output schema, the exact return format still relies on knowing ask_pipeworx's shape, but the description is otherwise complete enough for invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and aliases. The description adds only that it takes the same arguments as ask_pipeworx, which is useful but not parameter-specific. Baseline 3 is appropriate.

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

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

Clearly identifies itself as the beta version of ask_pipeworx and as a universal router with the same 5,798 tools, arguments, and response shape. This is a specific purpose that distinguishes it from the stable ask_pipeworx sibling.

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 it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the comparison against the stable router and the current no-active-candidate state, which grounds the usage decision.

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 fully discloses return shape, refusal reasons, and the principle that answers use ONLY tool result content. This goes well beyond the readOnlyHint and idempotentHint annotations and helps the agent predict 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 dense but every sentence earns its place: purpose, behavior, refusal contract, usage guidance, and cost comparison. It is front-loaded and structured for an agent to parse quickly.

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

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

Despite having no output schema, the description covers return values, refusal scenarios, cost, and safety-critical usage context. It is complete for correct invocation and expectation management.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that the question parameter drives internal routing across tools and that the answer is extracted from the fetched result, which is useful semantic context beyond the schema's alias 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 opens with a specific verb and resource: a hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from ask_pipeworx by describing its unique grounded extraction behavior and explicit refusal semantics.

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

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

It explicitly states when to use ('answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), and names the cost tradeoff. This provides a clear routing decision.

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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints; the description adds auth and paid-plan requirements, expected latency, gap[]/contradictions[] behavior, fetchable citation_uri semantics, and 'never invented' honesty. It also explains semantic excerpting of large records, giving the agent useful reliability 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 is long but densely informative; every sentence adds decision-relevant detail such as authentication, latency, output shape, depth differences, and citation guarantees. It is front-loaded with the account requirement and alternative tool, so an agent gets the most critical routing information first.

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 fully compensates by describing the findings packet structure, gaps[], contradictions[], hop/citation_uri fields, semantic excerpting, and latency expectations. Combined with the input schema and annotations, an agent has enough to invoke the tool correctly and interpret its results.

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

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

Schema coverage for both parameters is 100%, so the schema already documents question and depth. The description enriches depth semantics by explaining what each depth level does operationally—quick, standard's gap-recovery hop, thorough's lead-chasing plus contradictions scan—and confirms that broad, multi-part questions are acceptable.

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

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

The description names a specific verb and resource: 'grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' and explicitly contrasts itself with 'open-web search.' It also gives concrete example questions and routes single lookups to ask_pipeworx, so an agent can clearly distinguish this from sibling tools.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data,' and an explicit exclusion: 'For a single lookup use ask_pipeworx.' It also states the account/paid-tier prerequisite and names a fallback for unsigned-in users.

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?

Annotations already mark it read-only, idempotent, and non-destructive, so the bar for added behavioral context is high. The description exceeds it by explaining sources_used/sources_failed semantics ('an empty section is a real "no data", not a bug'), the USPTO PatentsView sunset soft-fail, expected-empty FDA sections for small-molecule-only companies, and private-company resolved:false behavior. This substantially exceeds what annotations alone 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 front-loaded with example user intents and the core 'ALWAYS PREFER' directive, then organizes return sections with clear semicolon-separated field names. It is long and dense, but nearly every clause carries unique operational detail rather than filler, so it earns a score above minimum despite not being brief.

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 bears the burden of explaining return values, and it does: it covers every returned section (recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI), source-failure semantics, input resolution behavior, and edge cases like private companies. An agent has enough to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds concrete value by explaining that type accepts 'company' or 'ticker' interchangeably, providing examples ('AAPL', '0000320193', 'Moderna'), and noting that names resolve via SEC EDGAR. It adds useful nuance beyond the schema, though it partially repeats it.

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

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

The description opens with natural-language triggers and states the deliverable: 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the verb, resource, and scope, and distinguishes itself from siblings like resolve_entity and compare_entities by its breadth and single-entity focus.

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

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

It explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving a clear routing signal. It also defines acceptable input forms and private-company behavior, but it does not contrast this tool against deep_research or compare_entities, so not all alternatives are addressed.

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?

Goes well beyond readOnlyHint/idempotentHint by disclosing non-obvious behaviors: compatibility codes and their meanings, unclassified legs never paired, null temporal_alignment not meaning aligned, fee model not included, and skipped comparison counters. 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?

Front-loaded with the core concept and then structured by modes, response, safety flags, codes, and caveats; every block carries needed safety semantics. It is long and occasionally repeats 'in EITHER mode,' but the length is justified by the absence of an output schema and the number of safety caveats.

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

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

With no output schema, the description carries the full burden and covers response fields, spread semantics, flags, fees, skipped counters, and interpretation warnings. An agent has enough to decide whether results are comparable and which caveats apply.

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

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

Schema already documents all three parameters with 100% coverage, so baseline is 3. Description adds value by explaining that BOTH modes execute the same token-overlap matcher, that explicit tickers/slugs override the topic-mapped side, and that topic presets are convenience shortcuts, not tradeability guarantees.

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?

Opens by identifying the exact resource: the cross-venue spread between Kalshi and Polymarket for the same resolving question, which separates it from single-venue siblings. It lacks an explicit action verb like 'computes' or 'returns,' but the noun phrase and subsequent mode descriptions make the function 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?

Gives clear operational guidance: two modes (topic vs explicit pairing), identical matcher, and a strong caution that pre-mapped topics often produce compatibility warnings and are not tradeable. It does not explicitly compare against sibling tools like polymarket_arbitrage, so no direct alternates or exclusions are named.

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?

Annotations already signal read-only, idempotent, open-world, and non-destructive behavior. The description adds substantial behavioral detail beyond that: graceful degradation when GLEIF/OpenFIGI is unavailable, explicit 'unresolved' output, 'figi_candidates' when a name matches multiple instruments, and the fact that one call replaces several manual lookups. 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 long and dense, but it is front-loaded with example queries and the 'Use FIRST' directive, then organized by supported type and edge cases. Some sentences are run-on and could be tightened, but the length is justified by the complexity of the resolution 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?

Given two required parameters, no output schema, and a high-complexity tool, the description covers what an agent needs: input formats, supported entity types, resolution sources, ambiguous-match behavior, unresolved identifiers, fallback behavior, and return artifacts like figi_candidates and RxCUI citations. Nothing critical is missing.

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

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

The schema already documents both parameters well, but the description adds crucial extra semantics: the exact meaning of 'value' for companies vs drugs, ISIN-to-LEI resolution behavior, and the important caveat to pass only the entity name, not the full noun phrase, especially for bonds. This materially helps the agent construct correct calls.

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 and resource: resolve a spoken name to canonical/official identifiers that other tools require. It further enumerates supported entity types and example queries, making it unmistakable what this tool does and how it differs from general search or entity-profile siblings.

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 direction: 'Use FIRST whenever you have a name but need an ID,' which is clear usage guidance. It does not explicitly list sibling alternatives or state when not to use this tool, but the examples and supported types cover the main selection criteria well.

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.