Hpo Api

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds beyond this by explaining the default model (Workers AI Llama-3.3-70b, free), the need for a BYO API key for Anthropic, and the return structure (per-model scores, confidence, signals, raw_response, combined view). 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, front-loaded with the main action and outcome, then providing key details (default model, API key handling, return structure). Every sentence is essential and there is no redundancy.

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

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

Given 4 parameters, high schema coverage, no output schema, the description covers the main use cases, parameter roles, and return structure. It is complete enough for an agent to understand when to use the tool and what to expect.

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 100% parameter description coverage, so baseline is 3. The description adds practical meaning: it explains that models defaults to just workers-ai, that _apiKey is only needed for anthropic, and that context disambiguates the entity. This adds value beyond the schema.

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

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

The description clearly identifies the verb 'probe', the resource 'LLMs', and the outcome 'score visibility (0-100) per model'. It distinguishes from siblings like 'scan_competitor_ai_presence' by being more general, and specifies the default model and optional API key for Anthropic.

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

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

The description states it is 'useful for AI-marketing audits, pre-launch brand checks, competitive monitoring', providing clear context for when to use. It does not explicitly exclude cases or compare to alternatives, but the context is sufficient for an agent.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral context: internal routing across 3,547 tools, argument filling, and stable citation URIs. This goes beyond annotations to explain how the tool works internally.

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 with a strong front-loaded opening but includes many details and examples that could be condensed. It is well-structured but not optimally concise; some sentences are redundant.

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 (many sources) and no output schema, the description adequately covers the pipeline (routing, citations). However, it lacks details on error handling, rate limits, and contrasts with siblings like 'search' only implicitly via 'prefer over web search'.

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

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

Schema coverage is 100% with all parameters described (question and aliases). The description adds example questions but does not provide additional formatting rules or constraints beyond the schema, keeping it at baseline 3.

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

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

The description explicitly states 'PREFER OVER WEB SEARCH' and enumerates specific data domains (SEC filings, FDA data, etc.), clearly defining the tool as a structured data query engine. It differentiates from sibling tools like 'search' by positioning itself as authoritative with citations.

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 when-to-use instructions: prefer this over web search for structured factual data, with example query phrases. However, it does not explicitly exclude cases where sibling tools like 'search' might be more appropriate, though the preference is strongly implied.

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

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

The description adds significant behavioral context beyond annotations: it is hallucination-resistant, extracts answer only from the tool result, returns explicit refusal reasons, and costs an extra call. No contradiction with annotations (readOnlyHint, openWorldHint, 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?

The description is front-loaded with the key purpose, then progressively adds details on behavior, return format, refusal reasons, and usage guidance. Every sentence adds value. Could be slightly shorter 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?

Given the complexity of routing among 3,641 tools and refusal logic, the description covers the tool's purpose, behavior, return format (fields and refusal reasons), failure modes, and usage trade-offs. No output schema, but the return structure is fully 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 description coverage is 100%, so baseline is 3. The parameter 'question' is well-documented with aliases, but the description does not add further semantics beyond 'fills arguments' and 'natural language'. Acceptable but not enhanced.

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 is a 'hallucination-resistant answer mode for high-stakes reads.' It specifies the verb 'ask', resource 'Pipeworx', and distinguishes itself from the sibling tool 'ask_pipeworx' by emphasizing groundedness and refusal 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?

Explicitly states when to use (high-stakes, answer will be quoted/cited/acted on, must not invent facts) and gives examples like financial verdicts, legal claims. Also says to prefer 'ask_pipeworx' for casual lookups, and mentions the cost trade-off of one extra LLM call.

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 behavior. The description adds extensive behavioral details: fan-out mechanism, resolver contract, parent event extraction, news fields with fallback, safety features for low-confidence matches and closed markets, and liquidity warnings. 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 lengthy but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Front-loads the core purpose. Every sentence adds value, though could be more concise. Slightly verbose but 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 the tool's complexity (3 parameters, no output schema, rich behavior), the description covers return shapes, evidence structure, safety mechanisms, and edge cases. It provides sufficient context for an agent to select and use the tool appropriately.

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

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

Schema coverage is 100%. Description adds meaning beyond schema: explains what market_input formats are accepted (slug, URL, question text), gives examples, elaborates on depth and includ_raw parameters with concrete effects. This provides richer context for 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 defines the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research), resource (Polymarket bet), and scope. This distinguishes it from siblings like polymarket_edges or polymorphic_arbitrage.

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

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

