Hpo Api

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

The description adds significant behavioral context beyond annotations: it reveals the default model (Workers AI Llama-3.3-70b, free), explains the optional Anthropic API key (passed through, you pay Anthropic), and details the return structure (per-model {score, confidence, signals, raw_response} + combined view). 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 concise (3-4 sentences) and well-structured: it starts with the core action and output, then details parameters and usage examples. No unnecessary words; every sentence adds value.

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

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

Given the moderate complexity (4 parameters, no output schema), the description is complete. It covers what the tool does, all parameters with realistic examples, usage context, and the return structure. 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%, baseline 3. The description adds value by providing examples for 'entity' (e.g., 'Pipeworx', 'OpenInvoice'), listing supported models for 'models', explaining when '_apiKey' is needed, and giving a disambiguation example for 'context'. This helps agents understand parameter usage 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 uses a specific verb ('Probe') and resource ('LLMs for what they know about a business/brand/product/topic') and clearly states the output (score 0-100 per model). It distinguishes from sibling tools by focusing on AI visibility scoring, which is unique among the listed siblings.

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

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

The description gives clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use it or name alternatives, but the context is sufficient for an AI agent to determine applicability.

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, and idempotentHint. Description adds context about routing to thousands of sources and returning citations, which enhances 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?

Description is thorough and front-loaded with the main directive. While slightly long, every sentence adds value. Could be tighter but still well-structured.

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

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

Given the complexity (meta-tool routing to many sources), the description covers purpose, usage, examples, and output format. No output schema, but description explains structured answer with citations. Complete and sufficient.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds examples and context but does not significantly enhance parameter semantics beyond what the schema already provides.

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

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

Clearly states the tool is for querying structured data (SEC, FDA, etc.) with citations. Distinguishes from web search and sibling tools like ask_pipeworx_grounded and deep_research. Uses specific verb+resource.

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 'PREFER OVER WEB SEARCH' and gives concrete examples of when to use. Provides guidance on when to step up to other tools (grounded, deep_research). Includes examples of queries.

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, etc. Description adds behavioral details: extra LLM call, explicit refusal reasons, extraction only from tool result. 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?

Description is long but well-structured with purpose front-loaded. Each sentence adds value, though could be slightly more concise. Informative 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?

Given the complexity (4,774 tools, 1,242 sources), the description covers purpose, mechanics, return format with refusal reasons, use cases, cost trade-off, and sibling comparison. No output schema but details output structure well.

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

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

Schema coverage is 100% with descriptions for each alias. The tool description does not add additional parameter details beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states it's a 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool results. It distinguishes from ask_pipeworx by mentioning extra cost 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 says when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. Also advises preferring ask_pipeworx for casual 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?

The description thoroughly discloses behavioral traits beyond the annotations (readOnlyHint, idempotentHint, etc.). It covers fan-out behavior, response shapes, resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence and closed markets, wide-spread warnings, and cancellation rule risk. 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 well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and each sentence contributes meaningful information. However, it is quite lengthy; some details (like the extensive response shapes) could be streamlined without losing essential guidance.

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

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

Given the tool's complexity (multiple fan-out categories, edge cases, no output schema), the description is highly complete. It covers behavior for low-confidence, closed markets, wide spreads, cancellation rules, and parameter nuances. No significant gaps remain.

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

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

Schema coverage is 100%, and the description adds significant value by explaining the market parameter types (slug, URL, question text), the depth parameter meaning (quick vs thorough), and the include_raw parameter behavior (summarization vs full payloads with size estimates). This helps agents beyond the 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?

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 inputs (slug, URL, question text) and outputs (evidence packet + comparison). However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, which could lead to confusion about which tool to use for similar tasks.

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 provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives detailed fan-out examples per category. However, it does not include guidelines on when not to use this tool or mention alternatives, such as polymarket_edges for pure edge analysis.

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

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

The description adds rich behavioral context beyond annotations: it details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with natural language examples, then explains purpose, type-specific details, and result behavior. It is slightly lengthy but every sentence adds value. Some minor redundancy could be trimmed, but overall well-structured.

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

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

The description covers key aspects: what data is returned, sorting, sources, and citation URIs. It lacks explicit definition of the 'primary metric' for sorting and does not address edge cases or error handling. Considering no output schema, it sufficiently fills the gap.

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

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

