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?

Annotations already establish readOnly/openWorld/idempotent behavior. The description adds valuable context beyond that: it routes to 5,798 tools, fills arguments automatically, and returns stable pipeworx:// citation URIs. This gives the agent a useful model of what happens when the tool is invoked.

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 instruction and includes useful examples and source categories, but it is longer than necessary and slightly repetitive ('Use whenever', 'START HERE', and the breaking-news note overlap in purpose). It is structured enough to follow but could be tightened.

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 routing tool of this complexity, the description covers the main operational facts: source domains, behavior, output form with citations, trigger phrases, and an explicit sibling alternative. There is no output schema, but the examples and routing explanation provide sufficient context for correct invocation.

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

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

Schema description coverage is 100%, and the description adds no parameter-specific details beyond the existing schema. The schema already documents that question is a natural-language query and that q, prompt, text, input, and query are aliases, so the description has little left to add.

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

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

The description states a precise function: route a factual question to the appropriate tool in a large verified-source library and return a structured answer with citation URIs. It clearly differentiates itself from web search and from deep_research, and the examples make the scope tangible.

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 tells the agent to prefer this over web search for factual/current-data questions, lists trigger phrases, and names deep_research as the alternative for broad multi-part questions. This gives 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=false. The description adds important behavioral context beyond annotations: candidate routing improvements are enabled live only when under test, no candidate is currently active, and this tool is a full working router with no fallback. This transparency helps set expectations about variability.

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 sized and well structured: it leads with the beta relationship, then explains current state, usage, and experimental purpose. Every sentence contributes useful context, though it could be tightened slightly without losing meaning.

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 query-router tool: it states what the tool is, how it relates to ask_pipeworx, when to use it, what behavior to expect currently, and that it is fully functional. Combined with the comprehensive schema and safety annotations, an agent has enough to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six aliases for the question parameter. The description adds the useful note that arguments match ask_pipeworx, but it does not need to restate parameter semantics when the schema already covers them.

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

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

Description clearly identifies ask_pipeworx_beta as the beta version of ask_pipeworx: an identical universal router with the same 5,798 tools, arguments, and response shape. It explicitly frames it as the experimental edge, distinguishing it from the stable ask_pipeworx sibling.

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

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

The description directly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router. It does not explicitly state when not to use it, but the beta/experimental framing and sibling comparison provide clear 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?

Discloses refusal behavior and failure modes: explicit refusal with refusal_reason values like 'not_in_source' or 'data_truncated'. Also reveals it costs one extra LLM call. This goes well beyond the readOnly/idempotent annotations and never contradicts 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?

Dense but well organized: purpose, mechanism, return shape, usage, and cost each earn their place. The critical facts are front-loaded in the first sentence, and the rest builds 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?

With no output schema, the description supplies the full success and refusal return shapes, including example refusal reasons. It covers the routing scale, grounded extraction constraint, and cost tradeoff, leaving no significant gap for an agent to invoke it correctly.

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

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

Schema covers the question parameter 100%, including aliases and natural-language description, so the baseline is 3. The tool description adds no additional parameter-level detail beyond referring to the general question-answering mode, which is acceptable but not additive.

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 opens with 'Hallucination-resistant answer mode for high-stakes reads' and explains the exact mechanism: it routes like ask_pipeworx, fetches data, and extracts an answer using only the tool result. This is a specific verb+resource with clear differentiation from the sibling 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 states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. It also names the alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost.

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?

The description goes far beyond the annotations: it discloses authentication and paywall requirements, latency expectations, iteration/gap-recovery behavior, the findings packet structure, gaps[] semantics, contradictions[], citation resolvability, and semantic excerpting. These behavioral details are not available from the annotations alone, and nothing contradicts the readOnly/openWorld/idempotent hints.

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

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

The description is dense and front-loaded with the most important routing and auth facts, and nearly every sentence earns its place given the tool's complexity. However, it somewhat repeats depth-tier details already present in the schema enum description and packs many caveats into one long block, so it is not maximally 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?

There is no output schema, so the description correctly carries the burden of explaining return semantics: findings packet fields, citation URIs, gaps[], contradictions[], excerpting behavior, and expected latency. Combined with the annotations and input schema, an agent has enough context to select, invoke, and interpret 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%, so the baseline is 3. The description adds value by giving example research questions, tying depth:'thorough' to a paid plan, and linking depth choices to second-hop iteration and latency. However, much of the depth-tier detail is already present in the schema's enum descriptions, so the additional semantic burden on the description is modest.

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

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

The description clearly states what the tool does: grounded multi-source research across Pipeworx's 1517 structured data sources, decomposing questions into facets and routing them in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx, making its purpose and scope unambiguous.

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

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

The description gives explicit usage guidance: use ask_pipeworx when not signed in and for single lookups, while deep_research is best for broad/multi-part questions over structured data. It also discloses the account and paid-tier requirements, giving clear go/no-go conditions for invocation.

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?

