Opentargets

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds behavioral details: probes LLMs, scores 0-100, returns per-model and combined view, and notes that Anthropic calls require BYO key and direct payment. This enriches transparency 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 (4 sentences), front-loads the purpose and output, and efficiently covers behavior, parameters, and use cases 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?

Given the schema covers all parameters, annotations are comprehensive, and no output schema exists, the description adequately informs about input usage, return format, and default behavior. It could mention output structure more explicitly but remains sufficient for a 4-parameter tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds some context (free default, BYO key for Anthropic) already present in schema. It does not substantially enhance parameter meaning beyond the schema, so score remains at 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 clearly states the tool probes LLMs for visibility of an entity and outputs a score. It lists specific use cases (audits, pre-launch checks, competitive monitoring), distinguishing it from sibling tools like scan_competitor_ai_presence by focusing on general visibility across multiple models.

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 context on when to use the tool (AI-marketing audits, brand checks) and parameter usage (default model, optional key for Anthropic), but lacks explicit guidance on when not to use it or alternatives among sibling tools. It adequately covers parameter-level usage but not high-level decision.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: the tool routes to 3,745 tools across 884 sources and returns structured answers with citation URIs. It does not contradict annotations and provides behavioral insight beyond the structured fields.

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

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

The description is a single, well-structured paragraph that front-loads the key 'PREFER OVER WEB SEARCH' message. It is efficient, with every sentence contributing useful information. Slightly long but justified by the tool's complexity.

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

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

Given the tool's broad scope and lack of output schema, the description provides good context: types of sources, examples, and citation URIs. However, it does not detail the return structure (e.g., format, pagination) or what happens if no tool matches. Adequate but could be more complete.

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

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

Schema coverage is 100% with all parameters described. The description does not add significant meaning beyond the schema; it merely repeats that the parameter accepts natural language queries. Baseline 3 is appropriate as schema does the heavy lifting.

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 routes questions to a vast set of sources and returns structured answers with citations. It explicitly distinguishes itself from web search and provides numerous examples, making its purpose unmistakable.

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

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

The description gives explicit guidance: 'PREFER OVER WEB SEARCH' for a specific set of question types. It lists linguistic cues ('what is', 'look up', etc.) and concrete examples, effectively telling the agent when to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true. Description adds valuable behavioral context: costs one extra LLM call, returns explicit refusal reasons (not_in_source, no_tool_match, etc.), and explains the extraction process. No contradiction with annotations.

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

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

Description is detailed but front-loaded with the key differentiator ('Hallucination-resistant...'). Each sentence serves a purpose, though slightly longer than necessary. Overall well-structured and efficient.

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

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

Given the tool's complexity (many siblings, high-stakes usage), description covers purpose, usage context, behavioral traits, and return format (including refusal reasons). No output schema, but description compensates with a clear response structure.

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 parameter names described. Description adds that the question is 'in natural language' and lists the accepted aliases, which reinforces understanding. Since schema already covers, baseline is 3, but description provides minor additional value.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and differentiates it from sibling 'ask_pipeworx' for casual lookups. It specifies verb (extracts answer), resource (tool results), and exact use cases (financial verdicts, legal claims, etc.).

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 whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups'. This provides clear when-to-use and when-to-avoid, with direct alternative mentioned.

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

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

The description goes into exceptional detail about behavioral aspects beyond annotations. It explains fan-out patterns for different bet types, response shapes, safety mechanisms (low-confidence matches, closed market handling), parent_event extraction, news fallback handling, resolution rule parsing, and more. Annotations (readOnlyHint, idempotentHint) are consistent with the description, and the description adds critical context that annotations cannot convey. There is no contradiction.

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

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

The description is lengthy but well-structured with sections (classifiers, fan-out examples, response shapes, resolver contract, etc.). It is front-loaded with the core purpose and progressively adds detail. While every sentence provides value, the length could be trimmed without losing essential information. However, given the complexity of the tool, the length is justified.

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

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

Given the tool's complexity (3 parameters, no output schema, no nested objects), the description is extremely complete. It covers all edge cases: low-confidence matches, closed markets, illiquid spreads, resolution rules, parent events, news fallbacks, and safety short-circuits. Without an output schema, the description thoroughly explains the response structure and fields. No gaps are apparent.

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

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

