Hpo Api

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

Description adds value beyond annotations: explains cost implications (free default, pay for Anthropic), model selection, and response structure. Annotations already indicate safe read-only operation; description aligns and enhances with behavioral details.

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: purpose+output, model details, use cases. Front-loaded with key information; 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?

Covers purpose, model options, output format, and use cases. No output schema, but description specifies per-model fields. Missing error handling or rate limits, but acceptable given tool 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?

Schema coverage is 100%, but description adds context: default model for 'models', explanation for '_apiKey', and optional 'context' for disambiguation. This enriches understanding beyond schema alone.

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

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

Clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. Specific verb 'probe', resource 'LLMs', and outcome 'score visibility'. Distinguishes from siblings like ask_pipeworx by focusing on generic brand visibility.

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 clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains model options (default free, Anthropic with BYO key). Lacks explicit when-not to use or alternatives, but context is adequate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: routes to 5,529 tools across 1,455 sources, fills arguments, returns stable pipeworx:// citation URIs, and works on every tier with one fast call.

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 adds value, including trigger phrases, examples, and explicit alternative routing. It's front-loaded with the key directive and structured to allow skimming.

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 compensates by stating the return format (structured answer with citation URIs). It covers scope, alternatives, and usage context, making it a comprehensive entry-point description.

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 parameters with descriptions, including the question field and aliases. The description doesn't add parameter-specific semantics beyond schema, but schema coverage is 100% so the schema itself is sufficient; baseline 3 applies.

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

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

The description clearly states the tool's purpose: answering factual questions about real-world entities/events/numbers using authoritative structured data. It lists specific domains and provides examples, distinguishing it from sibling tools like web search and deep_research.

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

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

Explicitly instructs to prefer over web search, start here for most questions, and step up to ask_pipeworx_grounded for single-answer evidence or deep_research for broad queries. Includes trigger phrases and examples, giving clear when-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 non-destructive behavior. The description adds valuable context beyond these: candidate routing improvements are tested live, currently no candidate is active so it behaves identically, and it does not fall back to anything—it is a full working router. This proactively explains the experimental nature without contradicting annotations.

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

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

The description is three sentences and front-loaded with the essential identity ('Beta version of ask_pipeworx'). Every sentence earns its place: identity, current status, usage guidance, and a clarification that it is not a fallback. It is dense but not padded.

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 beta query tool with no output schema, the description provides complete context: it defines the tool, states its exact relationship to the stable sibling, explains the testing mechanism, and assures the agent it is a fully functional router. This is sufficient for an agent to understand behavior 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?

The input schema is fully self-documenting with 100% coverage: all six parameters are aliases for 'question' and are explicitly described. The description only says 'same arguments' as ask_pipeworx, adding no additional parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states this is the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx sibling by labeling itself the experimental edge.

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

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

The description gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidate, so it matches ask_pipeworx exactly) and explains that results are compared against the stable router, which fully informs when to select this tool.

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

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

Annotations already cover read-only, idempotent, non-destructive safety. The description goes far beyond by detailing internal routing across '5,529 across 1455 sources,' the extraction process using only tool results, the exact return format with evidence and confidence, and explicit refusal reasons ('not_in_source', 'no_tool_match', etc.). This adds substantial behavioral context not present in annotations.

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

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

The description is dense but every sentence earns its place: purpose, process, return format, refusal reasons, usage guidance, and cost trade-off. It is front-loaded with the key purpose and structured logically, with no filler.

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

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

The tool is complex (routing, extraction, refusal modes) and has no output schema, so the description fully compensates by specifying the exact success and refusal return objects. It also covers usage context, cost implications, and alternative tool preference, making it complete for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, with all params documented as aliases for question. The description adds semantic context by explaining that the question is routed to internal tools and arguments are filled, giving the parameter a higher-level meaning beyond mere alias listing. This is a modest addition over a baseline of 3.

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

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

The description opens with a clear, specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It then explains the routing and extraction mechanism, distinguishing itself from sibling ask_pipeworx by emphasizing grounded answers with verbatim evidence and explicit refusals. This is a specific verb+resource+scope that clearly separates it from related tools.

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

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

The description explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and provides an alternative: 'prefer ask_pipeworx for casual lookups.' It also mentions the cost trade-off (one extra LLM call), giving clear guidance on choosing between this tool and its sibling.

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 extensive behavioral details beyond annotations: low-confidence match behavior, closed market handling, wide-spread warnings, resolution-rule risk, news fallback, parent event extraction, and blocking routes. This adds significant transparency. Annotations (readOnlyHint=true, openWorldHint=true) are consistent and reinforced.

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 very long and contains extensive examples and detail. While it is well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), its length may hinder quick parsing by an AI agent. Not all sentences are essential for a minimal understanding, but each adds specific value for a complex tool.

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

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

Given the tool's complexity (multiple classifiers, fan-out logic, edge cases like low-confidence matches, closed markets, wide spreads, resolution-rule risk) and no output schema, the description is remarkably complete. It covers all major scenarios and response shapes, leaving minimal ambiguity for an agent.

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

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