The description discloses far more than the annotations: it explains parallel fan-out across multiple sources, soft-fails for the USPTO patents API sunset, the expected empty FDA section for non-biologic companies, the semantics of sources_used/sources_failed, and the resolved:false private-company behavior. This is exemplary behavioral transparency.

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

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

The description is long, but it is front-loaded with trigger examples and packed with necessary operational details. Every major behavioral and return-semantic point earns its place, though some redundancy around source enumeration could be tightened.

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

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

With no output schema, the description must carry return-value documentation, and it does: it lists all returned sections (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) plus sources_used/failed. It also covers error/edge cases, making it complete for a tool of this 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 already 100%, but the description adds meaningful detail beyond the schema: type values are interchangeable, value can be ticker/CIK/name, names resolve via SEC EDGAR match, and person/place support is coming soon. This materially improves parameter understanding beyond the raw schema.

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

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

The description names a specific verb-resource pair ('full cross-source profile of a US public company') and includes many concrete trigger examples. It clearly differentiates itself from chained single-pack lookups and is unambiguous about being a holistic entity profile tool.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies accepted input forms, how names resolve, and what happens for private companies, giving the agent strong selection and invocation 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 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 mark the tool as read-only and idempotent, but the description adds substantial non-obvious behavior: gross spreads with no Kalshi fee modeling, keyword-overlap matching rather than shared resolution sources, unclassified legs never being paired, and null temporal_alignment meaning the computation could not be completed. No contradiction with annotations.

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

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

The description is long, but the tool is complex and has no output schema, so the detailed flag and code reference is largely earned. It is front-loaded with purpose and modes and uses textual headings to organize safety fields, though some redundancy in mode reminders and flag lists keeps it from a 5.

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

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

Given the absence of an output schema, the description is impressively complete: it covers response shape, compatibility codes, skipped-pair counters, fee treatment, and temporal-alignment semantics. It does not, however, specify behavior when no parameters are provided or whether topic and explicit parameters are mutually exclusive, which are minor but real 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%, so the baseline is 3, but the description adds meaningful semantic context beyond the schema: it explains the two modes, that explicit parameters override the topic-mapped side, and that both modes run the same token-overlap matcher. The concrete examples further help an agent construct valid calls.

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

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

The first sentence states a specific verb and resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. This clearly differentiates it from sibling Polymarket-only tools and explains the output direction (Kalshi − Polymarket).

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 clearly gives mode selection guidance: use the pre-mapped topic shortcuts or the explicit kalshi_event_ticker + polymarket_event_slug pair for custom comparisons. It also warns that most pre-mapped topics are not currently tradeable and that equivalent bet shapes are required for the spread to be a real signal.

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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, and the description adds rich behavior beyond that: ambiguity handling ('when a name matches more than one instrument it asserts nothing and returns figi_candidates'), explicit unresolved reporting ('stated explicitly under unresolved rather than omitted'), source-labelling of identifiers, the internal cascade across lookup endpoints, and graceful degradation when GLEIF/OpenFIGI are unavailable. This gives the agent an accurate model for interpreting results, not just call safety.

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 front-loaded (examples, core function, usage directive) and every sentence carries information with no fluff. However, it is structured as one run-on paragraph with deeply nested parentheticals — the 'company' parenthetical alone spans roughly 200 words and buries important distinctions like figi_candidates and the unresolved field. The density is justified, but the formatting actively hurts scannability for an 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?

For a tool with no output schema, the description bears the full interpretive burden and succeeds: it names the response fields an agent needs (figi_candidates, unresolved), enumerates output identifiers for both entity types, and covers edge cases (non-equity instruments, non-US issuers, ambiguous names, source unavailability). Nothing an agent needs to call or interpret this tool correctly appears to be missing.

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

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

Schema description coverage is 100%, setting a baseline of 3, but the description adds genuine meaning: it expands the 'company' type into a cross-source identity spine (EDGAR CIK, GLEIF LEI with ownership chains, OpenFIGI), explains the ISIN-to-LEI resolution behavior, and clarifies which value forms are accepted. The schema's value description already carries the 'entity name only' guidance, so this is an enhancement on top of a strong schema rather than a rescue — a solid 4.

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

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

The description names a precise operation — resolving a user-spoken NAME into canonical/official identifiers — and anchors it with concrete example queries ('what's the ticker for…', 'who owns X', 'is X a subsidiary of Y'). It enumerates the supported types and identifier systems it returns (CIK, ticker, LEI, FIGI, RxCUI), and the position-stating sentence 'Use FIRST whenever you have a name but need an ID' separates it sharply from sibling tools like entity_profile or validate_claim.

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 directive 'Use FIRST whenever you have a name but need an ID' is an explicit when-to-use condition, reinforced by the mapped user phrasings at the top and the catalog of accepted inputs (ticker, CIK, ISIN, brand/generic name). It stops short of a 5 because it never names sibling alternatives explicitly or states an explicit when-not-to-use case — the exclusion ('if you already have the ID') is only implied.

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

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

Annotations already 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.