The description significantly enhances parameter understanding: for 'type', it specifies the exact metrics pulled (revenue, net income, cash, debt for companies; adverse-event counts, approval counts, trial counts for drugs) and data sources. For 'values', it gives example formats (tickers/CIKs, drug names). This goes beyond the schema's enum descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with examples like 'compare X and Y'. It distinguishes from siblings by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups' (e.g., entity_profile) and claims to replace 8-15 sequential lookups.

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

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

The description explicitly says to prefer this tool over sequential single-pack lookups when comparing entities, providing strong usage guidance. However, it lacks explicit exclusions or when-not-to-use scenarios, which would make it 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, idempotentHint, and openWorldHint. Description adds significant context: account requirement, paid plan for thorough, parallel decomposition to 4,774 tools, findings packet structure with evidence, confidence, sources, citations, gaps, and expected duration (15-60s). 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 somewhat lengthy but front-loaded with critical account/usage info. Every sentence adds value, though a bit verbose. Could be tightened slightly without losing clarity.

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

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

Given complexity (1242 sources, 4774 tools, no output schema), the description fully explains return format (findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps[]), handles edge cases (empty gaps for uncataloged topics), and sets time expectations. Covers all necessary aspects for accurate 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?

Input schema has 100% coverage describing question and depth enum. Description adds value by explaining depth values in terms of facets (quick=3, standard=5, thorough=8), and that 'thorough' requires a paid plan. This goes beyond the schema's minimal description.

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

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

The description clearly states the tool performs grounded multi-source research over structured data sources, distinguishing it from open-web search and single-lookup siblings. It uses specific verb 'research' and resource '1242 structured data sources'.

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 (broad/multi-part questions over structured data) and when not to use (single lookups, breaking news). Provides alternatives: ask_pipeworx for single lookups and when not signed in. Also mentions paid plan requirement for thorough depth.

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=true, idempotentHint=true, destructiveHint=false. Description adds that results are 'ready to call directly, no second schema lookup needed', which is useful 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?

The description is single paragraph and front-loads purpose, but lists many domains which could be trimmed. Overall clear but slightly verbose.

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?

Tool is well-covered: schema covers all params, description explains return format (tools with schemas and examples). No output schema 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 description coverage is 100%, so baseline is 3. Description does not add meaningful information beyond what the schema already provides for 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 states the tool finds tools by describing data or task, listing many domains. It distinguishes from siblings like 'search' (which retrieves data, not tool metadata).

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance and context.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds that it returns HPO phenotype terms but does not detail pagination, limits, or other behavioral aspects. Slight value added.

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 concise, front-loaded with query patterns, and contains no extraneous information. Every sentence adds value.

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

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

Given a single parameter with format explained, annotations covering safety, and an output schema existing, the description is complete for this tool's purpose.

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 for the 'id' parameter. The description fully compensates by explaining the required format (OMIM:N, ORPHA:N, MONDO:N) and providing examples.

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

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

Description clearly states the tool lists HPO phenotype terms for a disease ID, with explicit examples of use cases and ID formats. It distinguishes from sibling tools like 'entity_profile' by focusing on clinical features.

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?

Says 'Use to enumerate clinical features of rare diseases' and specifies ID format, but does not explicitly contrast with sibling tools or state when not to use.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds details: parallel call, fan-out across sources, specific return fields, and potential soft-fail for patents. No contradiction.

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

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

The description is verbose but each sentence adds value. Starts with examples, then states principle, then details. Could be slightly more concise but well-structured.

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

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

No output schema, so description must detail return values. It lists return fields (cik, company_name, filings, fundamentals, patents, news, LEI) and limitations. 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 3. Description adds value by clarifying type must be 'company', value as ticker or zero-padded CIK, and explicitly that names are unsupported.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists the sources and outputs, and distinguishes from alternative chaining approaches.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and warns 'names not supported (use resolve_entity first).' Provides example queries and notes patent API limitations.

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

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

Annotations declare destructiveHint=true and idempotentHint=true; description adds context about clearing sensitive data, consistent with annotations.

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

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

Two concise sentences, front-loaded with purpose, no waste.

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

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

Complete for a single-parameter tool with clear annotations; no output schema 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% and description does not add meaning beyond schema's 'Memory key to delete'.

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

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

The description clearly states the verb 'delete' and resource 'memory by key', and distinguishes from sibling tools '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?

Explicitly states when to use (stale context, task done, clear sensitive data) and pairs with alternatives 'remember' and 'recall'.

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

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

Annotations already declare readOnlyHint, destructiveHint false, idempotentHint, openWorldHint. Description adds the specific input format (NCBIGene:N) which is useful, but does not disclose additional behavioral traits.

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?