Schema coverage is 100%, providing baseline 3. The description adds meaningful context: explanation of depth (quick vs thorough, default thorough), include_raw (false recommended, why), and market input flexibility. Examples further clarify usage. This adds value beyond schema documentation.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and provides explicit usage cases ('should I bet on X', 'what does the data say about Y'). The purpose is distinct from sibling tools like polymarket_arbitrage or polymarket_edges, though not directly contrasted.

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 contexts: 'Use for should I bet on X...' and includes many examples of when to use. However, it does not explicitly state when NOT to use this tool or mention alternative tools for different tasks (e.g., arbitrage or edges). The usage is implied but lacks 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 indicate read-only, idempotent, non-destructive. The description adds specific behavioral details: for companies, pulls latest 10-K data with correct off-calendar fiscal year handling; for drugs, pulls FAERS counts, FDA approvals, trial counts. Also mentions sorted results and 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?

Description is a single paragraph but is dense with information. It is front-loaded with trigger phrases. Could be improved with bullet points, but it remains concise without redundancy.

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

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

Despite no output schema, the description explains that returns paired data with citation URIs. It covers both entity types' specific data points and the sorting behavior. A bit vague on exact output format, but sufficient for an agent to understand the tool's capability.

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

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

Schema coverage is 100%, but description adds significant context: 'type' maps to data source and specific metrics, 'values' examples with tickers and drug names clarify proper input. The constraint of 2-5 items and the difference between company and drug inputs are well explained.

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 compares 2-5 companies or drugs side-by-side. It lists example query phrasings and specifies what data each type returns (financials for companies, adverse events for drugs). It distinguishes itself from sequential single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This tells the agent when to use this tool (comparing entities) and when not to (single entity lookups). Clear context and alternatives provided.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses account and plan requirements, the findings packet structure (verbatim evidence, confidence, source, fetched_at), gaps[] behavior (never invented), second-hop gap recovery, contradictions[], semantic excerpting, citation_uri fetchability, and expected latency (15-90s). This is far richer than annotations alone and sets clear expectations.

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 and well-structured, with critical operational facts (account, fallback, latency) front-loaded. Every sentence contributes meaningful information, though some details (e.g., citation_uri internals, elaborate hop mechanics) could be condensed without losing core value. Appropriate for a complex tool, but not perfectly concise.

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

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

With no output schema, the description fully covers return values: findings packet, gaps[], contradictions[], hop field, and citation_uri. It also explains behavior, limitations, alternatives, and performance, giving an agent everything needed to decide when to call it and what to expect. This is highly 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?

The input schema already provides high-quality descriptions (100% coverage) for both question and depth. The description adds useful context: broad/multi-part questions are acceptable, depth levels map to number of facets, and 'thorough' requires a paid plan. However, much of the depth-specific detail is also in the schema, so the incremental value is moderate.

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

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

The description clearly defines deep_research as a grounded, multi-source research tool over 1,455 structured data sources, decomposing questions into parallel tool calls. It explicitly differentiates from ask_pipeworx ('this is NOT open-web search', 'For a single lookup use ask_pipeworx') and from current-news tools, making its purpose and scope unmistakable.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It also states when not to use it (single lookups, breaking/colloquial news) and names the alternative (ask_pipeworx), plus account tier requirements and fallback behavior. This is exemplary usage guidance.

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

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

Annotations already indicate a safe, read-only, idempotent operation (readOnlyHint, idempotentHint, destructiveHint=false). The description adds key behavioral details: returns top-N relevant tools with full schemas and curated examples, ready to call without a second lookup. 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 a single, well-structured paragraph that starts with the core purpose, provides concrete examples, explains the return value, and gives usage guidance. Every sentence is informative; 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 the lack of an output schema, the description fully explains what the tool returns (tool names, descriptions, input schemas with examples). Annotations cover safety constraints. The tool is self-contained and the agent can immediately understand its role and behavior.

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 6 parameters. The description adds value by clarifying that 'query' accepts natural language and lists aliases (task, q, description, search). It also explains the 'limit' parameter's default and max. This goes beyond 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's purpose: 'Find tools by describing the data or task.' It lists numerous example domains (SEC filings, drugs, real estate, etc.) and distinguishes itself from siblings like 'search' by emphasizing that this tool discovers tools themselves, not data. The explicit instruction 'Call this FIRST when you have many tools available and want to see the option set' reinforces its unique role.

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

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

The description explains when to use: 'when you need to browse, search, look up, or discover what tools exist' and recommends calling it first when many tools are available. It does not explicitly state when not to use it, but the context implies it is for tool discovery rather than direct data queries. The guidance is clear and actionable.

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 that the tool lists HPO terms and accepts specific ID formats, but does not reveal additional behavioral traits such as pagination or rate limits.

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

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

The description is concise with two sentences that include examples and front-loaded purpose. It efficiently conveys necessary information without extraneous text.

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 one parameter and an output schema, the description sufficiently explains input format and return content (HPO phenotype terms). The presence of an output schema covers return value details.

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

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