The description explicitly states when to use: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It provides clear use cases and implies alternatives by not recommending it for arbitrage or other purposes.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, but the description adds context about the parallel call behavior, data sources (SEC EDGAR/XBRL, FAERS), sorting by primary metric, and return format including citation URIs. A minor gap is lack of mention of error handling or data freshness, but enough is provided beyond annotations.

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

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

The description is a single paragraph but front-loads with user query examples and key instruction. Every sentence adds value, but it could be more structured (e.g., bullet points) for easier scanning. It is not overly verbose and covers all essential aspects.

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 (two entity types, multiple data sources, sorting, citations, no output schema), the description is remarkably complete. It explains what data is returned, how results are sorted, and includes citation URIs. It covers the key usage patterns and provides enough detail for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'values', so baseline is 3. The description adds substantial context: explains what data each type pulls, gives examples of tickers and drug names, and clarifies the 2-5 range and sorting behavior. However, it does not specify case sensitivity or exact format for values, leaving some ambiguity.

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 does side-by-side comparison of 2-5 companies or drugs, with clear examples like 'Compare X and Y'. It distinguishes from sequential single-pack lookups and details what each entity type returns (financial metrics for companies, clinical data for drugs). This provides a specific verb+resource+scope.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance. It also explains the contexts for each type. This leaves no ambiguity about when this tool is appropriate versus using alternative tools like entity_profile.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is safe to call repeatedly. The description adds that it returns top-N relevant tools with full schemas and curated examples, and that each result is ready to call directly. This adds value beyond annotations.

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

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

The description is front-loaded with the core purpose and usage. It is not overly verbose but includes necessary details about return value and examples. Slightly long but justified by the complexity of the tool (discovery across many domains).

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

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

The description covers the purpose, usage, input parameters, and output characteristics (top-N tools with names, descriptions, schemas). Since there is no output schema, the description adequately describes what the agent will receive.

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

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

Schema coverage is 100%. The description explains the main 'query' parameter with examples and lists aliases (q, task, search, description). This clarifies that multiple parameter names are accepted, which is not obvious from the schema alone.

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

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

The description starts with 'Find tools by describing the data or task' which is a clear verb+resource statement. It distinguishes from siblings by being the primary tool for browsing/discovering tools, listing numerous example tasks and 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?

Explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also provides many examples of when to use (e.g., 'SEC filings', 'FDA drugs', 'stocks').

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool returns 'HPO phenotype terms,' providing useful 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 concise, front-loading the purpose with alternative phrasings. It includes ID formats and an example in two sentences, though slightly informal.

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 single-parameter tool with output schema and clear annotations, the description covers purpose, input format, and example. It is mostly complete, though it does not address invalid IDs or output details.

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

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

The input schema has no description for the 'id' parameter (0% coverage). The description compensates by specifying the allowed formats (OMIM:N, ORPHA:N, MONDO:N) and providing an example, 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 the tool lists HPO phenotype terms for a disease ID, using specific examples like OMIM:154700. It differentiates from sibling tools by focusing on symptoms/clinical features of a disease.

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 when-to-use guidance: 'Use to enumerate clinical features of rare diseases.' It gives example queries but does not explicitly mention when not to use or list alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent. Description adds context about fan-out across multiple sources, patent API potential failure, and news fallback chain. Does not contradict annotations, but could detail rate limits or data freshness.

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?

Fairly concise given complexity; uses examples, bullet-like listing of outputs, and clear constraints. Could be slightly shorter but earns its length.

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 sufficiently covers returned fields. Missing some specifics (pagination, date ranges) but adequate for an agent to understand the tool's capabilities.

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

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

Schema coverage is 100%, baseline 3. Description adds examples (AAPL, 0000320193), explains type enum only supports company, and explicitly states names are not supported—adding value beyond schema.

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

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

