Gtex

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: cost implications for Anthropic probes, output details (score, confidence, signals, raw_response), and the default model. 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 two well-structured sentences: first states primary function and output, second details model options and return format. Every sentence adds value with no 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?

Given the tool's complexity (multiple models, cost, output schema missing), the description covers key aspects: purpose, parameters, return format, and use cases. Could be improved by noting potential rate limits or error handling, but overall sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning with examples ('Pipeworx', 'OpenInvoice') for entity, explains model options, and clarifies that _apiKey is only needed for anthropic. This provides helpful context beyond schema descriptions.

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

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

The description clearly states the verb 'probe', the resource 'LLMs', and the outcome 'score visibility (0-100) per model'. It distinguishes itself from sibling tools by focusing specifically on AI visibility checks for brands/topics.

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

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

The description provides clear usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains when to use the free default vs. paid Anthropic option, but does not explicitly list alternatives among siblings.

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

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

The description adds significant behavioral context beyond the annotations: it explains that the tool routes questions to the right specialized sub-tool, fills arguments, and returns structured answers with pipeworx:// citation URIs. The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, and the description aligns with these. The only minor gap is no mention of latency or rate limits, but it does say 'one fast call', which is helpful.

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 key directive ('PREFER OVER WEB SEARCH'), then lists covered domains, then usage timing, and ends with alternatives. It is a bit long but every sentence adds value, and the structure is logical. Could be slightly tighter, but overall clear.

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 (5,564 tools, 1,462 sources) and lack of output schema, the description provides comprehensive guidance: what it does, when to use, when not to, examples, and alternatives. No output schema means the description must fill in what to expect (structured answer with citation URIs), which it does. No gaps remain.

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

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

Schema coverage is 100% with all properties documented as aliases for the question parameter. The description compensates by providing multiple examples and clarifying that the input is natural language. However, it doesn't add deeper semantics like expected length or constraints beyond what the schema provides, so a 4 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 is a unified entry point for authoritative structured data across 5,564 tools and 1,462 verified sources, with specific examples like 'current US unemployment rate' and 'Apple's latest 10-K'. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by explicitly noting when to use them instead.

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

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

Provides explicit guidance to prefer over web search for factual questions about real-world entities, events, or numbers, and lists when to step up to ask_pipeworx_grounded (hallucination-resistant single answer with verbatim evidence) or deep_research (broad/multi-part questions). Also mentions a caveat for breaking news, making the usage context crystal 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?

The description discloses behavioral traits beyond annotations, such as candidate routing improvements being enabled live during tests, the current inactivity of any candidate (last retired on 2026-07-26), and that results are compared against the stable router for merge decisions. Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false; the description adds operational context without contradiction.

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

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

The description is concise (three sentences) and front-loaded, immediately stating the beta nature and equivalence. Every sentence adds critical context: identity, candidate status, usage instruction, and fallback behavior. No wasted words.

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

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

Given the tool's complexity (5,564 tools, experimental routing) and the presence of detailed schema/annotations, the description is complete. It covers purpose, current state, usage guidance, and behavioral quirks. No output schema exists, but its identical response shape to ask_pipeworx is noted, satisfying 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%, and the description does not detail parameters, but it clarifies that all 6 parameters are aliases for 'question,' which adds value by disambiguating the single required input. The description states the tool accepts the same arguments as ask_pipeworx, implying consistency. Baseline 3 is elevated due to clear alias explanation.

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 this as a beta version of ask_pipeworx, specifying it is an identical universal router with the same 5,564 tools, arguments, and response shape. It distinguishes the purpose from the stable sibling by stating its role as an experimental edge for testing routing improvements.

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

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

The description provides explicit when-to-use guidance: use this like ask_pipeworx when you 'want the newest routing.' It also explains the fallback behavior (none, it is a full working router) and the current state (no candidate active, identical to stable), which helps the agent decide between siblings.

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

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

Annotations already readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false so safety is covered. The description adds significant behavioral context: the tool performs routing, argument filling, data fetching, then extracts an answer using only the tool result (with explicit refusal reasons). It discloses the extra LLM call cost and refusal modes. Slight deduction for not detailing what happens on truncation or how the evidence quote is selected.

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

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

The description is a single dense paragraph with no wasted sentences. It front-loads the core purpose and behavioral distinction, then details return format, refusal reasons, use cases, and cost trade-off. Every sentence adds value.

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

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

Given the tool's complexity (routing across 5,564 tools), the absence of an output schema, and the detailed annotations, the description covers all necessary aspects: behavior, return shape, refusal reasons, usage guidance, cost trade-off, and examples. No gaps remain for an agent to make incorrect assumptions.

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

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