The schema has 0% description coverage for the 'id' parameter. The description compensates by specifying valid formats (OMIM:N, ORPHA:N, MONDO:N) and providing examples, which adds significant 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 lists HPO phenotype terms for a disease ID, using specific verbs and resource names. It distinguishes the tool's purpose with example queries and a concrete example ID (OMIM:154700).

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 usage context ('Use to enumerate clinical features of rare diseases') and example IDs, but does not explicitly state when not to use this tool or mention alternatives like term_children or gene_diseases from the sibling list.

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

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

Annotations already declare safe, idempotent, read-only behavior. The description supplements with specific source dependencies (USPTO sunset) and output structure (fields returned). This provides useful operational transparency without contradicting annotations.

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

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

The description is concise and front-loaded with example queries and core purpose. Each sentence adds distinct value—usage guidance, parameter clarification, behavioral notes. No fluff.

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

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

Despite lacking an output schema, the description enumerates all return fields and their sources, including edge cases (patents sunset). It fully covers input requirements and output expectations for a multi-source profile tool.

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

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

The schema already covers both parameters with descriptions. The description reinforces the value format with concrete examples and explicitly states unsupported formats (names). The 100% schema coverage sets a baseline of 3; the extra usage context and examples justify a 4.

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

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

The description clearly states the tool's purpose: producing a holistic cross-source profile for US public companies. It explicitly distinguishes from chaining multiple lookups and from sibling tools like resolve_entity.

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

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

The description explicitly states when to prefer this tool (when user wants a holistic view) and when not to use it (if only have a name, use resolve_entity first). It also contrasts with chaining multiple single-pack lookups.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds no new behavioral context beyond 'Delete', which aligns with annotations. 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?

Two sentences plus a brief sibling mention. Every sentence serves a purpose, front-loaded with action and use case.

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 single parameter, no output schema, and annotations covering safety, the description is complete for this simple 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?

Only one parameter 'key' with schema description 'Memory key to delete'. Schema coverage is 100%, so the description adds no additional 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 action ('Delete'), the resource ('previously stored memory'), and the mechanism ('by key'). It distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Provides explicit contexts for use: when context is stale, task done, or clearing sensitive data. Doesn't explicitly mention when not to use, but the rationale is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety and behavior are clear. The description adds context about input format (NCBIGene:N) and use cases, which is beneficial. No contradictions are present. The description does not detail rate limits or pagination, but given the strong annotations and simple operation, it is sufficient.

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 compact, with no wasted words. It front-loads the purpose with typical question forms, then provides context and an example. Every sentence adds value, making it easy for an agent to quickly understand the tool's function.

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 (1 parameter, output schema exists), the description covers the fundamental aspects: purpose, input format, use cases, and an example. It does not mention error handling or missing gene IDs, but the output schema likely covers return structure. For a basic lookup tool, it is nearly 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 0%, so the description must compensate. It specifies the 'id' parameter format as 'NCBIGene:N' and gives an example (NCBIGene:7157). However, the input schema example shows '2309' without the prefix, creating a slight inconsistency. The description adds meaning but could be more precise about the prefix requirement.

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 fetches diseases associated with a gene ID, provides typical query phrasings ('What diseases is gene...'), and gives an example with NCBIGene:7157 (TP53). The verb 'fetch' and resource 'diseases associated with a gene ID' are specific and unambiguous. While no explicit sibling differentiation is given, the purpose is distinct enough given the sibling list.

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 says 'Use for gene-to-disease lookups in rare-disease research, variant prioritization', providing explicit context. However, it does not mention when NOT to use this tool or suggest alternatives like disease_phenotypes for the reverse direction. The guidance is present but lacks exclusionary or comparative advice.

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 non-destructive, read-only, idempotent behavior. Description adds that it fetches the page and extracts data, but doesn't elaborate on potential failures or limitations.

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

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

Two sentences plus a compact bullet list, front-loaded with the main action and output, 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?

No output schema, but description specifies output format as single text blob. Parameters and behavior are well-covered, though could mention that the URL must be publicly accessible.

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

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

Schema covers 100% of parameters with descriptions. Description adds no new semantic value beyond paraphrasing the schema fields.

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 generates an llms.txt file for a URL, extracting key metadata, and distinguishes it from sibling tools like scan_competitor_ai_presence by specifying its exact output format and use case.

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 three use cases (client site indexing, own project drafting, competitor auditing), but lacks when-not-to-use guidance or alternatives.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. Description adds return fields and the include_inactive parameter behavior, providing moderate additional context without contradiction.

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

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

Two efficient sentences: first states purpose and output, second gives usage guidance. No wasted words, front-loaded key information.

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

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

No output schema, but description lists return fields. Tool is simple with one optional parameter; annotations cover safety. Adequate for 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 covers the single parameter with description (100% coverage). Description does not add new parameter meaning beyond listing return fields, so baseline 3 is appropriate.

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

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