Schema coverage is 100% (all three parameters described in schema), and the description adds substantial meaning beyond the schema. For example, the 'market' parameter is explained with multiple input formats and examples. 'depth' enum values are clarified with performance implications. 'include_raw' gets a detailed justification for its use. The description enriches understanding significantly.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research), resource (Polymarket bet), and provides examples of inputs (slug, URL, question text). The verb 'Research' combined with the resource and the examples makes the purpose unambiguous. Among siblings, tools like 'polymarket_edges' or 'polymarket_arbitrage' have distinct focuses, so this tool stands out.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear guidance on when to use the tool. However, it does not explicitly mention when NOT to use it or suggest alternative tools among siblings. The usage context is well-defined but lacks explicit exclusions.

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

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

Discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). Adds value well beyond annotations.

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

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

Single paragraph is information-dense with no fluff, though it could be better structured with bullet points for readability. Front-loads key phrases like 'side-by-side comparison'.

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

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

Given 2 parameters and no output schema, the description fully explains inputs, data fetched, sorting behavior, and output format (paired data + URIs). Complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% but description adds meaningful context: examples of valid values (tickers/CIKs, drug names), constraints (2-5 items), and explains what each type returns, enhancing 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?

Clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific verbs like 'compare', 'rank', 'head to head'. Distinguishes from sequential lookups and sibling tools like 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and gives example phrases indicating when to use. No explicit when-not statements, but the comparative 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?

The description discloses behavioral traits beyond annotations: parallel decomposition, verbatim evidence with confidence/source/citation, explicit gaps for unanswered facets, and the fact that facts are pre-verified. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false).

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

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

The description is appropriately sized and front-loaded with the core purpose. Every sentence provides essential information without redundancy, covering usage, alternatives, requirements, and output format efficiently.

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

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

Given the tool's complexity (2 parameters, no output schema), the description is remarkably complete. It explains the decomposition process, parallel routing, evidence structure, gap handling, and prerequisites, ensuring the agent has all necessary context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by noting that depth:'thorough' requires a paid plan, which is not in the schema's enum description. This context aids correct parameter choice.

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 does grounded multi-source research in one call, decomposing questions into sub-questions and routing them to thousands of tools. It explicitly distinguishes from sibling ask_pipeworx for single lookups, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool (broad/multi-part questions) versus when to use ask_pipeworx (single lookups). It also mentions the requirement of a Pipeworx account, paid plan for thorough depth, and expected response time of 15-60s.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context by stating it 'returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations.

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

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

The description is front-loaded with purpose and usage, lists domains concisely, and every sentence contributes. No filler.

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

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

Given no output schema, the description thoroughly explains the return value (top-N tools with names, descriptions, and full schemas) and its readiness for direct calling. All parameters are covered in schema and description. Sibling guidance is provided.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by providing examples for the query parameter and noting multiple aliases (task, q, description, search). It also specifies default and max limit. 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 states the tool finds tools by describing data/task, lists many domains, and distinguishes from siblings by advising 'Call this FIRST when you have many tools available.' It uses a specific verb-resource pair (discover tools) that is non-tautological.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use and implied when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds the data source and return fields but no additional behavioral traits 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?

Two concise sentences: first gives purpose and aliases, second adds return fields and pairing suggestion. No fluff, front-loads key information.

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

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

With output schema present and only one parameter, the description adequately covers what the tool returns and how to use it, including a reference to a sibling tool.

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

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

The single parameter efo_id is well-described in both the schema (with example) and the description (mentions EFO ID). Schema coverage is 100%, so the description adds minimal extra 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 fetches a disease profile by EFO ID from Open Targets, listing return fields and providing synonyms. It distinguishes itself from the sibling 'disease_associations' tool by suggesting a pairing use case.

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

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

The description explains the main use case (fetch disease profile) and explicitly recommends pairing with disease_associations for finding drug targets, offering clear context. It does not explicitly state when not to use, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context by mentioning 'scored by integrated evidence', 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 concise (three lines), front-loaded with example queries, and contains no superfluous information. Every part is purposeful.

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 (so return values are covered), and the tool has only two simple parameters, the description is mostly complete. It could be improved by noting the purpose of the 'size' parameter, but overall it provides sufficient context.

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

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

Schema_description_coverage is 0%, meaning no parameter descriptions in the schema. The description does not explain the required 'efo_id' or optional 'size' parameters beyond implying the EFO ID in the text. This is insufficient for agent understanding.

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

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

The description clearly states the tool gives 'top drug-target candidates for a disease (EFO ID), scored by integrated evidence' and provides example queries. It distinguishes from sibling tools implicitly by specifying 'target discovery in a therapeutic area', but lacks explicit differentiation from related tools like target_associations.

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

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