Extremely concise: 2-3 sentences front-loaded with query patterns, purpose, and example. No redundant 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?

Complete for the tool's simplicity: one parameter with format clarified, explicit use case, example. Output schema exists so return values need not be described.

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

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

Schema provides only type 'string' for id with 0% coverage. Description compensates by stating required NCBIGene:N format and giving a concrete example (TP53 = NCBIGene:7157), adding critical semantic context.

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 'fetch diseases associated with a gene ID' with natural language examples and a concrete ID format. While it distinguishes from generic search, it does not explicitly differentiate from sibling 'disease_phenotypes'.

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 for gene-to-disease lookups in rare-disease research, variant prioritization', providing clear context. Lacks exclusion criteria or comparisons to alternatives.

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

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

The description transparently explains the process (fetches page, extracts title/description/key links, emits standard llms.txt format) and the output nature (single text blob). It aligns with annotations (readOnlyHint=true, no destructive action) without contradiction.

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

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

The description is tight: three sentences that front-load the main action, followed by use cases. No redundant or extraneous language.

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

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

The tool is simple (two parameters, no output schema). The description covers purpose, behavior, and output format adequately. It could mention potential limitations (e.g., blocked pages) but overall it is complete enough given the tool's low 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?

With 100% schema coverage, the description adds minimal new meaning beyond the schema: it frames the output as 'production-ready' and 'standard llms.txt markdown format.' However, it does not elaborate on how max_links affects the output beyond the schema's default/max values.

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 ('Generate') and resource ('llms.txt file for any URL'), clearly states the purpose for AI crawlers, and lists distinct use cases (client site, own project, competitor audit) that differentiate it from sibling tools like scan_competitor_ai_presence.

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 provides context for when to use the tool (e.g., getting a client's site indexed) but does not mention when not to use or name specific alternatives among the many siblings. The provided contexts sufficiently imply appropriate 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 already indicate read-only, idempotent, non-destructive. Description adds that it returns specific fields and only active subscriptions by default, and mentions the include_inactive parameter.

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 short sentences: first states purpose and return fields, second gives usage guidance. No wasted words.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete—it lists return fields and explains the parameter.

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's mention of 'include cancelled subscriptions' aligns with the schema's description. No additional meaning added beyond what schema provides.

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

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

The description uses specific verb 'list' and resource 'subscriptions', and distinguishes from sibling tools like 'subscribe' and 'unsubscribe'. It also lists the fields returned.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel'. Does not mention when not to use, but the context is clear.

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

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

Annotations are all false (readOnlyHint, destructiveHint, etc.). Description adds behavioral traits: rate-limited to 5 per identifier per day, free, doesn't count against quota, and team reads digests daily. This goes 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?

Single paragraph of 4 sentences, front-loaded with purpose, then usage, then constraints. No extra words; 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?

For a simple 3-param tool with no output schema, description covers all aspects: parameter explanations, usage constraints, rate limits, and team process. 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% so baseline 3. Description adds meaning by explaining enum values (e.g., 'bug = something broke'), describing context object's purpose, and providing guidelines for message (be specific, 1-2 sentences).

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

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

Description clearly states the tool is for sending feedback to Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs ('tell... something is broken, missing, or needs to exist') and distinguishes from sibling tools which are not feedback-related.

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

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

Explicitly states when to use: when a tool returns wrong data (bug), when a desired tool is missing (feature/data_gap), or praise. Provides alternatives (don't paste end-user prompt) and contextualizes how feedback impacts roadmap and that it's rate-limited and free.

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 (readOnlyHint, etc.), the description adds key behavioral traits: self-aggregating from CF analytics-engine, no PII, and caching delays of 5min-1h. This provides 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 yet comprehensive, with the core purpose front-loaded. Bullet points structure the use cases efficiently without redundancy. 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?

For a simple read-only tool with one parameter and no output schema, the description fully covers what the agent needs to know: what is returned (top tools, packs, volume), parameter behavior, and operational details (caching, data source). No gaps remain.

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

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

Schema coverage is 100% for the single parameter 'window'. The description adds semantic context beyond the enum values by explaining that shorter windows surface current hotness and longer windows show steady-state demand, enriching the agent's understanding.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a recent window. It uses specific verbs ('returns') and resources ('Pipeworx'), and the inclusion of three use cases distinguishes it from sibling tools like 'discover_tools' by focusing on trending behavior.

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

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

The description provides explicit contexts for using the tool: discovering hot data, confirming canonical tools, and aligning use cases. It does not mention when not to use it or alternatives, but the use-case list gives clear 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 indicate read-only, open-world, idempotent, non-destructive. Description adds substantial behavioral context: algorithm details, semantic anchor with Jaccard threshold, partition filter, fill check against live CLOB depth, and the condition that realizable_edge_pp ≤ 0 indicates no trade. No contradiction with annotations.

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

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

The description is detailed but well-structured with section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded main action. Slightly verbose in some technical details, but every sentence serves a 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?

For a complex tool with three modes and algorithmic details, the description is remarkably complete. It covers behavior for each mode, key constraints, response structure, fill check procedure, and references to related tools. No output schema, but response content is described 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?

Schema coverage is 100% with descriptions for both parameters. Description adds significant value: for 'event' it provides example slugs and explains the checks performed; for 'topic' it gives seed examples and explains cross-event pairing logic. This goes well beyond bare schema.

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

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

The description states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes three operation modes (no args, event, topic) and clearly differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance for each mode: 'Call with NO args for a trending_scan', 'pass `event` for the strongest per-event partition_check', 'pass `topic` for a themed cross-event scan'. Recommends event mode for specific markets and mentions alternative tool for custom sizing.

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 provides extensive behavioral details beyond annotations: it explains the five model families, edge calculation (net of slippage), Kelly fractions with caps, 24h move warnings, caching policy (1h at KV level), and diagnostic output for empty segments. Annotations (readOnlyHint, idempotentHint) are fully consistent, and no contradiction is 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 lengthy but well-organized with clear sections (models, response segments, knobs, diagnostics). It front-loads the purpose and uses formatting (like all-caps for segment names) to improve scannability. Every sentence adds value given the tool's complexity, but it could be slightly more concise.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the output structure (by_segment with three types, diagnostics), edge calculation details, caching, and rationale for excluding Fed bets. An agent can use this tool effectively without additional information.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'tradeable-edge knobs' section, which clarifies how min_liquidity, max_spread_pp, and min_partition_leg_killy function as filters to ensure edge realizability. This provides context beyond the parameter descriptions themselves.

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

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

The description clearly states the verb 'scan' and 'return', the resource 'Polymarket markets', and the outcome 'opportunities where Pipeworx data disagrees with market price'. It also directly addresses the agent's goal 'what should I bet on today', distinguishing it from siblings like polymarket_arbitrage by focusing on data disagreement.

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 frames the tool for discovering daily betting opportunities without paging through hundreds of markets. It details three opportunity segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and mentions Fed bets are excluded, providing context on when to use it. However, it does not explicitly state alternatives or when not to use it, which would earn 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 indicate read-only, open-world, idempotent, non-destructive. The description adds significant behavioral context beyond annotations: history bounded by 60-day TTL, snapshots written on cache-miss (gaps mean no scan), decay computed from daily closes not intraday, and details on how trends are computed. No contradiction found.

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 well-organized, starting with the core question and then listing arguments and response structure. Every sentence adds value, though it could be slightly more structured for easier scanning.

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

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

The description is highly complete given the tool's complexity. It explains the entire response format (tracked[], expired[], snapshot_dates[]), data sources, computation method, and limitations (TTL, intraday vs daily). No output schema exists, so the description bears full burden and succeeds.

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 days and window. The description adds extra semantics: defaults (14 days, '1wk'), max clamp (30), and clarification that window refers to snapshot family. This enriches the agent's 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?

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It distinguishes from sibling 'polymarket_edges' by focusing on historical tracking rather than current edges. The verb 'tracks' is implicit in the answer it provides.

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: it answers how long an edge has existed and if it is shrinking, with an example comparing fresh and old edges. It implies when to use (for historical persistence analysis) but does not explicitly state when not to use or mention alternatives beyond 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context (walks the order book ladder, returns verdict) without contradicting annotations. It enriches understanding of the tool's safety and operation.

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 bold headings for modes, front-loaded with purpose, and every sentence adds value. It is appropriately sized for the complexity.

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

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

No output schema exists, so the description thoroughly explains return values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict; for basket: theoretical_sum, realizable_sum, capture_ratio, profit_usd, forced_directional_risk). 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% (baseline 3). The description adds meaning by explaining parameter roles (market vs.event, side values, size_usd interpretation as settlement notional in basket) and default behaviors, exceeding bare 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?

The description clearly defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It is specific and differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial fills cause directional risk). Clear context for 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it details the response fields (compatibility_warning, temporal_alignment, skipped_cross counters) and explains when spreads are meaningless (e.g., temporal misalignment, mismatched bet shapes). This goes well beyond the annotations and provides a complete picture of the tool's behavior.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses bold for key terms. It is somewhat lengthy but every sentence adds value due to the complexity of the topic. It could be slightly more concise without losing meaning, hence a 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 the complexity and lack of output schema, the description covers the response structure (spread, compatibility_warning, temporal_alignment, skipped_cross counters) and explains edge cases. It explains the meaning of safety fields and why spreads may be invalid. It might be slightly over-detailed for some agents, but it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two modes and providing context for the parameters (e.g., 'auto-fetch matching event' for topic, 'overrides topic-mapped side' for explicit). It also gives examples and lists valid topic values. This exceeds the baseline.

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

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