Description explicitly states the verb 'List' and resource 'subscriptions' with scope 'the caller's active subscriptions'. It lists specific return fields, distinguishing it 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?

Explicitly advises when to use: 'to review what you're monitoring before adding more or to find an id to cancel'. Provides clear context, though does not explicitly state 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 provide no positive hints (all false), so the description carries the full burden. It discloses the write-like behavior (filing returns a token), rate limits, the fact that it's free, and the mechanism to check status later—none of which are in annotations.

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

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

Though longer than a one-liner, every sentence adds operational value—exclusions, token flow, rate limits—and it's structured logically from purpose to usage to mechanics. No redundancy or fluff.

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

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

Given no output schema, no substantial annotations, and a nested object parameter, the description covers all required aspects: categories, tool scope, message guidance, token workflow, account-free usage, and rate limiting. Fully self-sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds important context: how to phrase the message (in terms of Pipeworx tools, not user prompts) and the dual-use of claim_token (file vs. read). This goes beyond the schema, though not drastically.

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

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

The description opens with a clear action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and identifies the specific resource (Pipeworx feedback). It distinguishes from sibling tools by focusing on reporting issues/praise rather than data retrieval or research.

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

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

Explicitly specifies when to use (bugs, features, data gaps, praise) and when not to use (for tools from other MCP servers), including a clarifying 'Not sure?' rule. This is exemplary guidance that prevents misuse.

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 beyond: caching behavior (5min-1h), data source (CF analytics-engine), and no PII. Good additional behavioral context.

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?

Very concise: three bullet use cases, one sentence on window semantics, one on caching and data source. Front-loaded with key output. 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?

No output schema, but description fully explains return format (top tools, top packs, total call volume). Caching behavior and derivation from analytics are covered. Complete for a simple read-only tool.

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

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

Schema has 100% coverage with enum and description for window. Description adds semantic value by explaining trade-offs between short and long windows, enhancing schema info.

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

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

Clearly states it returns top tools, packs, and total call volume for recent windows (24h, 7d, 30d). Specific verb 'Returns' and resource defined. Distinguishes from siblings like discover_tools by focusing on trending data.

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

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

Provides three explicit use cases and explains window selection (shorter for hot, longer for steady-state). No explicit when-not-to-use or alternatives, but the context is clear enough.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds extensive behavioral details: how scans work, partition checks, fill checks against live CLOB depth, and when not to trade (realizable_edge_pp <= 0). 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 thorough but somewhat verbose, with dense technical details like Jaccard similarity and partition filter. However, it is well-structured, front-loaded with the main purpose, and each section adds value. Slightly over-detailed for conciseness, but still 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?

Despite no output schema, the description fully explains the response structure (opportunities[] with fields, partition_check in event mode). It covers fill check and custom sizing. References sibling tool polymarket_fill_risk for additional context. Complete for a no-required-param tool.

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

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

Schema coverage is 100% with descriptions for both parameters, but the description adds significant extra meaning: explains event expects a Polymarket event slug (with examples), topic is a seed question, and contrasts both modes. This enhances parameter understanding 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes three modes: no args for trending scan, event for single-event, and topic for cross-event. This differentiates it from sibling tools like polymarket_edges and polymarket_edge_tracker.

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: no args for trending, event for a specific market, and topic for cross-event scanning. It also notes that cross-event mode catches patterns single-event misses, and suggests using polymarket_fill_risk for custom sizing, which serves as a clear alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: caching (1h at KV level), model families, response structure, and edge computation details, contradicting nothing.

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 very long and dense with technical details. While it front-loads the core purpose, it dives into model specifics that could be shortened. Some redundancy exists (e.g., multiple edge explanations). Could be more concise without losing value.

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

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

With 9 parameters, no output schema, the description thoroughly explains the response structure (by_segment, diagnostics), edge computation, and filtering logic. It covers return values and model families completely for an agent to understand output.

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

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

Schema description coverage is 100%. The description adds extra context for many parameters (e.g., slippage_pp notes Polymarket fees, min_liquidity explains walking the book, min_partition_leg_kelly explains its purpose relative to partition arbs). Every parameter is well-explained 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 the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'Polymarket markets', and distinguishes from siblings by focusing on edge discovery.

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 is built for 'what should I bet on today' and explains when to use filters like min_liquidity and max_spread_pp. It notes Fed bets are excluded from ranking. While not explicitly stating when not to use, it provides adequate context for typical usage.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds crucial limitations: 60-day snapshot TTL, snapshot availability from enablement date, decay computed from daily closes not intraday. Also explains the meaning of trend and decay fields, going well 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?

Front-loaded with the core question, then breaks down response structure with bullet-like clarity, and ends with limitations. Every sentence adds value; no fluff. Despite length, it is efficient and well-organized.

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, yet the description fully covers return fields: tracked[] with full time-series, first_seen, trend, decay_pp_per_day; expired[] with lifespan_days; and snapshot_dates[]. Also explains decay computation and limitations. Complete for agent usage.

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

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