The description says 'Use for target discovery in a therapeutic area', giving a clear usage context. However, it does not specify when not to use this tool or mention alternative tools, leaving the guidance somewhat implicit.

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, so the description's claim of 'fetch a drug profile' aligns. The description adds detail on returned fields but does not contradict annotations, so a 3 is appropriate as it 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 extremely concise: two sentences that cover purpose, example queries, output, and usage. It front-loads the most important information (query patterns) and avoids unnecessary detail.

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 has an output schema (present), a single required parameter, and rich annotations, the description is complete. It lists all key return fields and the usage context. No gaps remain for this simple lookup tool.

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

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

Schema description coverage is 100% with a single parameter explained. The description mentions 'ChEMBL ID' but does not add new information beyond the schema's example. Baseline 3 is correct since the schema already does the heavy lifting.

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 fetches a drug profile from Open Targets using a ChEMBL ID, listing the specific returned data (name, mechanisms, indications, etc.). It uses specific verbs and resources, and distinguishes itself from sibling tools like 'disease' and 'target' by focusing on drugs.

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

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

The description provides clear context for when to use it (drug research, mechanism queries) but does not explicitly exclude cases or list alternatives among siblings. However, the sibling list itself implies alternatives, and the description's focus on drugs differentiates it.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds significant context: fans out across multiple sources in parallel, returns specific fields with constraints (e.g., up to 5 filings, sorted fundamentals), mentions patent sunset and fallback, and explains LEI and news fallback. No contradictions with annotations.

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

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

Description is dense but efficient, front-loading with examples and then detailing behavior in a structured manner. Every sentence adds value, though it could be slightly more concise. For the complexity of the tool, it is appropriately sized.

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

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

With no output schema, the description compensates well by listing return fields (CIK, company_name, recent_filings with URIs, fundamentals, patents with sunset, news fallback, LEI). It covers constraints and limits. Missing error handling for invalid tickers, but overall complete for the tool's complexity.

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

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

Schema covers both parameters with descriptions, so baseline is 3. Description adds value by specifying that 'value' must be ticker or zero-padded CIK (with example), explicitly states names not supported, and confirms 'type' only supports 'company'. This extra context justifies a 4.

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

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

Description clearly defines the tool as providing a full cross-source profile of US public companies. It lists specific data sources (SEC, XBRL, USPTO, news, GLEIF) and returned fields, and differentiates from sibling tools by stating it should be preferred over chaining single-pack lookups for holistic views. Examples include diverse queries like 'tell me about X' and 'company profile for Microsoft'.

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 (holistic view of US public companies) and when not to (if only have a name, use resolve_entity first). Also mentions that patents feature will sunset in May 2025 and provides fallback behavior, giving clear guidance on current limitations and alternatives.

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

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

The description discloses the destructive nature of forgetting, consistent with annotations (destructiveHint=true). It adds context beyond annotations by explaining why deletion is appropriate (e.g., stale context, sensitive data).

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

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

Two sentences with no wasted words. The action and resource are front-loaded, and every sentence serves a purpose. Highly efficient.

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

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

Given a single parameter, no output schema, and good annotations, the description covers all necessary context: what it does, when to use it, and how it relates to siblings.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add extra semantics beyond the schema's 'Memory key to delete' for the parameter. No added value.

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

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

The description clearly states 'Delete a previously stored memory by key,' using a specific verb and resource. It distinguishes from sibling tools like remember and recall by its action of 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 provides explicit usage contexts: '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, offering guidance on alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by explaining the process (fetching, extracting title/description/links) and output format (single text blob). However, it does not disclose error handling or what happens with invalid URLs.

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

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

The description is four sentences with no redundancy: first sentence states purpose, second describes process, third defines output, fourth lists use cases. Every sentence adds value and it is front-loaded with the core action.

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

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

For a simple two-parameter tool with no output schema, the description covers inputs, process, output format, and use cases. It lacks error cases and prerequisites (e.g., public site access), but these are minor omissions given the tool's straightforward nature.

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

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

Schema description coverage is 100%, so the parameters are well-documented in the schema itself. The description merely restates the defaults (max_links default 25, max 50) without adding new constraints or behavioral context.

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

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

The description clearly states the function: 'Generate a production-ready llms.txt file for any URL' and lists the specific steps (fetch, extract, emit). However, it does not explicitly differentiate from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which share the domain of AI site indexing.

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 use cases (client indexing, drafting, auditing) providing context, but does not specify when to avoid this tool or mention alternative siblings for similar tasks. Guidance is implied rather than explicit.

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, destructiveHint=false, and idempotentHint=true. Description adds context about return fields but doesn't reveal behavioral traits beyond annotations. No contradiction.

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

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