The description clearly identifies the tool's purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison, using specific verbs like 'compute spread' and mentioning the two venues.

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 two distinct modes (topic shortcuts and explicit tickers) and provides guidance on when to use each. It warns that most pre-mapped topics return a compatibility_warning, implying that the tool should be used with caution and that tradeable spreads are rare. However, it does not explicitly list alternative tools for different use cases, which would make it 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, idempotentHint, and destructiveHint. The description adds behavioral details beyond that: it states that omitting the key lists all saved keys, and that values are scoped to an identifier. This enriches the agent's understanding 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?

Three sentences that are dense but not verbose. The first sentence states the core function, the second provides usage guidance, and the third adds context on scoping and pairing. 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?

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It covers retrieval and listing, scoping, and pairing with siblings. No gaps remain for a read-only lookup 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 one parameter. The description adds semantic value by explaining that omitting the parameter lists all keys, which is not explicitly in the schema. This extra context helps the agent decide how to invoke the tool.

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

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

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

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 says when to use this tool: 'to look up context the agent stored earlier'. It gives examples of use cases and mentions scoping. It doesn't explicitly state when not to use, but the pairing with remember and forget implies exclusion.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. Description adds important detail: setting mark_read:true flags events as read, affecting subsequent calls. This goes beyond annotations without contradicting them.

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

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