Schema coverage is 100% for both parameters. Description repeats the defaults and helps clarify the window parameter, but adds minimal new meaning beyond the schema's 'lookback in days' and 'which window family'. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?'. It explicitly distinguishes from sibling tools like polymarket_edges by focusing on historical time-series analysis rather than current state.

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 clear context on when to use: 'a fresh wide edge and a 3-week-old wide edge are different trades'. It explains the response structure but does not explicitly mention when not to use it or specify alternatives. Could improve by contrasting with raw edge data tool.

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

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

Goes beyond annotations (readOnlyHint, idempotentHint) by detailing behavioral traits: it only performs a risk check, does not execute trades, walks the order book ladder, and reports verdicts (clean|degraded|cannot_fill). Warns about thin books 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?

The description is dense and lengthy but well-structured with section headers (REQUIRES, SINGLE-MARKET, BASKET). Every sentence serves a purpose, though breaking into shorter paragraphs could improve readability slightly. Still acceptable given information density.

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 4 parameters, no output schema, and no nested objects, the description fully covers outputs (top_of_book, vwap_fill_price, slippage_pp, etc.) and basket-specific fields (theoretical_sum, realizable_sum, capture_ratio, thin_legs, forced_directional_risk). No missing information 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 coverage is 100%, but the description adds significant meaning: explains side default logic in basket mode ('auto from partition sum'), interprets size_usd as 'max spend on buys, target proceeds on sells,' and notes clamp range (10–1,000,000). This adds value beyond schema.

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

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

The description clearly states it performs an 'edge check against live CLOB order-book depth' for both single-market and basket modes, and explicitly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before those.

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

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

Provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the two modes (single-market vs basket), required parameters per mode, and warns about risks like partial basket fills converting arb to directional position.

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, openWorld, idempotent), the description adds substantial behavioral context: modes, response fields (leg-by-leg prices, spread array), safety fields (compatibility_warning, temporal_alignment, skipped counters), and the caveat that pre-mapped topics often yield warnings. This far exceeds annotation coverage.

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

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

The description is well-structured with clear sections, but it's relatively long. However, every sentence earns its place given the tool's complexity. Minor redundancy (e.g., 'pre-mapped' repeated) prevents a perfect score.

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

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

Given no output schema, the description thoroughly covers inputs, behavior, and outputs: leg-by-leg prices, spread array, safety fields, and error conditions. Complexity is high, yet the description equips the agent to correctly handle all cases.

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

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

Schema coverage is 100%, and the description enriches parameter meaning: topic gets a concrete list and explanation of pre-mapped shortcuts; explicit tickers are described as overrides. This adds value beyond schema descriptions, though the schema already provides adequate basics.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It details two modes (topic and explicit) and explains the response structure, clearly distinguishing this from sibling tools like polymarket_arbitrage.

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

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

The description provides explicit when-to-use guidance: two modes for different needs, warnings about compatibility and temporal alignment, and a note that real spreads are rare despite pre-mapped topics. This helps the agent decide when to invoke and how to interpret results.

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, destructiveHint, idempotentHint. Description adds scoping details (anonymous IP, BYO key hash, account ID) beyond 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 core purpose. No wasted words. Efficient and informative.

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

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

Covers retrieval and listing, scoping, and pairing with remember/forget. Lacks error handling details, but acceptable for a simple read-only tool with good annotations.

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

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

Schema coverage is 100% with parameter description. Description adds clarity that omitting key lists all keys, and explains key purpose (memory retrieval). Adds value beyond schema.

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

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

Clearly states the verb (retrieve/list) and resource (saved memories). Distinguishes from siblings remember and forget by mentioning them. Specific about scoping to an identifier.

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 without re-deriving. Implies alternatives (remember, forget) and when not to use them. Provides 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?

The annotations already indicate readOnlyHint=true (read-only), idempotentHint=true, and destructiveHint=false. The description adds value by explaining the side effect of mark_read (flagging events as read so next call shows newer ones) and the availability of an external endpoint, which are not covered by annotations alone. No contradictions are present.

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

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

The description is four sentences long, each serving a distinct purpose: purpose, return fields, filtering/mark_read usage, and alternative access. It is front-loaded with the core action and avoids redundancy with structured fields. Every sentence adds value with 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?

For a read-only list tool with 5 optional parameters and no output schema, the description covers all necessary aspects: what is returned, how to filter, the mark_read side effect, and even an alternative REST endpoint for non-LLM use. It is self-contained and sufficient for an agent to use correctly.

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

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