Description is two concise sentences with no fluff. Front-loads the purpose and returns structure, then advises usage. Every sentence adds value.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description explains return fields and usage. It is complete enough for an agent to understand what the tool provides.

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 for the single parameter (include_inactive). Description does not add further meaning to the parameter, but schema already documents it. 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 the action: 'List the caller's active subscriptions' and specifies return fields (id, type, etc.). It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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 gives explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This helps the agent decide when to invoke the tool. No 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?

Discloses rate limiting (5 per identifier per day), free usage, and that the team reads digests daily. These add behavioral context beyond annotations, which are generic.

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

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

Concise, front-loaded with purpose, and every sentence adds value. Well-structured with clear separation of use cases, constraints, and how feedback is used.

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 feedback tool, the description covers purpose, usage, limitations, and outcome. No output schema is needed, and the context is complete for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the schema's parameter descriptions (e.g., explains enum options) but does not add significant new 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's purpose: to send feedback to the Pipeworx team about bugs, missing features, or praise. It distinguishes itself from sibling tools as the only feedback channel among research and query tools.

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

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

Explicitly states when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). Also mentions rate limits and that it's free, providing comprehensive usage guidance.

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

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

Beyond annotations (read-only, idempotent), the description adds valuable behavioral details: caching intervals (5min-1h), data source (CF analytics-engine), no PII, and the exact data shape (pack, tool, count). This fully informs the agent of behavior.

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

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

The description is well-structured with a clear core statement and bullet-pointed use cases. It is reasonably concise, though slightly verbose; however, 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 lacking an output schema, the description thoroughly describes what is returned (top tools, top packs, total call volume) and the data format. Caching and data source are also covered, making the tool fully understandable.

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

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

The schema provides an enum and description for the window parameter. The description adds contextual insight on how to interpret window sizes ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which enhances understanding.

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

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

The description clearly states the tool returns trending data (top tools, top packs, call volume) over a window. It distinguishes itself from sibling tools by focusing on what other AI agents are calling, which is unique among the list.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical choice, checking alignment). Provides clear context for when to use, though no explicit when-not-to-use guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds detailed behavioral context: monotonicity checks, partition calculation, semantic anchor with Jaccard similarity, placeholder filtering, and fill check logic. This goes well beyond annotations.

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

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

The description is dense and well-structured, starting with a requirement statement and then explaining modes. However, it is somewhat verbose with many technical details. It could be slightly more concise, but every sentence adds value.

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

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

Given the tool's complexity (two modes, fill checks, partition checks, semantic filtering), the description is comprehensive. It explains response structure, edge cases (placeholder filters, low similarity), and criteria for actionable signals. No output schema exists, but description compensates well.

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

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

The input schema has 2 parameters with 100% description coverage. The tool description significantly enriches the parameter semantics by explaining the difference between event and topic modes, providing example values, and describing backend processing. The description adds substantial 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 states that the tool finds arbitrage opportunities on Polymarket via monotonicity and partition-sum checks. It explicitly differentiates between 'event' and 'topic' modes, and references sibling tools like polymarket_fill_risk for custom sizing.

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

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

The description provides explicit guidance on when to use each mode: 'event' for a specific market, 'topic' for cross-event scanning. It warns that calling with no args fails, explains when not to trade based on fill risk, and gives examples.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent, and the description adds extensive behavioral details: caching at KV level, three model families with their calculations, tradeable-edge knobs, diagnostics explaining empty segments, and data freshness (1h cache). This goes well 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 well-structured with numbered model families, bullet points, and clear sections for response top-level and diagnostics. Every sentence adds value, and the length is appropriate for the tool's complexity. It front-loads the core purpose and usage scenario.

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

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

Given no output schema, the description thoroughly explains the response structure: by_segment with three groups, fields like edge_pp_net, kelly_fraction, diagnostics, and Fed bets surface. It covers both success and empty segment cases. The tool is complex, and the description is comprehensive.

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?

Even though schema coverage is 100%, the description enriches each parameter with practical context: e.g., 'min_liquidity' is explained as a 'tradeable-edge filter', 'min_partition_leg_kelly' justifies its existence because partition arbs return kelly_fraction_half=0. The explanation for 'slippage_pp' includes real-world Polymarket conditions. This adds significant value beyond schema descriptions.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for disagreements between Pipeworx data and market prices. It explicitly connects to the use case 'what should I bet on today' and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on edge detection rather than cross-platform arbitrage.

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

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

The description provides a clear use case ('what should I bet on today') and explains the filtering knobs. However, it lacks explicit guidance on when NOT to use this tool versus alternatives like polymarket_arbitrage or polymarket_edge_tracker, which are listed as siblings but not directly compared in the text.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral details: it reads from daily snapshots, has a 60-day TTL, decay from daily closes not intraday, and gap handling. 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 dense but well-structured, starting with purpose, then output details, then limits. Every sentence adds value, though length could be slightly trimmed.

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

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