Description is a single focused paragraph with front-loaded purpose. It efficiently covers key details without extraneous text, earning a high score for conciseness.

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

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

Given no output schema, the description adequately explains return fields (source, citation_uri, payload) and core behavior. It also mentions polling suitability and an alternative HTTP endpoint. Minor omissions (e.g., pagination details) prevent a perfect score.

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

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

Input schema covers 100% of parameters with descriptions. Description adds value by explaining the effect of mark_read and giving an example for type, but does not significantly extend beyond schema for other parameters. 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 clearly states it pulls fired events from the subscription feed, specifying returned fields and filtering options. It does not explicitly differentiate from sibling tools like list_subscriptions, but the purpose is unambiguous.

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

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

Description mentions that polls work fine and that the same feed is available via HTTP, providing some alternative access guidance. However, it lacks explicit when-to-use or when-not-to-use instructions relative to siblings.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds significant behavioral context: it fans out to multiple sources, includes fallback behavior, and specifies the return format (structured changes grouped by source, total_changes count, citation URIs). A higher score would require disclosure of potential rate limits or result limits, but the provided details are strong.

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 for the amount of information conveyed, but it is a single dense paragraph. It could be more scannable with bullet points or clearer separation of sources and parameter details. However, it front-loads example queries effectively.

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 and the absence of an output schema, the description covers the return format, source behavior, and parameter usage well. It lacks information about result pagination, limits, or what happens with no results, but otherwise provides a thorough overview.

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 substantial value: it clarifies that `since` accepts both ISO dates and relative shorthands with examples, recommends '30d' or '1m' for typical monitoring, explains `value` accepts ticker or CIK, and notes that `type` only supports 'company'. This goes well beyond the schema descriptions.

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

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

The description explicitly states the tool provides a change feed for a company in a recent time window, fanning out to multiple sources. It gives concrete example queries and distinguishes from the sibling tool `entity_profile`, making the purpose unambiguous.

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

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