Schema documentation covers 100% of parameters, so baseline is 3. The description enhances understanding by providing examples ('type e.g. sec_8k') and clarifying that since is an ISO timestamp. This adds practical context beyond the schema's property 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 uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly distinguishing it from sibling tools like 'search' or 'recent_changes'. It also lists the key return fields (source, citation_uri, payload), which adds specificity.

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 mentions that polling works fine and points to an alternative REST endpoint, providing some context on when to use this tool. However, it does not explicitly state when NOT to use it or compare it to siblings like 'search_within' or 'subscribe'. More explicit exclusion guidelines would improve this dimension.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral details: it fans out to multiple sources (SEC, GDELT→GNews, USPTO), explains the fallback mechanism (GDELT preferred, GNews when rate-limited or 5xx), notes USPTO soft-failing due to API sunset, and outlines the return structure (changes grouped by source, total_changes count, 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 a single, dense paragraph that front-loads examples, clearly states the tool's purpose, explains the underlying mechanics, and ends with an explicit alternative. Every sentence contributes value with no wasted words.

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

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

Given the moderate complexity (multiple data sources, fallback behavior, failure conditions) and the absence of an output schema, the description provides sufficient context: it describes the return format (changes grouped by source, count, URIs), handles edge cases (soft-fails, rate limits), and gives a complete picture of what the tool does and returns. The annotations already guarantee safety and idempotency, so no further behavioral assurances are needed.

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 value beyond the schema by clarifying 'since' format details (ISO date or relative shorthand, suggesting '30d' or '1m' for monitoring), explaining that 'type' currently only supports 'company', and giving examples for 'value' (ticker or zero-padded CIK). This enriches the schema information without redundancy.

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 multiple concrete query examples and explicitly states it is a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists the data sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes itself from the sibling entity_profile tool by describing what it does that the sibling does not.

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 includes an explicit alternative: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also provides typical query examples and suggests using '30d' or '1m' for typical monitoring, giving clear direction on when and where to use this tool.

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

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

Description adds key behavior: memory scoped by identifier, authenticated vs anonymous persistence (24h), which goes beyond annotations. 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?

Concise at 4 sentences; front-loaded with purpose, then usage, then technical detail. 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?

For a 2-param tool with no output schema, description fully covers purpose, usage, persistence behavior, and relationships to siblings.

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

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

Schema covers both parameters with descriptions (100% coverage), description adds context like 'key-value pair' and examples, but doesn't add new meaning 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?

States 'save data the agent will need to reuse later' – a specific verb and resource. Distinguishes from siblings recall and forget explicitly.

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

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

Explicitly says 'use when you discover something worth carrying forward' with concrete examples, and contrasts with recall and forget.

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, and the description adds significant behavioral detail: it lists sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), explains that unresolved identifiers appear in an `unresolved` field rather than being omitted, and describes graceful degradation when GLEIF/OpenFIGI are unavailable. This goes well beyond the annotation baseline.

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 information-dense; each sentence adds value around the two entity types, sources, and failure handling. It starts with concrete user queries, which quickly clarifies intent. Slightly overstuffed with examples but earns its length given the tool's complexity.

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

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

With no output schema, the description compensates by detailing what is returned for each entity type: CIK, ticker, company_name, LEI, FIGI, parent/child ownership, and drug RxCUI with citation. It also covers behavior on partial resolution and the internal cascading of lookups, making the tool's behavior fully understandable.

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

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

Schema coverage is 100% with clear descriptions for `type` and `value`, including examples of formats (AAPL, 0000320193, 'ozempic'). The description essentially restates this input info without adding new parameter semantics, so it stays at the baseline for high schema coverage.

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

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

The description opens with user-spoken queries ('What's the ticker for…') and states its purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This specifies the verb (resolve), resource (name to ID), and includes supported types. It also distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID.'

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 clear usage context: 'Use FIRST whenever you have a name but need an ID.' It also details supported entity types and their inputs. However, it does not explicitly state when not to use it or name alternative tools for entity profiles (e.g., entity_profile), though the context implies it.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds detail about the internal behavior (probing with ai_visibility_check, ranking, returning score/confidence/signal density) without contradicting annotations.

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

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

The description is two sentences with an embedded example, no wasted words, and front-loads the main action and outcome.

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 4 parameters (all well-documented in schema) and no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by noting that the first entity is treated as the 'subject' for narrative, which is not in the schema. This extra context justifies a 4.

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

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

The description uses a specific verb "compare" and resource "AI visibility across multiple entities", clearly distinguishing it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic). The example question grounds the purpose concretely.

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

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

The description explicitly states the use case (competitive AI-marketing audits) and gives an example question. It implies when to use this tool versus ai_visibility_check (for single entities) and compare_entities (generic), but does not explicitly state when not to use it.

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

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

The description adds significant behavioral context beyond the annotations: explains the composite fan-out, return format details (summary block fields, per-advisory detail, links, alternative versions), and partial failure behavior (bundlephobia timeout 5-30s, sources_failed listed). This is comprehensive and aligns with annotations (readOnlyHint, openWorldHint, idempotentHint).

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 compact yet comprehensive. It front-loads the core purpose, then covers usage, return details, limitations, and failure modes in a logical flow. Every sentence earns its place; no fluff.

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

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

Despite no output schema, the description thoroughly explains the return structure (summary block fields, advisory details, links, alternatives) and handles edge cases (NPM-only scope, partial failures). The agent has enough information to correctly invoke and interpret results.

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

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