Schema description coverage is 100% and all 6 params are aliases for a single natural language question field. The description adds clarity by explaining the question parameter accepts natural language and lists accepted aliases. It could be improved by noting that the question drives the routing—it's implied but not explicit.

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

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

The description clearly states a specific verb ('ask') and resource ('Pipeworx'), while distinguishing this tool from the sibling ask_pipeworx by emphasizing its hallucination-resistant behavior for high-stakes reads. The contrast with ask_pipeworx is explicit.

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 (high-stakes reads where answers will be quoted or acted on) and when-not-to-use (prefer ask_pipeworx for casual lookups) guidance, including a cost trade-off (one extra LLM call). It lists specific use cases (financial verdicts, legal claims, medical lookups, public statements).

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are complemented by extensive behavioral disclosure: low-confidence resolution handling, closed market detection, wide spread tradeability warnings, cancellation rule parsing, and safety short-circuits. No contradiction with annotations.

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

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

Description is exhaustive but verbose, covering many edge cases and response details. Information is structured with bold headers and examples, but length could be reduced. Each sentence adds value, but not minimally concise.

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

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

Given tool complexity (multiple data sources, edge cases like closed markets, low-confidence matches, cancellation rules) and lack of output schema, description is extremely thorough. Covers all important behavioral aspects for correct agent invocation.

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

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

Schema coverage is 100% (baseline 3). Description adds meaning beyond schema: explains 'depth' enum (quick vs thorough), default behavior, and when to use 'include_raw' (false recommended for size, true for post-processing). Market parameter examples given.

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

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

Description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). Distinguishes from siblings like polymarket_edges and polymarket_arbitrage which serve different specific purposes.

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 lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides classifiers and fan-out examples to guide appropriate use. Does not explicitly state when not to use compared to alternatives, but context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds valuable context: it pulls latest data, handles off-calendar fiscal years, returns sorted by primary metric, and provides citation URIs. 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 moderately long but each sentence adds value. It is front-loaded with natural language examples. However, it could be slightly more concise by removing redundant phrases like 'head to head'.

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

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

Given no output schema, the description adequately explains the return format (paired data + citation URIs) and sorting. It covers data sources, entity types, and the efficiency gain (replaces 8-15 lookups). For a 2-param tool, this is very 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 baseline is 3. The description adds meaning beyond schema: explains how 'values' should be formatted (tickers/CIKs for company, names for drug), sets limits (2-5), and describes the return data per type. This is substantial added value.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 entities (companies or drugs) in one parallel call. It specifies the data sources (SEC EDGAR for companies, FAERS for drugs) and distinguishes from sequential single-entity lookups, making the purpose unambiguous.

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

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

The description provides explicit triggers ('Compare X and Y', 'which is bigger', 'rank these companies') and strongly recommends this tool over sequential lookups. It could be improved by explicitly mentioning when not to use (e.g., for single entities use entity_profile), but the guidance is already very clear.

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

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