Without an output schema, the description thoroughly explains the returned fields (tracked, expired, snapshot_dates) and their subfields. It also covers limits and caveats, making it complete for an AI agent.

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

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

Schema covers both parameters with descriptions. The description adds some context (defaults, max 30) but with a slight inconsistency: schema says 'clamp 2-30', description says 'max 30'. Does not add substantial new meaning beyond schema.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and its trend. It distinguishes itself from sibling polymarket_edges by being a derivative analysis tool.

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

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

It explains the type of questions it answers (how long edge existed, is it shrinking?) and gives an example comparing fresh vs old wide edges. It doesn't explicitly state when not to use or alternatives, but the context from siblings makes it clear.

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

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

Annotations already declare read-only, non-destructive, idempotent. The description adds significant behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), and warns about forced_directional_risk and thin_legs. 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 every sentence provides value. It is well-structured with bold keywords (REQUIRES, SINGLE-MARKET, BASKET) and bullet-like listing of return fields. Front-loaded with core purpose. No fluff.

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

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

Given no output schema, the description compensates by detailing return fields for both modes and explaining edge cases (partial fills, thin books). It is comprehensive for a risk-check tool informing decisions.

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. Description adds meaning by explaining the two modes and how parameters interact (market vs event, side defaults, size_usd interpretation in basket mode as settlement notional). This enriches understanding beyond the schema.

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

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

The description clearly states it checks realizable-vs-theoretical edge against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and explicitly ties its use to specific sibling tools (polymarket_arbitrage, polymarket_edges) and trade sizes, making its purpose very specific and distinct.

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

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

The description explicitly says when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround not capturable, partial basket fills create directional risk) and warns of the dominant loss mode if not used.

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 detailed behavioral transparency: explains that compatibility_warning fires for non-equivalent bet shapes or semantically unrelated events, and that temporal_alignment indicates if spreads are meaningful across time gaps. 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?

Densely packed information with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value; no fluff. Front-loaded with purpose.

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

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

Given no output schema, the description fully explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). It also warns that most pre-mapped topics are not currently tradeable, setting proper expectations.

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?

All three parameters are described in the schema. The description adds significant value by listing the 10 topic shortcuts, explaining that custom parameters override the topic, and providing examples. This goes beyond the schema's brief descriptions.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes from siblings like 'polymarket_arbitrage' by focusing on two different prediction markets, not intra-venue.

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?

Explains two modes (topic shortcuts and custom ticker/slug pairs) and provides extensive guidance on when results are reliable via safety fields (compatibility_warning, temporal_alignment). Does not explicitly list alternative tools, but the context from sibling names and the tool's unique purpose is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds value by explaining scoping to an identifier (anonymous IP, BYO key hash, or account ID) and pairing with remember/forget, which goes beyond what annotations provide.

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

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

The description is concise at 4 sentences, front-loaded with the main purpose, followed by use case, scope, and pairing info. 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 (1 optional parameter, no output schema), the description covers retrieval, listing, scoping, and related tools. It is complete and leaves no major gaps.

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

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

Schema coverage is 100% with a description for the key parameter. The description adds semantic value by explaining that omitting the key lists all saved keys, 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 clearly states the verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It distinguishes from siblings like remember (save) and forget (delete) by explicitly naming 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 explains when to use the tool: 'to look up context the agent stored earlier... without re-deriving it from scratch'. It implies omitting key to list all, but does not explicitly state when not to use or list alternatives beyond the sibling relationship.

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 includes a flag 'mark_read' that modifies state (marks events as read), which contradicts the annotation 'readOnlyHint: true' indicating no state modification. This is a serious inconsistency.

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

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

The description is concise with four sentences, front-loading the purpose and adding essential details without redundancy. Each sentence contributes meaning.

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

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

Given no output schema, the description adequately explains return fields (source, citation_uri, payload) and parameter usage. It also notes polling suitability and an alternative endpoint, though error handling is omitted.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by explaining the effect of mark_read, giving an example filter type ('sec_8k'), and describing the 'since' parameter as an ISO timestamp.

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

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

The description clearly states the tool retrieves fired events from a subscription feed, with a specific verb ('pull') and resource. It distinguishes itself from siblings like 'list_subscriptions' by focusing on alerts and their contents.

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 context for when to use the tool (polling) and mentions an alternative REST endpoint for scripts/dashboards. It explains the mark_read parameter for controlling subsequent calls but does not explicitly contrast with sibling tools.

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

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