The description clearly indicates when to use this tool (e.g., 'What's new with X', 'latest on Y', 'updates on Acme') and when to use an alternative (`entity_profile` for static profiles). It also explains the fallback mechanism between GDELT and GNews and the soft-fail for USPTO, providing comprehensive usage context.

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

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

Annotations declare idempotentHint=true and destructiveHint=false. The description adds key behavioral details: authenticated vs anonymous persistence (24-hour retention for anonymous), scope by identifier, and the fact that this is a write operation. 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 three sentences with zero wasted words. First sentence states core purpose, second provides usage guidance, third covers behavioral details. It is front-loaded and efficient.

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

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

For a simple key-value store tool, the description covers purpose, usage context, persistence behavior, and pairing with siblings. No output schema exists, but the return value is implied (success/failure) and not necessary for agent use. 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%, but the description adds meaningful context: it renames and exemplifies keys (e.g., 'subject_property', 'target_ticker') and describes value as 'any text — findings, addresses, preferences, notes', going beyond the generic schema descriptions.

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

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

The description starts with a clear verb-resource pair ('Save data') and immediately specifies the scope ('across this conversation or across sessions'). It provides concrete examples of what to store (ticker, address, preference) and explicitly names sibling tools 'recall' and 'forget', differentiating this tool as the storage side.

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: 'when you discover something worth carrying forward'. It lists example data types and directs the agent to pair with recall/forget for retrieval/deletion. This gives clear context for tool selection among siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true; description adds that it cascades through multiple lookup endpoints internally and returns specific identifiers with citation URIs. No contradiction, but could mention lack of side effects beyond annotation cues.

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 front-loaded with purpose and uses clear examples. It is slightly verbose but all sentences add value. The structure is logical, moving from purpose to usage to details.

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

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

No output schema, but description fully covers return values for each type, including citation URIs. It also mentions internal cascading and that it replaces multiple manual lookups, providing a complete picture 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%, but description adds significant meaning: it explains the type enum with what each returns, and for value provides examples and auto-disambiguation behavior. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states the tool resolves a name to a canonical identifier, with specific examples (ticker, CIK, RxCUI) and a clear verb 'resolve'. It distinguishes itself from sibling tools by emphasizing its role when an ID is needed from a name.

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 FIRST whenever you have a name but need an ID.' It provides supported types and return formats. However, it does not explicitly state when not to use it or name alternative siblings, leaving some ambiguity compared to other search 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details beyond these: it explains that the tool probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. 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 concise: two sentences plus a parenthetical example. It front-loads the main action, and every sentence adds meaningful information without redundancy. 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 (4 parameters, no output schema), the description covers the core functionality, expected input/output, and use case. It does not detail error handling or array size constraints, but schema coverage fills those gaps. Overall sufficient for an agent to use the tool effectively.

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%, but the description adds valuable context: it mentions that the first entity in the array is treated as the 'subject' for narrative, and that context is an optional shared context to disambiguate names. This goes beyond the schema descriptions, aiding correct parameter usage.

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 specific verbs (compare, probe, rank, surface) and clearly identifies the resource it acts on (AI visibility across multiple entities). It distinguishes itself from the sibling tool ai_visibility_check by focusing on batch comparison versus single entity probing.

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 a clear use case (competitive AI-marketing audits) and a concrete example question. While it does not explicitly state when not to use it or name alternatives, the context implies it is for multi-entity comparison, and the sibling list includes ai_visibility_check for single entity checks.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and failed sources are listed. 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 but well-organized: purpose first, then details, return fields, and caveats. Every sentence provides value, though it is slightly long. Could be tightened without losing 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?

Given the complexity of the tool (composite call, multiple services, partial failures), the description is highly complete. It lists all return fields (summary, advisories, alternatives), mentions graceful degradation, and covers ecosystem limitations. No output schema, but the description sufficiently documents return values.

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 both 'package' and 'version'. The description adds helpful context: version defaults to latest, scoped packages are accepted. This goes beyond the schema but only marginally.

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's a composite check for evaluating npm packages, covering license, advisories, bundle size, etc. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes itself from sibling tools like 'validate_claim' by being a single-call multi-source aggregator.

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

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

Explicitly states when to use: when an agent asks about package safety, popularity, or size. Also notes limitations: NPM only in v1, and for other ecosystems to use deps.dev directly. Provides clear context for when to avoid 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which describe safety and behavior. The description adds that it returns ranked terms but does not add significant behavioral context beyond the annotations.

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

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

The description is effective but contains several example queries that could be condensed. It is front-loaded with examples and purpose, but slightly verbose.

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 that an output schema exists, the description does not need to detail return values. It covers purpose, usage context, and the main parameter well. It lacks explanation of pagination but remains fairly 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 description coverage is 0%, so the description must explain parameters. The description effectively explains the 'query' parameter via examples, but 'page' and 'limit' are not mentioned, leaving those parameters unexplained.

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 searches the Human Phenotype Ontology (HPO) to return HPO terms with IDs, mapping clinical descriptions to ontology terms. It distinguishes from sibling tools by being HPO-specific.

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 says 'Use to map clinical descriptions to standard ontology terms' and provides example query patterns, guiding appropriate use. It doesn't explicitly state when not to use, but the context is clear among diverse siblings.

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

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

Adds rich context beyond annotations: character offsets, similarity scores, BGE-base-en embeddings, cosine over 500-char windows, 200K char cap with truncation flag. No contradiction with readOnlyHint=true, openWorldHint=true, etc.

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

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

Four efficient sentences, front-loaded with core purpose. Every sentence provides unique information without 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?

Covers inputs, outputs (top-N passages with offsets and scores), model details (BGE-base-en, cosine, windows), and limitations (200K cap, truncation). No output schema, but description compensates fully.

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 3. Description adds value: example queries for 'query', clarifies 'text' is document text with max chars, and describes return format (passages with offsets) which relates to parameter usage.

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, with specific verb (search inside/within) and resource (a fetched record). It distinguishes from siblings by mentioning alternatives like ask_pipeworx_grounded and contrasting with full document retrieval.

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

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

Explicitly states when to use: when record is too big for prompt. Mentions pairing with ask_pipeworx_grounded. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true). Description adds behavioral context: returns subscription id, requires OAuth, SMS cap, webhook HMAC signing, and auto-disable after failures. 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?