Annotations already declare readOnlyHint=true (safe read), idempotentHint=true (repeatable), and destructiveHint=false, so the baseline safety profile is covered. The description goes far beyond by disclosing parallel routing to 5,564 tools, gap recovery and contradiction scanning behaviors, expected latency ranges (15-90s), citation format (pipeworx:// URIs that are always fetchable), semantic excerpting (not head-truncated), and the hop field. 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 detailed and informative, but at 450+ words it is somewhat verbose for a tool description. Key information is front-loaded (account requirement, when to use sibling), and each sentence adds value, but the density could be slightly reduced for quicker scanning. Still, no waste exists.

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 2 parameters, 100% schema coverage, no output schema, and high interactivity with siblings (33+ tools), the description is remarkably complete. It explains the return format (findings packet with evidence, confidence, gaps, contradictions), the parallel architecture, the citation guarantee, and the iteration logic. An agent has all the context needed to select and invoke this tool correctly.

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

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

Schema coverage is 100% (2 parameters fully documented in schema), so baseline is 3. The description adds value by explaining that 'question' can be broad/multi-part and that decomposition is intrinsic, and that 'depth' controls not just quantity but also hop behaviors (gap recovery, contradiction scan, lead chasing). This contextual richness elevates the score above 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 this tool performs grounded multi-source research across Pipeworx's structured data sources, distinguishing it from alternatives like ask_pipeworx (single lookup) and open-web search. It specifies the verb 'researches' and the resource 'structured data sources' with concrete examples like SEC filings and FDA data, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool (broad/multi-part questions over structured data) and when not to (single lookups → ask_pipeworx; breaking news → ask_pipeworx). It names specific sibling alternatives and states account requirements, including that depth:thorough is paid and that free-tier users should use ask_pipeworx 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 already declare readOnlyHint=true and idempotentHint=true. Description adds valuable behavioral context: that results are 'ready to call directly' and include 'full input schemas (with curated examples).' This goes 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 somewhat lengthy but front-loaded with core purpose. Every sentence adds value, though could be slightly more concise. Still well-structured for an AI agent.

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

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

No output schema, but description adequately explains return format (top-N tools with names, descriptions, schemas) and that results are callable directly. This is complete for a discovery tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. Description mentions aliases but adds little beyond the schema. Baseline 3 is appropriate as no significant extra semantics are provided.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the output (top-N tools with names, descriptions, and schemas) and distinguishes itself from siblings by focusing on discovery rather than specific data retrieval.

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' This clarifies context and prioritization.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds significant behavioral context beyond annotations: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), details returned fields, mentions soft-fail for patents, and notes news fallback. 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 efficiently structured: it front-loads example queries, states the core purpose, gives usage preference, and details return fields in a bullet-like format. Every sentence adds necessary 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?

Despite no output schema, the description sufficiently explains the tool's output by listing returned data categories (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It covers input constraints and behavioral notes (patents sunset). Only minor gap: no explicit mention of output structure (e.g., JSON shape), but the list is adequate for an AI agent.

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

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

Schema coverage is 100% with both parameters described. The description adds value by providing examples ('AAPL', '0000320193'), explaining that names are not supported, and clarifying the CIK format (zero-padded). This goes beyond the schema descriptions, making parameter semantics clearer.

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: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs ('get profile') and resources ('US public company'), and distinguishes itself from sibling tools by explicitly preferring over chaining single-pack lookups and referencing resolve_entity for names.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use: 'Pass ticker or CIK — names not supported (use resolve_entity first if you only have a name).' This clearly defines usage 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?

Annotations already indicate destructiveHint=true. Description adds context about when deletion is appropriate (stale context, done task, sensitive data), which is helpful beyond the annotation.

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

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

Two sentences: one for purpose and one for usage. Every word earns its place; 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?

For a simple destructive tool with one required parameter and no output schema, the description, annotations, and schema together provide complete guidance. Agent can confidently decide when and how to use it.

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

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

Single parameter 'key' is described in the schema. The description does not add additional semantics beyond the schema, but schema coverage is 100% so baseline 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?

Description clearly states the verb ('Delete') and resource ('previously stored memory by key'). Distinguishes from siblings like 'remember' and 'recall' by specifying the delete action.

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

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

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall'.

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. The description adds no additional behavioral context, such as output format, pagination, or error handling. It relies entirely on 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, concise sentence with no wasted words. It is appropriately sized for the tool's simplicity.

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 an output schema, the description is too minimal. It does not explain what 'gene metadata' includes, whether multiple results are possible, or how to interpret the output. Additional context about the tool's scope would improve 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?

With 0% schema description coverage, the description must compensate but only says 'by Gencode id or symbol.' This implies the parameter accepts those identifiers but lacks format details, examples (though present in schema), or clarification that both types are accepted. The schema's examples partially fill the gap, but the description could be more explicit.

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 'Gene metadata by Gencode id or symbol' clearly states the tool's purpose: retrieving gene metadata based on an identifier. It uses a specific verb-resource combination, but does not explicitly differentiate from similar tools like 'top_expressed_genes' or 'single_tissue_eqtls', which also involve genes.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not specify scenarios where querying by Gencode id vs symbol is appropriate, nor does it mention any prerequisites or limitations.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds behavioral detail: fetches page, extracts content, emits markdown. No contradictions.

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

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

Concise, front-loaded with core purpose, and every sentence adds value. 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 simple params and no output schema, description fully conveys behavior and output format ('single text blob'). Annotations cover safety. 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 has 100% coverage with descriptions. Description adds example for url ('https://example.com') and default/max for max_links (25, 50), enhancing clarity.

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

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

Description clearly states the tool generates a llms.txt file for any URL, explicitly listing what it does (fetches page, extracts title/description/key links, emits standard format). It distinguishes itself from diverse sibling tools by being a unique utility.

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

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

Provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. Does not mention when not to use or alternatives, but siblings are unrelated so no conflict.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return field details and scope (active vs include_inactive), consistent with annotations. No contradictions.

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

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

Two sentences, front-loaded with purpose, efficient. Every sentence adds value.

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

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

Given annotations and schema, description covers return fields, usage context, and optional parameter. No output schema but description lists return fields sufficiently.

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 parameter description already handling semantics. Description does not add additional parameter meaning beyond what schema 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?

Description clearly states verb 'List', resource 'subscriptions', scope 'caller's active', and lists returned fields. Distinguishes from sibling 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?

Provides context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Implicitly guides when to use, but does not 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as false. The description adds behavioral context (aggregated median across tissues, TPM units) that goes beyond annotations, aligning well.

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

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

The description is a single, well-structured sentence with no wasted words. It conveys the core purpose immediately.

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, the presence of an output schema, and full parameter descriptions, the description is complete. It covers the essential information needed to invoke the tool correctly.

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

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

Schema description coverage is 100% for both parameters, so the baseline is 3. The tool description does not add extra parameter details beyond what the schema already provides.

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

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

The description clearly states the tool returns median TPM expression across tissues for a gene. It is specific and understandable, but does not explicitly differentiate from sibling tools like 'single_tissue_eqtls' or 'top_expressed_genes', though the function is distinct.

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

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

No usage guidelines are provided. The description does not specify when to use this tool over alternatives, nor does it mention any prerequisites or 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 provide no safety context (all false), so the description must carry the burden. It discloses rate limiting (5/day), the claim_token mechanism for unauthenticated filing, and follow-up via the token. It doesn't fully describe response/status behavior, but adds substantial context beyond annotations.

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

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

The description is longer than average but every sentence earns its place: purpose, use cases, exclusions, content guidance, token mechanics, and rate limit. It starts with a clear purpose and remains logically structured 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?

Without an output schema, the description compensates with claim_token flow, rate limit, and follow-up instructions. It covers scope, content guidelines, and identifies the tool as non-readonly (via 'filing'). Minor gaps remain around response formats for account holders, but overall it is thorough for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying message content (describe in terms of Pipeworx tools/packs, don't paste user prompt) and explaining the claim_token round-trip flow in detail, going beyond the schema's 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 clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback types (bug, feature, data_gap, praise) and is easily distinguishable from sibling research/utility tools.

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

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

Explicit when-to-use triggers are given for each feedback type, and an explicit exclusion is stated: only for tools from this Pipeworx connection, with a direct recommendation to file elsewhere for other MCP servers. This is exemplary 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: self-aggregating from CF analytics-engine, no PII, cached 5min-1h. No contradiction.

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

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

Three sentences plus bullet points, front-loaded with core functionality. Every sentence adds value, no waste.

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 low complexity (1 optional param, no output schema), description covers purpose, use cases, caching, and privacy. Sufficient for agent to select and invoke correctly.

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

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

Schema has 100% coverage with single parameter description and enum values. Description adds meaningful context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' Specific verb and resource, distinguishes from siblings like 'discover_tools' and 'ask_pipeworx'.

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

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

Lists three explicit use cases: discovering hot data sources, confirming canonical tool, aligning use case. No exclusions or alternatives, but context is clear.

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

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

Annotations declare readOnly, idempotent, non-destructive. The description adds behavioral details: partition checks, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check (CLOB depth). This explains what the tool does 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 comprehensive but lengthy. It uses bullet points and clear sections, but some redundancy exists (e.g., repeating 'cross-event mode'). Could be more concise without losing clarity.

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

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

Given the tool's complexity (multiple modes, fill check, partition check), the description covers all necessary aspects: response structure, filtering criteria, and references related tools (polymarket_fill_risk). No output schema, but response fields are described.

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?

Both parameters have schema descriptions, but the tool description adds significant context: event examples (slug, URL), topic examples (seed question), and explains how each mode behaves. This adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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 each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains the benefits of each mode, but lacks explicit when-not-to-use instructions.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral context: caching details, edge calculation methods (e.g., lognormal barrier, GDELT signal), response structure with diagnostics, and exclusion logic for Fed bets. No contradictions with annotations.

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

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

The description is long but dense with information, front-loaded with core purpose and organized by segments. Every sentence adds value given the tool's complexity. Slightly verbose but justified.

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

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

The description covers all essential aspects: purpose, model families, response structure, tunable knobs, caching, diagnostics, and edge cases (Fed bets). Despite no output schema, agents have enough context to invoke and interpret results 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 parameter descriptions. The description adds value by explaining tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) with usage tips (e.g., slippage guidance). It goes beyond schema defaults and conditions.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). It distinguishes itself from siblings by detailing unique model families and response segments.

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 (discovery of edges) and includes tunable knobs like min_liquidity and max_spread_pp. However, it does not explicitly compare with sibling tools like polymarket_arbitrage or polymarket_edge_tracker to guide 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 (readOnlyHint, idempotentHint) already convey safety. The description goes beyond by detailing output structure (tracked, expired, snapshot_dates), field semantics (trend, decay_pp_per_day), and data source limitations (non-intraday, TTL, cache-miss gaps). 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 front-loaded with purpose and well-structured with sections (RESPONSE, LIMITS). However, it is relatively long (multiple paragraphs) and could be slightly more concise for an agent to parse quickly. The detail is justified by complexity.

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

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