Beyond annotations, it details fan-out to multiple sources, GDELT/GNews fallback, USPTO soft-fail, and output structure. This adds valuable behavioral context.

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

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

Front-loaded with example queries, all sentences are useful. Slightly verbose but warranted given 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?

Covers all parameters, output structure, source behaviors, fallback, soft-fail, and alternative tool. No gaps given no output schema.

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

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

With 100% schema coverage, the description adds meaning: explains `since` format with examples, recommends typical values, and clarifies `value` can be ticker or CIK. This goes 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 provides a change feed for a company over a time window, with example queries. It distinguishes from the sibling 'entity_profile' by noting when to use that instead.

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

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

It gives explicit context for use (e.g., 'in one parallel call') and names an alternative ('entity_profile') for static profiles. It lacks explicit exclusions but is clear enough.

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

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

The description adds key behavioral details beyond annotations: key-value scoping by identifier, persistence for authenticated users vs 24-hour retention for anonymous sessions. Annotations already indicate idempotency and non-destructiveness, but this provides richer context.

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

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

The description is concise (5 sentences), front-loaded with the core purpose, and efficiently includes usage guidelines, behavioral notes, and sibling references without waste.

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

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

Given the simplicity of the tool (2 params, no output schema), the description fully covers what the agent needs: purpose, when to use, key-value format, scoping, persistence model, and references to complementary tools.

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 covers both parameters with clear descriptions and examples. The tool description does not add significant new parameter-level meaning beyond what the schema provides. Baseline score of 3 applies due to full schema coverage.

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

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

The description clearly states 'Save data the agent will need to reuse later' with specific verb 'save' and resource 'data to reuse later'. It distinguishes from siblings by explicitly mentioning 'recall' and 'forget'.

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

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

The description says 'Use when you discover something worth carrying forward ... so you don't have to look it up again' and advises pairing with 'recall' and 'forget', providing explicit when-to-use and 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral transparency by noting internal cascading through multiple lookup endpoints, replacing 2-3 manual lookups. 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 dense but could be slightly more structured. However, it is front-loaded with examples and usage, making it efficient.

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

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

Despite no output schema, the description fully explains return values and citations for both entity types. Parameter details and behavioral context are sufficient for correct invocation.

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

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

Schema covers 100% of parameters. The description adds meaning beyond schema by explaining what each type returns (ticker+CIK for company, RxCUI for drug) and auto-disambiguation for company names.

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/official identifier, with explicit examples (ticker, CIK, RxCUI). It distinguishes from sibling tools by noting it replaces 2-3 manual lookups.

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

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

The description advises 'Use FIRST whenever you have a name but need an ID.' and lists supported types with expected inputs/outputs. It does not explicitly exclude use cases but the context of sibling tools implies when not to use.

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

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

Annotations already declare safe, read-only, idempotent behavior. Description adds specific internal process: 'Probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized.' This enriches transparency beyond annotations without contradiction.

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

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

Three sentences, front-loaded with purpose, then method and example. Every sentence adds unique value; no fluff.

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

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

Given 100% schema coverage, good annotations, and no output schema needed, the description fully explains what the tool does, how it works, and when to use it.

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

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

Schema coverage is 100%, but description adds value by explaining the 'entities' array: 'First entry treated as the subject for narrative; rest are competitors.' Also clarifies 'models' and '_apiKey' usage 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?

Purpose is crystal clear: 'Compare AI visibility across multiple entities side-by-side.' Uses specific verb 'compare' and resource 'AI visibility across entities', distinguishing it from siblings like compare_entities and ai_visibility_check.

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

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

Provides explicit use case: 'competitive AI-marketing audits' with example question. Does not explicitly state when NOT to use or name alternatives, but the context is clear enough.

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

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

While annotations already mark the tool as read-only and idempotent, the description adds important behavioral context: partial failure handling, bundlephobia measurement delay (5-30s), and the sources_failed field. No contradiction with annotations.

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

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

The description is a single paragraph that packs significant detail without unnecessary words. It front-loads the core purpose. However, it is somewhat dense and could benefit from slight restructuring for improved scannability.

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

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

Despite no output schema, the description fully details the return structure (summary block fields, per-advisory detail, links, alternative versions). It also covers input constraints, ecosystem scope, and failure behavior. No gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context beyond schema: scoped packages are accepted for 'package', and 'version' defaults to latest. This extra guidance justifies a 4.

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

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

The description clearly states it is a composite check for 'should I add this npm package' across deps.dev and bundlephobia. It distinguishes from sibling tools by specifying NPM ecosystem only in v1 and noting alternative tools for other ecosystems.

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 safety, popularity, size, or cost of adding a package. Also provides exclusions (NPM only v1, other ecosystems via direct deps.dev) and mentions graceful degradation on partial failures.

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, so the description adds context about output (canonical IDs) and search semantics. No contradictions, and it complements annotations well.

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

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