Description starts with multiple example queries, states it returns a full cross-source profile, and lists specific output fields (CIK, filings, fundamentals, patents, news, LEI). Clearly distinguishes from chaining single-pack lookups.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack lookups when user asks for holistic view' and clarifies that names are not supported—use resolve_entity first. Provides when-to-use and when-not-to.

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

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

Annotations already indicate destructiveHint=true, readOnlyHint=false. The description says 'Delete' which is consistent but does not add extra behavioral context beyond what annotations provide, such as irreversibility or authorization needs.

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, efficiently front-loading the action and usage guidance. Every sentence is valuable and there is 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?

For a simple delete operation with one parameter and no output schema, the description covers the purpose, when to use, and pairs with siblings. It is complete given the tool's complexity and the existing annotations.

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

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

Schema coverage is 100%, and the description for the single parameter 'key' ('Memory key to delete') largely repeats the schema description. No additional meaning beyond the schema is provided.

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

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

The description clearly states 'Delete a previously stored memory by key.' This is a specific verb (Delete) and resource (memory by key), and it distinguishes itself from sibling tools 'remember' and 'recall' by mentioning 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 states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's mention of 'fetch' is consistent. The description adds no additional behavioral details about execution, results, or side effects beyond the annotations, but it does not contradict 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?

The description consists of two concise sentences: the first presents query patterns, the second provides usage context and an example. Every sentence adds value with no redundancy or filler.

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

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

For a tool with one required parameter, an output schema (present), and clear annotations, the description fully covers the input format, purpose, and example. No additional completeness is 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?

The schema provides only a 'string' type for 'id' parameter with 0% coverage. The description compensates fully by specifying the required format 'NCBIGene:N format' and giving an explicit example 'NCBIGene:7157 (TP53)', which adds essential meaning beyond the 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 clearly states the action ('fetch diseases') and resource ('gene ID in NCBIGene:N format'), provides example query patterns and a concrete example (TP53). It distinguishes from siblings by specifying gene-to-disease lookups and mentioning rare-disease research and variant prioritization.

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

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

The description explicitly states when to use ('Use for gene-to-disease lookups in rare-disease research, variant prioritization') and gives an example ID. It does not explicitly exclude other tools or provide alternatives, but the context is clear enough for appropriate selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains the internal steps and output format beyond what annotations provide. 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 three sentences, each serving a purpose: main action, process description, and usage examples. It is front-loaded with the key verb-object pair. No unnecessary words or repetition.

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

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

No output schema exists, so the description correctly explains the return format ('single text blob ready to drop at site-root/llms.txt'). The description covers what the tool does, how it works, and why it is useful. Given the low complexity and good annotations, it is fully 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?