Given no output schema, the description fully explains the response format (tracked with time-series, expired with lifespan, snapshot_dates). It covers parameter constraints, data source caveats, and edge case behavior (gaps, signed values). No missing critical information.

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

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

Input schema covers both parameters with descriptions (100% coverage). The description restates defaults and constraints ('default 14', 'snapshot family') but adds no new semantic meaning beyond schema. Baseline score 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 explicitly states the tool provides 'edge persistence and decay telemetry' from snapshots, answering a specific question about edge longevity. It clearly differentiates from sibling polymarket_edges by focusing on time-series tracking rather than current snapshots.

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 (to assess edge freshness versus age) and includes LIMITS with TTL constraints. However, it does not explicitly contrast with alternatives like polymarket_edges or other tracking tools, leaving some inference to the agent.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are already present. The description adds rich behavioral context: it is a simulation/check that walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), and warns about risks like 'thin_legs' and 'forced_directional_risk'. 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?

Well-structured with section headers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Front-loaded with purpose, then mode details, then usage guidance. Every sentence adds essential information for safe tool use. Length is justified by complexity.

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

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

Despite lacking an output schema, the description fully documents return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and warns about risks. Handles two modes thoroughly, covers parameter behaviors, and explains output interpretation. Complete for a high-stakes simulation tool.

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

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