The description is concise, front-loaded with examples, and clearly structured. Every sentence earns its place with no fluff.

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

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

Given the tool's complexity, rich annotations, and presence of an output schema, the description is complete enough. It explains the tool's purpose, usage flow, and output, leaving no major gaps.

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

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

Schema description coverage is 67%, and the description provides examples but does not add significant new meaning beyond the schema's parameter descriptions. The schema already explains entity values and size range.

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 across diseases, drug targets, and drugs in the Open Targets Platform. It provides example query patterns and explains that it returns ranked matches with canonical IDs, effectively distinguishing from sibling tools like target, disease, and drug.

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

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

It explicitly advises to use this tool first to find IDs, then call target/disease/drug for details, providing clear when-to-use guidance. It does not explicitly state when not to use it, but the alternatives are implied.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint). Description adds technical details: embedding model, window size, character offset, and 200K char cap. 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?

Single paragraph efficiently covers purpose, usage, limitations, and technical details. Front-loaded with main action. No redundant sentences.

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, description still explains return format (passages with offsets and scores). Covers character limit, pairing with other tools, and technical implementation. Adequate for an agent.

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

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

Schema has 100% coverage; description adds value with example query and clarifies the limit range. Enhances understanding of natural-language query semantics.

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' specifying the verb, resource, and action. It distinguishes from siblings by mentioning it pairs with ask_pipeworx_grounded.

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

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

The description provides explicit usage context: 'Use when the record is too big to cram into the prompt'. It suggests a complementary tool (ask_pipeworx_grounded), but doesn't explicitly list when not to use.

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

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

The description contradicts the idempotentHint annotation: it says 'Returns the new subscription id' implying a new ID each time, which is not idempotent. Aside from that, the description adds useful behavioral details (e.g., phone verification, daily caps, auto-disabling webhooks), but the contradiction overrides.

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 every sentence provides necessary detail. It could be better structured (e.g., bullet points), but all information is relevant and front-loaded with the core purpose.

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

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

Given the tool's complexity (3 params, no output schema), the description covers all essential aspects: return value, supported types, parameter examples, delivery options with constraints, and prerequisites. No significant 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 100% schema coverage, the description still adds significant value by providing concrete examples and constraints for each parameter (e.g., detailed templates for type-specific params, delivery channel requirements).

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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It enumerates supported types and delivery channels, distinguishing it from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description specifies that a Pipeworx OAuth account is required, and that anonymous or BYO accounts cannot persist subscriptions. It provides context for when to use this tool (to create subscriptions) but does not explicitly state when not to use it relative to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral context: it's an onboarding tool that returns categorized examples with tool shapes and explains the effect of the optional topic 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?

The description is a single comprehensive paragraph that includes synonyms, purpose, contents, and usage. It is front-loaded with common queries and is not overly verbose.

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

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

For a tool with one optional parameter and no output schema, the description is complete: it explains the return format (category-bucketed examples with tool calls), usage scenarios, and parameter behavior.

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

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

Schema coverage is 100% (1 parameter, described fully). The description adds context by listing possible focus areas and explaining how omitting the parameter gives a cross-category spread.

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

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

The description clearly states the tool is the onboarding entry point for a connected agent, explaining it returns category-bucketed example questions with tool calls. It distinguishes from siblings by specifying it helps users discover what to ask and how to call meta-tools.

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

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

It explicitly recommends using this tool first when not knowing what Pipeworx can do, and provides example queries ('what can I ask', 'give me ideas'). It doesn't explicitly state 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 already indicate the tool is read-only, idempotent, and non-destructive. The description adds transparency by listing the returned fields (symbol, name, biotype, protein IDs, pathways, synonyms) and the data source (Open Targets), 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—just a few sentences—and front-loaded with example queries. Every sentence adds value: examples, data source, returned fields, and usage context. No wasted words.

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

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

Given the tool's simplicity (one parameter), rich annotations, and the presence of an output schema, the description is complete. It explains the input, output, and use case without needing to detail return values (handled by output schema).

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 covers the single parameter 'ensembl_id' with 100% coverage, describing it as a string with an example. The description reinforces that it uses Ensembl gene IDs and provides usage patterns, adding meaningful context beyond the schema.

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

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