Slightly verbose but well-structured: purpose first, then requirements, then types with examples, then delivery channels. Every sentence adds value; minimal 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?

Highly complete: covers prerequisites, all subscription types with parameters, delivery options with limitations, and mentions return value (subscription id). No output schema, but description fills the gap.

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

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

Schema already covers 100% of parameters, but description adds extensive meaning: type-specific parameter examples, constraints like 'phone must be verified' and '10/day cap', webhook secret returned once. Greatly aids understanding.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. Distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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: requires Pipeworx OAuth account, lists supported types with examples, and explains delivery channels. Does not explicitly state when not to use or contrast with alternatives, but the detail is sufficient.

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 safe, read-only, idempotent behavior. Description adds that it returns example questions with exact tool+argument shape, which is crucial for agent decision-making. 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?

Front-loaded with purpose and alternative phrasings. Every sentence adds value, including usage context, return structure, and parameter guidance. 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 simple interface (one optional parameter, no output schema), the description fully covers how to invoke the tool and what to expect as 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 already covers parameter 'topic' with description. The description lists possible values (finance, pharma, etc.) and explains the effect of omitting vs providing topic, adding significant meaning.

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

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

The description clearly states it returns categorized example questions and is the onboarding entry point. It distinguishes itself from siblings like ask_pipeworx or search by being the first step for a new agent.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', and explains when to provide a topic vs omit. Mentions related tools (ask_pipeworx, entity_profile) as 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 provide readOnlyHint and destructiveHint. Description adds return fields (label, definition, synonyms, cross-references) which is useful but not essential for safety. 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 4 sentences, front-loaded with example queries, concise, and contains no redundant 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?

Given simple single-parameter tool with output schema and annotations, description covers purpose, usage, return format, and provides examples. Complete for the task.

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 coverage, description adds significant meaning: explains the parameter is an HPO ID, gives examples like HP:0001250, and links it to Seizure. This compensates for schema's lack of description.

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

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

Description starts with natural language queries ('What does HP:[N] mean'), clearly states the verb 'fetch' and resource 'single HPO term', and distinguishes from sibling tools like term_children by specifying it's for a single term.

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 implies usage context: fetch one term by ID. Siblings list includes term_children, term_descendants, term_parents, making it clear when to use this tool vs alternatives, though explicit 'when not to use' is absent.

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 readOnly, idempotent, and non-destructive hints. The description adds that it returns only direct children (not all descendants), clarifying the scope. No contradiction with annotations. Could be improved by noting that results are based on ontology graph structure.

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

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

The description is extremely concise: two sentences that front-load the key information. Every word adds value; 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?

Given the tool's simplicity, one required parameter, rich annotations, and an output schema (not shown), the description is fairly complete. It explains the return type (direct children) and use case. Could mention that the output is a list of terms.

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 description carries the burden. It provides context that the parameter is an HPO term ID (e.g., 'HP:0000118'), but does not explicitly describe the parameter format, constraints, or that it is required. The example in schema helps, but description could be more precise.

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

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