Schema coverage is 100% (all 4 parameters described), so baseline 3. The description adds value by explaining side defaults for single vs basket, size_usd meaning (spend vs target proceeds vs settlement notional), clamp range, and required exclusivity of market/event. However, schema descriptions already cover basics, so not a full 5.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific details. It uses precise verbs and resources, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains why (theoretical overround not capturable, partial basket fills create directional risk). Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: how the two modes work, when compatibility_warning fires (with two specific conditions), temporal_alignment details, and counters for skipped comparisons. There is 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 comprehensive but somewhat verbose. It is well-structured with clear sections (MODES, RESPONSE, SAFETY FIELDS) and front-loads the core concept. Some details, like the specific shortcut list and counters, could be streamlined but each sentence adds meaningful information.

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

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

There is no output schema, but the description thoroughly explains the response structure: leg-by-leg prices, top spreads, safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers edge cases like non-equivalent bet shapes and temporal gaps, making the tool's behavior fully predictable.

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 each parameter. The description adds significant value by explaining the usage of each parameter, listing the topic shortcuts explicitly, and describing how explicit tickers override the topic. This goes well beyond repeating schema info.

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 computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It explains the two operating modes (topic shortcuts and explicit tickers) and distinguishes this from siblings like polymarket_arbitrage which focus on single-venue edges. The verb 'compute' and resource 'spread' are specific and unambiguous.

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

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

The description explicitly guides when to use topic mode versus explicit tickers and notes that real spreads are rare and pre-mapped topics often return warnings. However, it does not explicitly contrast with sibling tools or state clear don't-use scenarios beyond the implied caution about non-equivalent bet shapes. The guidance is strong but could be more exclusionary.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scoping (to identifier) and pairing with remember/forget, providing context beyond annotations.

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

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

Three sentences, each adding distinct value: primary function, usage context, scope and pairing. No superfluous information, well 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?

The description is complete for a simple retrieval tool with one optional parameter, no output schema, and rich annotations. It clearly explains what, when, and pairing.

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

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

Schema description coverage is 100% and already states 'omit to list all keys'. The description reiterates this and adds slight extra context about usage, but does not significantly enhance parameter understanding.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys. It uses specific verbs 'retrieve' and 'list', and distinguishes itself from sibling tools like remember and forget by mentioning pairing.

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

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

Explicitly says when to use: to look up context stored earlier without re-deriving. Implicitly says when not to use (use remember to save, forget to delete). Also notes scoping to identifier.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds valuable behavior: return fields, mark_read effect on subsequent calls, polling suitability, and alternative endpoint. No contradiction with annotations.

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

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

Four concise sentences, front-loaded with main purpose, each sentence adding meaningful information. No redundancy or wasted words.

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

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

With 5 parameters and no output schema, description adequately explains return format, filtering, mark_read mechanics, and alternative access. No gaps for a read-only polling tool.

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

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

Schema covers all 5 parameters with descriptions (100% coverage). Description adds extra context: mentions filter by type and since, and explains mark_read's effect, going beyond schema.

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

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

Description begins with 'Pull fired events from your subscription feed,' clearly stating the action and resource. It specifies return content (source, citation_uri, payload) and differentiates from siblings by focusing on subscription feed 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?

States 'Polls work fine' and mentions alternative access via GET URL, providing usage context. Does not explicitly exclude scenarios or compare to siblings, but gives clear guidance on polling and mark_read behavior.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable behavioral details: fan-out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO), fallback logic, soft-fail for patents, and return structure (changes grouped by source, citation URIs). No contradictions.

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

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