Schema coverage is 100% (both parameters described). The description adds value by clarifying that scoped packages are accepted for 'package' and that 'version' defaults to latest. This provides practical guidance 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 composite nature (combining deps.dev and bundlephobia) and specific purpose: answering 'is X safe/popular/small' or 'cost of adding lodash'. It uses specific verbs and resources, and distinguishes from sibling tools by being uniquely focused on npm dependency analysis.

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

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

Explicit usage context is given: 'Use whenever an agent asks ...'. Also notes ecosystem limitation: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly.' This helps the agent know when to use this tool vs. alternatives, though it doesn't explicitly state when not to use it.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value by stating that results are 'ranked terms with HP: IDs', which is behavioral insight beyond annotations. It does not contradict annotations.

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

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

The description is front-loaded with the core purpose and includes examples, but it is slightly verbose with multiple example phrases and could be trimmed without losing meaning. Still 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 the tool's complexity (3 parameters, output schema, rich annotations), the description covers purpose and behavioral context well but falls short on parameter semantics, which are needed for correct invocation. Adequate but with clear gaps.

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

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

The input schema has 0% parameter descriptions, so the description must compensate. While it implies the 'query' parameter is a clinical description through examples, it does not explain 'page' or 'limit' or their optionality. This is insufficient for a tool with 3 parameters.

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

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

The description clearly identifies the tool as a text search over the Human Phenotype Ontology (HPO), with specific verb 'search' and resource 'HPO'. It provides concrete query examples and states the use case for mapping clinical descriptions to ontology terms. This distinguishes it from sibling tools like search_within.

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

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

The description explicitly states when to use the tool: 'Use to map clinical descriptions to standard ontology terms for rare-disease workups, genomics, or clinical phenotype databases.' It gives clear context but does not mention when not to use it or provide alternatives, which would warrant a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: embedding model (BGE-base-en), windowing (500-char overlapping windows), character cap (200K chars with truncation flag). This goes well 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?

Well-structured: purpose first, then usage guidance, then pairing, then technical details. Every sentence adds value. Appropriate length for the tool's complexity.

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

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

Despite no output schema, the description specifies return format ('top-N passages with character offsets and similarity scores'). Input constraints, behavioral details, and usage context are all covered. 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 enriches each: text gets 'max ~200K chars' limit, query gets example phrases, limit gets default value. Adds meaningful context 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 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K body, article, long tool result) and output details (top-N passages with offsets and similarity scores). It distinguishes from sibling tools by focusing on intra-document search.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and describes pairing with ask_pipeworx_grounded. While it doesn't list explicit alternatives, the context is clear enough for selecting the tool.

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

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

Beyond annotations (idempotent, not destructive), description adds account requirements, delivery channels, and SMS cap. Idempotency behavior not elaborated, but overall transparency is good.

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

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

Single paragraph packed with information; could be more structured with bullet points, but remains readable and front-loads the purpose.

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

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

Covers return value, all subscription types with examples, delivery options, and limitations. No output schema, but description compensates adequately.

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

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

Although schema coverage is 100%, description enriches parameter meanings with concrete examples (e.g., items codes, delivery details). Adds value beyond schema definitions.

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

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

Clearly states it creates a subscription to a live-data event stream and returns the new subscription ID. Distinguishes from sibling tools like list_subscriptions 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?

Specifies prerequisites (Pipeworx OAuth account, verified phone for SMS) and supported types with examples. Does not explicitly state when not to use, but context of siblings implies 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?

The description adds behavioral context beyond annotations: it is the onboarding entry point, returns example questions drawn from a live catalog, and explains the effect of the optional topic parameter. 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 informative but slightly verbose with multiple alternative queries. However, it front-loads the purpose and remains structured, earning a solid 4.

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 return format and covers the optional parameter. It also positions the tool relative to sibling tools as the onboarding entry point, providing complete context.

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

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

Schema coverage is 100%, and the description enriches the single parameter by listing example topics (finance, pharma, etc.) and stating the behavior when omitted, providing concrete guidance.

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: returning category-bucketed example questions to onboard a new agent. It specifies the output format (questions with tool+argument shape) and distinguishes itself as the entry point for understanding Pipeworx capabilities.

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

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

Explicitly advises using this tool first when the agent does not know what Pipeworx can do, and provides guidance on calling with no arguments for a full spread or with a topic to focus. This gives clear when-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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by stating return fields (label, definition, synonyms, cross-references), which is consistent and not redundant.

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

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

Three concise sentences with front-loaded natural language query. Every sentence adds value: query pattern, purpose, ontology context, return fields, and example ID.

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 input (one string with examples) and the presence of an output schema (not shown but indicated), the description covers all needed context: input format, output contents, and domain context.

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

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

The single parameter 'id' is fully explained in the description with format (HP:number) and example (HP:0001250). Schema coverage is 0% but irrelevant since the description compensates completely.

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

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