The description clearly states the verb 'get', resource 'direct children of an HPO term', and differentiates from siblings like 'term_descendants' and 'term_parents' by specifying 'direct children'. It provides an example of use (narrowing from general to specific).

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 says 'Use to narrow from a general phenotype to specifics', which gives clear context. However, it does not explicitly mention when not to use or compare to alternatives like 'term_descendants' or 'search', which would raise the score to 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 safe, read-only, idempotent behavior. Description adds that it returns transitive descendants, which is the key behavioral trait. No contradiction; annotation_contradiction is false.

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

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

Two sentences, no fluff. Front-loaded with quotes and examples. Every sentence adds value—purpose, scope, and example 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 one parameter, full annotations, and presence of output schema (mentioned), the description is complete. It tells what the tool does, when to use it, and provides an example. 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 has 0% description coverage for parameter 'id'. Description adds meaning by specifying it's an HPO term ID and showing example 'HP:0000118'. Adds significant value beyond the raw schema.

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

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

Description uses specific verb 'get' and resource 'transitive descendants of an HPO term', with examples like 'every cardiac phenotype'. Clearly distinguishes from siblings like term_children (immediate children) and term_parents, as seen in 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?

Explicitly states 'Use for exhaustive coverage' and provides an example. Implicitly tells when to use vs alternatives (term_children for immediate). Could be more explicit about when not to use, but context from sibling names helps.

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, indicating a safe read operation. The description adds that it returns 'direct parents' (not all ancestors), which is useful but not extensive. No contradictions.

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

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

The description is two sentences: a natural language query followed by a technical description and usage tip. It is concise, front-loaded, and 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?

Given the tool's simplicity (one parameter, clear purpose), the description covers the essential behavior, usage, and parameter semantics. It could mention error handling for invalid IDs, but that's minor. Output schema exists to define return values.

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 only one parameter 'id' with 0% description coverage. The description clarifies that the id is an HPO identifier (e.g., 'HP:0001250'), adding meaning beyond the schema. For a single parameter, this is sufficient.

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 direct parents of an HPO term in the ontology graph, using a natural language query and a technical clarification. It distinguishes from sibling tools like term_children and term_descendants by specifying 'direct parents' and 'walk up'.

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 to walk up to a more general phenotype class', which implies the use case. It doesn't explicitly mention when not to use or name alternatives, but the context (siblings include term_children and term_descendants) provides enough differentiation.

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 (idempotentHint=true, destructiveHint=false, readOnlyHint=false), the description adds critical behavioral details: the row is deactivated not deleted, historical events remain accessible via recent_alerts, and ownership is enforced. This enriches agent understanding.

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 concise sentences that front-load the action and effect. Every word is meaningful, with no redundancy. Well-structured for quick parsing.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, effect, ownership, and references sibling tools (recent_alerts). It is substantially complete, though could optionally mention idempotency explicitly.

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 the parameter 'id' already described as 'Subscription id (uuid) returned by subscribe.' The description only mentions 'by id', adding no new semantic value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and distinguishes itself from sibling tools like subscribe, list_subscriptions, and recent_alerts by specifying the effect (deactivation, not deletion).

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 specifies ownership enforcement ('you can only cancel your own subscriptions'), which guides usage, but does not explicitly state when not to use this tool or mention alternatives. Context is clear for intended use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond annotations by detailing the return format: verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported), extracted structured form, actual value with citation, and percent delta. There is no contradiction with annotations.

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

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

The description is concise and front-loads example queries and usage context. It packs a lot of information (supported domain, return format, efficiency gains) without unnecessary verbosity. Minor improvement could be structuring the return values as a list, but overall it is 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?

Given no output schema, the description fully explains the return values (verdict types, structured form, actual value with citation, delta). It also covers the domain limitation (company-financial claims for public US companies), the data source (SEC EDGAR + XBRL), and the efficiency benefit (replaces 4-6 sequential calls). No gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond schema by stating the supported domain (company-financial claims via SEC EDGAR + XBRL) and providing examples of valid claims (e.g., 'Apple's FY2024 revenue was $400 billion'). This helps the agent formulate appropriate input.

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 specific verbs like 'fact check', 'verify', 'confirm or refute' and clearly identifies the resource: claim verification against authoritative sources for company-financial claims via SEC EDGAR + XBRL. It distinguishes from sibling tools like 'entity_profile' or 'compare_entities' which do not perform claim validation.

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 whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain (company-financial claims for public US companies). While it does not explicitly state when not to use, the domain restriction implies exclusions, and it notes the tool replaces multiple sequential calls, providing efficiency context.

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