The description clearly states the tool's purpose: 'fetch a drug-target profile' for a given Ensembl gene ID. It provides specific example query patterns and distinguishes from sibling tools (e.g., 'disease', 'drug', 'target_associations') by focusing on target characterization.

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 example queries that guide when to use the tool (e.g., 'Drug target profile for [gene]') and states the context 'Use for target characterization in drug discovery.' However, it does not explicitly mention when not to use it or name alternatives, leaving room for improvement.

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 value by explaining the scoring mechanism (genetics, expression, animal models, drugs, literature, pathways) and the type of output (top disease associations with integrated evidence). 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, well-structured paragraph of three sentences. It front-loads example queries, states the core function, and lists evidence types. Every sentence adds value with no redundancy. It is appropriately concise for the tool's complexity.

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

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

Given the tool's complexity (multiple evidence sources) and presence of an output schema (not shown), the description provides a good overview of what the tool returns and how scores are derived. It lacks details on score interpretation, but the output schema likely covers that. The description is sufficient for an agent to understand the tool's purpose and usage.

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

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

Schema description coverage is 50% (size has description, ensembl_id does not). The description adds meaning by specifying that ensembl_id is an 'Ensembl gene ID' and that results are 'scored by integrated Open Targets evidence,' which clarifies the output semantics. The example usage further reinforces parameter usage. This compensates for the missing 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 tool's purpose: to find top disease associations for a drug target (Ensembl gene ID) using integrated Open Targets evidence. It includes example queries that mirror user intent, and the use verb 'triage' specifies the action. The description implicitly distinguishes from siblings like 'disease_associations' by focusing on target-to-disease relationships.

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

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

The description provides explicit usage context: 'Use to triage what diseases a candidate target might address.' It includes example user queries, which guide when to invoke it. However, it does not explicitly state when not to use this tool or mention alternatives among siblings, which would elevate it to 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds that the tool returns specific fields (names, mechanisms, indications, phases) and implies querying an external dataset. No contradictions. Could be more explicit about data freshness or rate limits, but overall adequate.

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?

Highly concise: two sentences plus parenthetical examples, front-loaded with natural language patterns. Every sentence adds value—no filler.

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

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

Given the presence of output schema (which documents return structure) and rich annotations, the description covers purpose, inputs, output fields, and use cases. It is complete without requiring supplementary 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?

Schema description coverage is 50% (only 'size' has description). The description compensates by explaining that 'ensembl_id' is an Ensembl gene ID, clarifying required parameter semantics beyond the schema. The 'size' parameter details are already in the schema, so description adds marginal value there.

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 returns drugs that target a given Ensembl gene ID, including drug names, mechanisms, indications, and clinical trial phases. It provides natural language query examples to clarify intent. This is distinct from siblings like 'drug' or 'target_associations' which cover different aspects.

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 mentions use cases: 'competitive landscape / drug-repositioning queries'. However, it does not provide explicit when-not or alternative tools for other scenarios, leaving some guidance implicit.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds key details: ownership enforcement and that the row is deactivated, not deleted, preserving historical events via 'recent_alerts'. 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 two sentences with zero waste. The first sentence front-loads the core action and ownership constraint; the second adds a crucial behavioral detail. Every phrase earns its place.

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

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

Given no output schema, the description explains the effect (deactivation) and references relevant sibling ('recent_alerts'). However, it lacks description of return value or error cases, leaving some context incomplete for an agent.

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

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

Schema coverage is 100% (parameter 'id' described as 'Subscription id (uuid) returned by subscribe'). The description merely restates 'by id' without adding new semantic meaning, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by describing the cancellation action and noting that historical events remain available via 'recent_alerts'.

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

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

The description implies usage for cancellation but does not explicitly state when to use this tool versus alternatives. Ownership enforcement is mentioned, but no guidance on prerequisites or when not to use is provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds valuable context: returns verdict, structured form, actual value with citation, percent delta, and uses SEC EDGAR + XBRL. 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?

Well-structured starting with user intent phrases, then purpose, scope, and output. Every sentence adds value, though slightly verbose. Could be trimmed slightly.

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, description compensates by detailing return values (verdict, structured form, actual value, citation, delta). Clarifies domain, source, and version limitation. Fully adequate for a single-parameter tool.

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

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

Schema description coverage is 100%, but the description provides example claims and clarifies natural-language input, adding meaning beyond the schema's brief description. Baseline 3, plus extra value for examples.

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

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

The description clearly states it performs natural-language claim verification against authoritative sources, with specific examples of user intents. It distinguishes itself from sibling tools like 'deep_research' or 'search' by being specialized for fact-checking financial claims.

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 whenever the agent needs to check whether something a user said is factually correct.' Also notes it replaces multiple sequential calls, implying efficiency. Could be improved by stating when not to use (e.g., non-financial claims).

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