Input schema has 100% coverage with descriptions for both parameters (url, max_links). The description does not add any parameter-specific details beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description starts with a clear verb+resource: 'Generate a production-ready llms.txt file for any URL'. It specifies the exact output (llms.txt) and target consumers. No sibling tool competes, so differentiation is implicit but clear.

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 lists three concrete use cases (indexing a client's site, drafting for own project, auditing competitors). It implies when to use but does not explicitly state when not to use or name alternatives. Still, the guidance is clear and contextually appropriate given the unrelated 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 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 indicate non-readonly, non-idempotent, non-destructive. Description adds rate limiting and free cost info, consistent with annotations. Does not contradict.

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, well-structured paragraph that front-loads purpose and includes all necessary details without verbosity.

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 all aspects: when to use, how to write, rate limits, free nature, and team feedback loop. No output schema needed; description is complete for a simple feedback 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 100% and description adds meaning: explains each feedback type's purpose, gives guidance on message content (be specific, length), and clarifies context is optional.

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 providing feedback to Pipeworx team, listing specific categories (bug, feature, data_gap, praise) and distinguishing itself from sibling tools by being a feedback mechanism.

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 tells when to use (wrong data, missing tool, praise) and what not to do (don't paste end-user prompt). Includes context on team usage, rate limits, and free nature.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds that it's self-aggregating, derived from CF analytics-engine, no PII, and caching times (5min-1h). No contradiction.

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

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

Description is about 5 sentences, front-loaded with the core output, then use cases, then technical details, all 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?

Despite no output schema, the description explains what is returned (top tools, packs, call volume) and addresses caching, aggregation method, and privacy. Complete for a simple read 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% for the single parameter (window). The description adds context beyond the enum values (shorter vs longer windows for different insights), enhancing 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 top tools, packs, and call volume over recent windows. It provides specific use cases, distinguishing it from siblings which have different functions (e.g., search, entity profile).

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

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

The description gives three explicit use cases (discovering hot data, confirming canonical choice, alignment check) and mentions caching duration. It does not explicitly say when not to use, but context is strong.

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

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

Annotations already declare readOnly, openWorld, idempotent. The description adds significant behavioral details: prerequisite arguments, internal logic (Jaccard similarity threshold, partition filter), failure conditions, and response structure. No contradiction with annotations.

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

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

The description is dense and well-structured, front-loading the requirement. While comprehensive, it is somewhat lengthy; however, every sentence contributes to understanding. Efficient 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?

Despite no output schema, the description thoroughly explains the response (opportunities array with fields) and covers error modes (no args, low similarity, placeholder fraction). All essential aspects are covered for a complex arbitrage 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%, so baseline is 3. The description adds value by explaining usage modes, providing examples (slugs, seed questions), and detailing internal behavior (Jaccard, partition filter) beyond the schema's type/description.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from siblings by specifying two modes (event/topic) and provides concrete examples, 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 explicitly explains when to use each mode (event for specific markets, topic for cross-event scanning), gives examples, and warns that calling with no args fails. It doesn't directly compare to siblings like polymarket_edges, but context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, non-destructive. Description adds extensive behavioral details: caching 1h at KV level keyed on knobs, response structure with by_segment and diagnostics, knobs like min_liquidity, max_spread_pp filter tradeability. 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?

Long but dense with information. Front-loaded with purpose then detailed segments, response fields, caching. Every sentence adds value, though could be slightly more structured with bullet points. Term 'EVERY OPPORTUNITY' is clear but adds 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 9 parameters and no output schema, description fully details response structure: by_segment with three groups, fed_candidates/fed_note, _diagnostics with funnel counters. Explains parameter interactions (min_kelly vs min_partition_leg_kelly) and caching behavior. Complete for agent understanding.

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

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

Schema covers 100% of parameters with descriptions. Tool description adds rich context: explains min_kelly vs min_partition_leg_kelly distinction for partition arbs, edge_pp_net net of slippage, kelly_fraction capped at 0.25, and tradeable-edge knobs. Exceeds baseline for high coverage.

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

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

Clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, built for daily betting decisions. Distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx-specific signals and three response segments.

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

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

Explicitly states purpose ('what should I bet on today') and that it eliminates paging. Mentions Fed bets surface but are excluded with explanation. Does not explicitly list when not to use or alternatives, but context from siblings implies 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?

Adds extensive behavioral context beyond annotations: explains two modes, response structure, safety fields (compatibility_warning, temporal_alignment), and counters (skipped_cross_type/subtype). Discloses that pre-mapped topics often return warnings, providing realistic expectations. No contradiction with annotations.

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

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

The description is long but well-structured: purpose first, then modes, response, safety fields. Every sentence adds value, though it could be slightly more concise. The use of colons and parentheses aids readability.

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 (two modes, safety fields, counters) and the lack of an output schema, the description is remarkably complete. It explains response fields, when spreads are meaningful, and common caveats. 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%, so baseline is 3. The description adds meaning by listing the 10 topic shortcuts, explaining that kalshi_event_ticker and polymarket_event_slug override topic mapping, and providing examples. This enriches the bare schema descriptions.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It describes two modes (topic shortcuts and explicit pairings) and distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explains when to use (to find spreads between venues) and when not (when bet shapes are non-equivalent or temporally misaligned, as indicated by compatibility_warning and temporal_alignment). It warns that most pre-mapped topics are not tradeable, but it does not explicitly mention alternative 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 readOnly, idempotent, non-destructive. Description adds scoping detail (by identifier) and ties to remember/forget lifecycle. No contradictions. Could mention more about return format but not critical.

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

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

Four concise sentences front-load core function, then examples, scope, and related tools. No wasted words, 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?

With one optional param and no output schema, description covers key aspects: usage, scoping, lifecycle. Minor gap: no description of return value format, but it's implicit for a key-value retrieval.

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

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

Schema covers the key parameter with description of its dual role (retrieve or list). Description repeats this but adds no new parameter-level detail. Baseline 3 acceptable as schema is comprehensive.

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

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

Clearly states it retrieves a saved value or lists keys, using specific verb 'Retrieve' and resource 'value previously saved via remember'. Distinguishes from sibling tools remember and forget by explicitly pairing them. Provides concrete examples (user's target ticker, address, research notes).

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

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

Explicit use case: looking up context stored earlier to avoid re-derivation. Mentions scoping and pairing with remember/forget. Lacks explicit when-not-to-use or alternatives like searching, but context is clear enough for agents.

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 indicate safe read-only operation; description adds valuable context: fans out to multiple sources, fallback logic, patent soft-fail, and supported `since` formats.

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?

Packed with info but slightly long; front-loaded with examples. Every sentence earns its place, though could be trimmed 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?

No output schema, but description clearly states return format (grouped by source, counts, URIs). Covers all parameters and fallback behaviors. Complete for a 3-param tool.

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

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

Schema has 100% coverage; description adds richer meaning: example values for `since`, explanation of `value` accepting ticker or CIK, and typical monitoring recommendation.

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 change feed for a company in the last N days, covering SEC, news, and patents. It distinguishes from sibling 'entity_profile' which is for static profiles.

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

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

Explicit use cases like 'What's new with X' and when-not-to-use (static profile suggests entity_profile). Includes fallback behavior between GDELT and GNews.

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 idempotent and non-destructive behavior. The description adds valuable context: key-value scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous sessions. 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?

Three well-structured sentences: purpose, usage, and behavioral details. Front-loaded with the main verb 'Save'. Every sentence adds value with no redundancy.

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

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

For a simple key-value store with two parameters and no output schema, the description covers purpose, usage, behavioral constraints, and pairing with siblings. It is fully sufficient for an agent to understand when and how to use the tool.

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

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

Schema covers 100% of parameters with descriptions. The description enhances by providing example key formats (e.g., 'subject_property') and specifying acceptable values ('findings, addresses, preferences, notes'), adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific examples (resolved ticker, target address, user preference, research subject). It distinguishes itself from siblings like 'recall' and 'forget' by explicitly mentioning 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 says 'Use when you discover something worth carrying forward' and pairs with recall/forget, providing good usage context. However, it does not explicitly state when not to use it or mention alternatives beyond the paired 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 indicate read-only, idempotent, non-destructive. The description adds that each call cascades through several lookup endpoints internally, which goes beyond annotations. No contradictions.

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

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

The description is front-loaded with example queries and well-structured with bullet points for supported types. It is somewhat lengthy but every sentence adds value, so only minor deduction.

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, but the description thoroughly explains return values for each type (ticker, CIK, name, URI for company; RxCUI, ingredient, brand, URI for drug) and mentions auto-disambiguation. Completely covers necessary 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%, but the description adds meaning beyond enum and type: it explains expected input formats for company (ticker, CIK, name) and drug (brand/generic name), which is critical for correct 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 the tool resolves a user-spoken name to a canonical identifier, with specific examples like ticker, CIK, and RxCUI. It distinguishes itself from siblings by focusing on name-to-ID resolution and not on other operations.

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: 'Use FIRST whenever you have a name but need an ID.' Provides context that it replaces 2-3 manual lookups, giving clear when-to-use direction.

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

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

Annotations already declare readOnlyHint and idempotentHint, indicating safe, idempotent behavior. The description adds behavioral details: probing each entity with ai_visibility_check, ranking by score, surfacing extremes, and returning score, confidence, and signal density per entity. This provides meaningful 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 three sentences, front-loaded with purpose, then method, then example usage and return. Every sentence adds value 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?

Given 4 parameters, no output schema, and composite nature, the description covers how the tool works, what it returns, and why to use it. It explains the probing process, ranking, and output fields (score, confidence, signal density). Complete for the tool's complexity and structured data available.

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%, providing detailed parameter descriptions (e.g., entities array with first as subject). The tool description does not add new meaning beyond the schema, only restating 'your brand + N competitors'. Baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using 'compare' as the verb and specifying the resource. It distinguishes from sibling ai_visibility_check by targeting multiple entities instead of single.

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 use case (competitive AI-marketing audits) with an example question, implying when to use the tool. It does not explicitly state when not to use or directly name alternatives, but the context of composing ai_visibility_check hints at the single-entity alternative.

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

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

Annotations already declare readOnlyHint, 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing the tool as safe and non-mutating. The description adds value by specifying that results are ranked and include HP IDs, and clarifies the domain (HPO). It does not contradict annotations. The description could mention pagination behavior (page, limit) but is sufficient given 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 three sentences, front-loaded with example query phrases, then a clear statement of functionality, and ends with a usage note. Every sentence adds value with no redundancy. It is concise while covering purpose, domain, and output.

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 presence of an output schema (not shown but present), the description is not required to detail return values. It adequately covers the tool's domain (HPO), use case (mapping clinical descriptions), and behavior (text search, ranked results). However, missing parameter documentation and lack of explanation for pagination reduce completeness slightly.

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

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

The input schema has three parameters (query, page, limit) with zero description coverage. The description does not explain what query format is expected (e.g., free text vs. specific patterns) or how page/limit affect results. Examples are provided in the schema but not in the description, leaving the agent to infer parameter semantics. This is a significant gap for a search 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 performs text search of the Human Phenotype Ontology (HPO) and returns ranked terms with HP IDs. It provides concrete examples of queries (e.g., 'seizures', 'short stature'), making the purpose immediately recognizable. Differentiates from sibling tools like 'term' (exact lookup) and 'term_children' (hierarchy navigation) by emphasizing generalized search.

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

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

The description includes explicit usage context: 'Use to map clinical descriptions to standard ontology terms for rare-disease workups, genomics, or clinical phenotype databases.' It does not explicitly state when not to use or list alternatives, but the context is clear enough for an agent to infer appropriate scenarios. Sibling tools could be mentioned for exact lookups, but omission is not critical.

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 it's not read-only, not destructive, and idempotent. The description adds critical context: OAuth requirement, type-specific parameter behaviors, delivery channel limitations (10 SMS/day cap), and phone verification. It does not contradict annotations.

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

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

The description is a single dense paragraph that efficiently communicates purpose, requirements, type options, and delivery details. Every sentence adds value, and information is front-loaded with the core action first.

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

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

Given no output schema, the description adequately mentions return value (new subscription id). It covers auth, all required and optional parameters, delivery options, and rate limits. No additional context seems necessary for effective tool use.

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 significant meaning by explaining each type's filter structure with examples, constraints (e.g., phone must be verified), and optional delivery details (email/sms with caps). This greatly aids parameter understanding.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id,' providing a specific verb and resource. It 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?

The description implies usage by detailing the purpose and supported subscription types, but does not explicitly state when not to use it or compare to alternatives. It provides enough context for an agent to decide when to call subscribe versus other 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, destructiveHint=false. The description adds useful details about return values (label, definition, synonyms, cross-references) and the ID format, enhancing transparency 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?

Two sentences plus an example, no wasted words. Information is front-loaded with common query patterns, making it efficient for an agent to parse.

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 output schema exists, the description doesn't need to detail return format, but it still lists key fields. It provides domain context (HPO, rare-disease), ID format, and example. For a simple fetch tool, this is fully complete.

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

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

Schema has 0% description coverage, but the description compensates fully by explaining the 'id' parameter is an HPO term ID, with an example (HP:0001250) and explicit context. This adds significant meaning beyond the 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 clearly states that the tool fetches a single HPO term by ID and lists the return fields. It distinguishes from sibling tools like term_children and term_parents by focusing on 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?

Provides explicit query patterns ('What does HP:[N] mean' / 'look up HPO phenotype [ID]') and context about HPO's use in rare-disease research. While it does not explicitly state when not to use it, the examples imply the appropriate use case, and the sibling tools cover related 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 declare read only and non-destructive. Description adds that it returns direct children and provides an example, but lacks details on rate limits or authentication.

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-load the core purpose, with no wasted words, making it efficient for an AI agent to parse.

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

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

For a simple retrieval tool with an output schema, the description covers purpose, parameter, and usage context completely, with no gaps.

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

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

With 0% schema coverage, the description adds full meaning: the 'id' parameter is an HPO term ID, with an example (HP:0000118) and context of the ontology graph.

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 lists direct children of an HPO phenotype term, with a specific verb and resource, and distinguishes from siblings like term_parents or term_descendants.

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

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

Explicitly advises to use for narrowing from general to specific phenotypes, but does not explicitly state when not to use or provide alternative tool references beyond sibling 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?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. Description adds behavioral context by explaining 'transitive descendants' and 'full subtree', which clarifies the scope beyond what annotations provide. It does not mention potential scale or pagination, but openWorldHint covers that.

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

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

Extremely concise: two short phrases and an example. Every word adds value. Front-loaded with the core functionality ('All phenotypes under [HP:N]' / 'full subtree'). 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?

For a simple one-parameter query tool with an output schema, the description is complete. It explains what the tool does, provides a usage example, and distinguishes from siblings. No additional information is necessary.

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 must compensate. It does so by clearly indicating the parameter is an HPO term ID (e.g., HP:0001626) and providing an example in the schema's 'examples' field. This is sufficient for a simple string parameter.

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

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

Description clearly states it returns 'transitive descendants (children, grandchildren, …)' of an HPO term, with example 'every cardiac phenotype via descendants of HP:0001626'. Distinguishes from sibling tools like term_children (direct children) by emphasizing 'full subtree' and 'exhaustive coverage'.

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 exhaustive coverage' and gives a concrete example. While it implies when not to use (e.g., if only direct children needed), it does not explicitly state alternatives or when-not conditions. This is still clear and helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context about ontology graph traversal and that only direct parents are returned, which is consistent with annotations and adds value.

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

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

The description is a single sentence with an alternative phrasing, front-loaded with the core purpose. Every word adds value, no redundancy.

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

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

Given the simple tool (one parameter, output schema exists), the description is complete: it explains input, output (direct parents), and use case (walk up to broader term). 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?

The input schema has one parameter 'id' with no description (0% coverage). The description compensates by clarifying that the ID is an HPO ID and providing examples like 'HP:0001250', adding meaning beyond the raw schema.

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

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

The description clearly states it returns direct parents of an HPO term, with example queries. It distinguishes from siblings like term_children and term_descendants by specifying 'direct parents' and 'walk up to a more general phenotype class'.

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

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

The description explicitly says 'Use to walk up to a more general phenotype class', providing clear context for when to use. It implies differentiation from child/descendant tools, though it does not name them directly.

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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds that it uses authoritative sources (SEC EDGAR + XBRL), returns a structured verdict with citation and delta, and has version limitations (v1). This supplements the annotations without contradiction.

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

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

The description is approximately 5 sentences, front-loaded with trigger examples. Every sentence adds value: use case, supported domain, return format, efficiency benefit. 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?

For a single-parameter tool with comprehensive annotations and no output schema, the description fully covers purpose, usage context, domain limitations, and return structure. An agent can confidently invoke this tool.

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

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

Schema coverage is 100% with a single 'claim' parameter described well. The description enriches this by illustrating supported claim types (company-financial) and providing example formats, which goes beyond the schema description.

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

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

The description clearly states the verb ('verify', 'fact check', 'confirm or refute') and resource ('natural-language claim') with concrete examples. It distinguishes from siblings by noting it replaces 4–6 sequential calls, implying efficiency and uniqueness.

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 use when checking factual correctness of a user statement. It defines scope (company-financial claims for v1) and provides a clear use case. Absence of explicit when-not-to-use is acceptable given distinct purpose among siblings.

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