The description is front-loaded with example queries and clearly structured. It is slightly verbose (covers multiple sources in detail), but every sentence adds value for an agent. Could be marginally tighter but remains effective.

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

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

Given high schema coverage, no output schema, and the tool's complexity (multiple sources, fallback logic), the description explains return structure (changes grouped by source, total_changes, citation URIs) and provides cross-reference to an alternative tool. No gaps.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds further meaningful context: type is only 'company', since accepts ISO dates or relative shorthand with examples, and value accepts ticker or CIK. This exceeds what schema alone provides.

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

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

The description clearly states the tool provides a change feed for companies over specified windows, with example queries and explicit differentiation from 'entity_profile' (static profile). It identifies the verb 'get recent changes' and the resource 'company change feed'.

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

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

The description gives explicit usage patterns ('What's new with X', 'latest on Y') and directly states when to use the alternative ('Use entity_profile instead when you want the static profile'). No ambiguity.

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

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

Discloses persistence, scoping, and retention beyond annotations. No contradiction with readOnlyHint, idempotentHint, or destructiveHint.

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

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

Two sentences, front-loaded, no wasted words. Efficiently conveys purpose, usage, and 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?

Fully covers purpose, usage, behavioral details, and parameters. No output schema needed; description self-contained.

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

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

Schema coverage is 100% with descriptions. Description adds context (e.g., key naming conventions, value as any text) and use cases, improving meaning.

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

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

Clearly states 'Save data the agent will need to reuse later' with specific verb and resource. Distinguishes from siblings by mentioning recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Provides alternatives: 'Pair with recall to retrieve later, forget to delete.'

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 well beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing internal cascading behavior, graceful degradation of LEI/FIGI enrichment, listing of unresolved identifiers, and source labeling. It also explains that the tool replaces multiple manual lookups, providing rich behavioral context that annotations alone cannot 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 well-structured with front-loaded examples and clear sections for supported types, but it is somewhat verbose. For instance, the detailed breakdown of company resolution and the list of example queries could be condensed. While every sentence adds value, some redundancy exists (e.g., repeating the 'Use FIRST' guidance).

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

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

Given the tool's complexity (2 params, no output schema, but annotations cover safety), the description is remarkably complete. It explains the return value structure (labeled identifiers, unresolved list), graceful degradation, and internal cascading. It covers all major aspects needed for an agent to correctly invoke and interpret the tool's results.

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

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

Schema coverage is 100% and both parameters are described, but the description adds significant value beyond the schema. It explains what each entity type returns (e.g., for 'company': CIK, ticker, LEI, FIGI, ownership info, unresolved list; for 'drug': RxCUI, ingredient, brand, citation). It also provides concrete examples like 'AAPL' and 'ozempic', making the parameter semantics much clearer.

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

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

The description starts with example queries that clearly illustrate the tool's purpose: resolving names to canonical identifiers. It explicitly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' The phrase 'Use FIRST whenever you have a name but need an ID' distinguishes it from siblings like entity_profile and compare_entities, which are for different stages.

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 strong usage guidance: 'Use FIRST whenever you have a name but need an ID' and gives example queries. It implies the tool is the primary entry point for name-to-ID resolution. However, it does not explicitly mention when to use alternatives (e.g., entity_profile after obtaining an ID) or exclude cases, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks results, and surfaces the most/least recognized. This enriches the agent's understanding beyond annotations without contradiction.

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

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

Two sentences, each earning its place. First sentence captures core purpose, second elaborates on method, use case, and output. No wasted words; front-loaded with key action.

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 multi-entity comparison tool with inner tool calls and no output schema, the description adequately covers input semantics, process (using ai_visibility_check), and output format (ranked list with score, confidence, signal density). It does not address edge cases or error handling, but given the annotations (read-only, idempotent), this is acceptable.

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 valuable semantic information beyond the schema: for 'entities', it states 'First entry treated as the 'subject' for narrative; rest are competitors.' This clarifies the role of the first entity, which is not in the schema description.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side', specifying the verb 'compare', the resource 'AI visibility', and the scope 'multiple entities'. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic) by focusing on AI visibility ranking.

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 a concrete use case: 'competitive AI-marketing audits' with an example question. While it does not explicitly exclude alternatives, the description implies when to use this tool over others (e.g., for multi-entity AI visibility comparison). 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?

Beyond annotations (readOnly, idempotent, openWorld), the description discloses key behaviors: partial failures degrade gracefully, bundlephobia first measurement latency (5-30s), and sources_failed field. No contradiction with annotations.

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

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

Description is informative but somewhat lengthy; however, every sentence adds value. Front-loaded with purpose and usage. Could be slightly tighter, but no wasted words.

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

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

Despite no output schema, the description fully enumerates return fields, explains partial failure behavior, and covers edge cases (new version latency). Complete for a composite tool with two data sources.

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 no new meaning beyond what the schema already provides (package name, version defaulting). No extra semantics needed.

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

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

Description clearly states the verb 'check' and resource 'npm package', and distinguishes from siblings by specifying the composite nature (deps.dev + bundlephobia) and ecosystem scope. It precisely conveys what the tool does.

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

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

Explicitly states when to use ('is X safe / popular / small', 'what does adding lodash cost me') and when not to use (non-npm ecosystems, directing to deps.dev directly). Provides clear context for agent decision-making.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flagging. 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?

Two well-structured sentences. The first covers purpose and when-to-use; the second adds technical specifics. Every sentence provides distinct value 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?

Despite no output schema, the description explains return structure: top-N passages with character offsets and similarity scores. Covers caps, truncation, and pairing with another tool. Sufficient for an agent to invoke and interpret results 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 good descriptions. The description reinforces the intended usage ('Pass the text you already pulled...') and provides explicit query examples (e.g., 'drug interactions with warfarin'). Adds clarity on limit default and range beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and explains the use case. It distinguishes from sibling tools like ask_pipeworx_grounded by showing how they pair, making the tool's specific role unambiguous.

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

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

Explicitly advises using when a record is too large for the prompt, saving context. Mentions pairing with ask_pipeworx_grounded. Lacks a direct 'when not to use', but the context strongly implies alternative if the record fits in the prompt.

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 and idempotentHint; description adds no additional behavioral context (e.g., significance threshold, data source, or return format).

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

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

Single sentence is efficient with no redundancy, but could be expanded slightly without losing conciseness.

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

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

For a simple tool with an output schema, the description is minimal; lacks parameter details and contextual information needed for an agent to use 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?

With 0% schema description coverage, the description does not explain any parameters; 'gencode_id' and 'tissue' remain undefined in meaning or format.

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

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

Description clearly states it returns significant single-tissue eQTLs for a gene, but fails to differentiate from sibling tools like 'tissues' or 'median_expression'.

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

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

No guidance on when to use this tool versus alternatives; no context on prerequisites or 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 fully discloses behavioral traits beyond annotations: it creates a persistent subscription, requires OAuth, returns a subscription ID, and details delivery channel behaviors (always-on feed, optional email/SMS with 10/day cap, webhook with HMAC signing and auto-disable after 10 failures). No contradiction with annotations (idempotentHint=true, destructiveHint=false, readOnlyHint=false).

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

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

The description is front-loaded with the main action and returns. It contains detailed examples but remains efficient. Minor redundancy (SMS cap mentioned twice), but overall well-structured and not overly verbose for the complexity.

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

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

Given the tool's complexity (multiple subscription types, delivery channels, prerequisites, and no output schema), the description is comprehensive. It covers authentication requirements, type-specific parameters, delivery options with constraints, and behavioral details like webhook authentication. No gaps for an AI agent to safely invoke it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the 'type' enum options with real-world examples (e.g., sec_8k items codes, polymarket_edge topic) and providing detailed parameter formats for each type. The delivery object is also explained with validation and secret handling. This exceeds the schema alone.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation. Mentions specific subscription types and delivery channels, making the purpose unambiguous.

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

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

The description explains when to use (for proactive monitoring) and notes prerequisites (Pipeworx OAuth account, anonymous/BYO cannot persist). It mentions caps and verification requirements for SMS. However, it does not explicitly state when not to use or compare with alternatives like real-time queries, though siblings provide context.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral context: returns category-bucketed example questions with exact tool+argument shapes, drawn from a live catalog of thousands of tools. No contradiction.

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

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

The description is detailed but well-structured with examples of user queries and a list of categories. It could be slightly more concise, but every sentence adds value.

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

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

Given the simple parameter set, no output schema, and rich annotations, the description fully explains what the tool returns and when to use it, covering all needed context for an AI agent.

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

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

Schema coverage is 100% with one optional 'topic' parameter. The description explains the allowed values (finance, pharma, etc.) and the effect of omitting it (full spread), adding meaning beyond the schema.

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

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

The description clearly states that this tool is the onboarding entry point for suggesting example questions about what Pipeworx can do. It lists specific example user queries and the categories of questions returned, distinguishing it from other tools like ask_pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning to call meta-tools like ask_pipeworx, entity_profile, etc., providing clear when-to-use guidance 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?

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context by specifying the exact return contents and clarifying that the tool serves as a lookup for tissue IDs, without contradicting any 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 well-structured sentences, front-loaded with the GTEx context and immediately covering the return data and use case. Every word adds value; 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?

With no parameters and an output schema present, the description provides complete context: what the tool does, what it returns, and why the returned ID is important for downstream tools. It is self-contained for the intended use case.

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?

There are zero parameters, so the baseline is 4. The description adds useful context about the output and purpose, which is sufficient given that there is nothing to document about inputs.

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

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

The description clearly states it provides a catalogue of GTEx tissue sites and returns specific fields (tissueSiteDetailId, display name, parent tissue site, sample counts, colour code). It distinguishes itself from sibling tools by focusing solely on tissue metadata and the canonical spelling of tissue IDs.

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 mentions that the tissue ID returned is what every other GTEx expression and eQTL tool expects, which signals when this tool should be consulted. It also states it answers which tissues GTEx covers, but it does not name alternative tools or provide direct exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context about the output (ranked genes with Gencode id, gene symbol, median TPM), the optional mitochondrial filter, and the configurable result count, going beyond the annotations without contradicting them.

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

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

Three focused sentences. The first sentence establishes the tool's core function, the second details the output, and the third gives a concrete use case. No wasted words or redundancy with the schema.

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 four-parameter read-only tool with full schema coverage and an output schema, the description covers the essential aspects: what it does, what it returns, example inputs, and an optional filter. It is complete enough for an agent to invoke correctly without further clarification.

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 each parameter is already described. The description reinforces the meaning of 'tissue' and mentions the result count and mitochondrial filter, but does not provide significant additional semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns the genes with the highest median expression in a specified human tissue, using a specific verb ('returns') and resource (GTEx Portal). It differentiates from siblings like median_expression by emphasizing ranking by median TPM and providing concrete examples (Liver, Whole_Blood).

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 ('answers which genes are most highly expressed in human liver, brain or blood') and explains the required tissueSiteDetailId format. It does not explicitly name alternatives or exclusions, but the use case is well implied.

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

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

The description goes beyond annotations by clarifying ownership enforcement, that the row is deactivated not deleted (aligning with destructiveHint=false), and that historical events stay accessible via recent_alerts. This adds significant behavioral context beyond the structured 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 with no wasted words. The first sentence states the core action and constraint, the second explains the side effect. 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 one-parameter tool with no output schema, the description covers all necessary aspects: purpose, ownership constraint, effect on data (deactivation vs deletion), and consequence for historical tracking. It is complete given the tool's simplicity.

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 has 100% coverage with a description for the required 'id' parameter stating it's a UUID returned by subscribe. The description restates 'by id', adding minimal extra value, but the schema already does well. Since coverage is high, baseline is 3, and the description adds the origin hint (returned by subscribe), so 4 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 starts with a specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing it from its sibling 'subscribe'. It adds ownership enforcement and deletion behavior, making the purpose unambiguous.

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

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

The description states ownership enforcement and the deactivation vs deletion behavior, providing context for when to use this tool. It also mentions that historical events remain available via recent_alerts, guiding the agent on related tools. However, it does not explicitly list when not to use it or compare with alternative cancellation methods.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and non-destructive, but the description adds critical behavioral context: the verdict enum, the structured/grounded actual value with citation, and especially the distinction between could_not_verify (verification failed, not evidence) and unsupported (no source found). This is far beyond what annotations convey and directly helps the agent interpret results 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 relatively lengthy but structurally sound: it opens with invocation cues, states the primary use, explains the two routing paths, enumerates return values, and provides essential caveats. Every sentence carries information, and the length is justified by the tool's complexity. It earns a 4, not a 5, because a few redundant phrases (e.g., listing example phrasings twice) could be trimmed.

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?

This is a complex tool with nuanced return values and failure modes. The description covers the full workflow, defines each verdict, explains error semantics (verification_error{stage,detail}), and even quantifies the efficiency gain ('Replaces 4–6 sequential calls'). Without an output schema, the description carries the burden of explaining return structure, and it does so thoroughly.

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

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

Schema description coverage is 100% for both parameters (claim and tolerance_pct), so the baseline is 3. The description reinforces the purpose of tolerance_pct by mentioning "exact percent-delta math" and hallucination-detection use, but the schema already explains the default and range. It doesn't add substantial new semantics beyond the schema, so a 3 is appropriate.

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

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

The description clearly states the tool's verb+resource: natural-language claim verification against authoritative sources. It opens with concrete invocation patterns ("Is it true that…", "fact check") and distinguishes itself from siblings by explaining it replaces 4–6 sequential calls. The two distinct paths (SEC EDGAR for company-financial claims vs. grounded pipeline for other facts) further crystallize its 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?

It explicitly says "Use whenever the agent needs to check whether something a user said is factually correct," giving a clear when-to-use directive. It also describes the automatic routing logic, implying that users don't need to decide between paths. However, it doesn't explicitly mention when not to use it or name alternative tools, though the sibling list makes alternatives apparent.

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