The description uses a specific verb ('fetch') and resource ('single Human Phenotype Ontology term'), clearly distinguishing it from sibling tools like term_children or term_parents. Examples and ontology context reinforce purpose.

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 natural language query examples ("What does HP:[N] mean") and specifies the domain (HPO for clinical phenotypes). It lacks explicit 'when not to use' guidance, but the single-term lookup is clear given siblings for hierarchies.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. Description adds no additional behavioral traits beyond purpose, which is acceptable but not enhanced.

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 with an example, no wasted words. Front-loaded with key purpose and usage.

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 tool (1 param, robust annotations, has output schema), description is complete. No need for return value details as output schema exists.

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 0% description coverage, but description adds meaning: parameter is an HPO term ID (e.g., HP:0000118). Example clarifies format, though schema lacks any description. Description adequately compensates.

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

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

Clearly states the tool returns direct children of a given HPO term, with an example. Distinguishes from term_descendants and term_parents by specifying 'direct children' and 'narrow from general phenotype'.

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 to narrow from a general phenotype to specifics,' providing clear context. Does not explicitly mention alternatives or when not to use, but sibling tools and the description imply the appropriate use case.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about transitive scope but does not disclose additional behavioral traits 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 two sentences, front-loaded with core function, and contains no unnecessary words. Every part is valuable.

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, annotations, and presence of output schema, the description fully explains what the tool does and when to use it, with 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?

With 0% schema description coverage, the description adds meaning by specifying the parameter is an HPO term ID and providing an example. This compensates for the schema gap.

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 transitive descendants (children, grandchildren, etc.) of an HPO term, with examples and distinction from siblings like term_children.

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

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

The description provides explicit usage guidance ('Use for exhaustive coverage') and an example (e.g., 'every cardiac phenotype'). It implies when not to use but does not explicitly name alternatives like term_children.

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, etc. Description adds critical behavioral detail: returns only *direct* parents, not all ancestors, which is beyond annotation scope.

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, zero waste. Front-loaded with the tool's core question and purpose, immediately followed by usage guidance.

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

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

Output schema exists, so return values need not be described. With only one required parameter, low complexity, and annotations covering safety, the description is complete for correct agent selection.

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 0% (no description for params), so description must compensate. It identifies the parameter as an 'HPO ID' and gives a usage example, but does not specify format or constraints. Minimal but adequate given low complexity.

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+resource: retrieve direct parents of an HPO term. It explicitly contrasts with sibling tools like term_children and term_descendants by indicating 'walk up to a more general phenotype class'.

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?

Description says 'Use to walk up to a more general phenotype class,' providing clear context. It does not explicitly exclude alternatives, but sibling names (term_children, term_descendants) imply opposite directions.

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

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

The description adds behavioral details beyond annotations: ownership enforcement, deactivation vs deletion, and that historical events remain via recent_alerts. Annotations include idempotentHint=true and destructiveHint=false, which are consistent and complemented.

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, no wasted words, front-loaded with the action. 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?

The description covers ownership, side effects, and data retention. However, with no output schema, it does not mention the return format (e.g., success message or object), which would improve completeness for an agent.

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

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

Only one parameter 'id' with schema description 'Subscription id (uuid) returned by subscribe.' Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond referencing the parameter.

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

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

The description clearly states 'Cancel a subscription by id.' It uses a specific verb and resource, and distinguishes from sibling tools like subscribe (create) and list_subscriptions (list).

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 but does not explicitly mention when to use versus alternatives. However, the ownership enforcement ('only cancel your own subscriptions') is a useful constraint. The purpose is unambiguous given sibling tools.

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

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

The description discloses rich behavioral details beyond the annotations: it distinguishes between structured financial verification and grounded fallback, enumerates the verdict types, and explicitly warns that 'could_not_verify' means the check did not happen and must not be treated as evidence. It also explains 'unsupported' semantics and the exact source of citations, going far beyond 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 longer than average but is front-loaded with user intent phrases and a clear purpose. Each sentence earns its place: purpose, routing, overrides, caller warning, and performance benefit. It is well-structured and not wasteful, though it could be slightly trimmed without losing critical information.

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

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

Despite having no output schema, the description compensates fully by listing the exact verdicts that will be returned, the presence of a 'pipeworx://' citation and reasoning, and the error/edge-case behaviors (could_not_verify, unsupported). It also explains the routing for different claim types, making the tool's behavior predictable and complete for the 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?

The input schema already provides 100% coverage for both claim and tolerance_pct, including the default behavior and suggested values for hallucination detection. The description's mention of 'exact percent-delta math' loosely relates to tolerance_pct but adds little meaning beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description defines a specific verb+resource+scope: 'natural-language claim verification against authoritative sources' with concrete user phrasings like 'fact check' and 'verify the claim that…'. It clearly distinguishes itself from siblings such as ask_pipeworx or deep_research by its claim-verification focus and routing logic (SEC EDGAR/XBRL vs grounded pipeline).

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 condition. It also explains that it replaces 4–6 sequential calls, implying it is an aggregated tool, though it does not explicitly name alternatives to avoid.

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