Ensembl

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

Annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool probes LLMs, returns per-model scores/confidence/signals/raw_response, and notes the cost implication for Anthropic (user pays). No contradictions.

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

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

The description is front-loaded with the core purpose, then explains default behavior, optional parameters, return format, and use cases. Every sentence adds unique value with no redundancy or wasted words.

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

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

Despite no output schema, the description fully explains the return structure (per-model fields + combined view), covers default and optional behavior, and provides use contexts. The tool complexity is well-addressed with 4 parameters and clear behavioral notes.

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

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

Schema coverage is 100%, and the description adds value by explaining the default model for the 'models' parameter, the purpose of '_apiKey' (BYO key for Anthropic), and examples for 'entity' and 'context'. This exceeds the baseline of 3.

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

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

The description clearly states it probes LLMs for knowledge about businesses/brands/products/topics and scores visibility (0-100). It specifies the default model, optional Anthropic with BYO key, and the return structure. This distinguishes it from siblings like 'scan_competitor_ai_presence' by focusing on general visibility scoring.

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 lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default free model vs. paid Anthropic option. It does not explicitly exclude alternatives or contrast with sibling tools, but the context is clear enough for appropriate selection.

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

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

Annotations already show readOnly, openWorld, idempotent hints. Description adds: routes to the right tool out of 4,770, returns structured answer with pipeworx:// citation URIs, works on every tier, one fast call. 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?

While the description is lengthy, it is front-loaded with the key directive 'PREFER OVER WEB SEARCH' and each sentence adds value. Could be slightly trimmed but still effective.

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

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

Given the complexity of a routing tool with many sources and no output schema, the description covers purpose, usage, behavior, and examples well. 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 has 100% coverage with descriptions for all 6 parameters (all aliases for question). Description does not add extra semantic detail beyond what schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it routes factual questions to 4,770 sources, with specific examples like SEC filings, weather, patents. It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides precise guidance on when to use ask_pipeworx_grounded (hallucination-resistant) vs deep_research (broad/multi-part). Includes example queries.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it costs one extra LLM call, specifies refusal reasons, and emphasizes data-only answers. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and includes all essential details in a compact format. Every sentence provides value, and the structure flows logically from function to usage to behavioral notes.

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 explains the return format including fields like answer, evidence, confidence, and refusal reasons. It covers cost implications and use cases, making it highly complete for a complex 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 all parameters clearly documented as aliases for 'question'. The description does not add new parameter information, but the schema is self-sufficient, 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 identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool results. It distinguishes itself from the sibling 'ask_pipeworx' by noting the extra LLM call and grounded behavior.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). Provides clear alternatives and context for high-stakes decisions.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, etc.) by detailing fan-out behavior, response shapes, resolver contract, parent_event extraction, news fields, safety mechanisms (low-confidence short-circuits, closed market detection), wide-spread market handling, and resolution-rule risk. It discloses potential blocking routes and pure-rules loss, providing exceptional transparency.

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

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

The description is verbose and not concise, spanning multiple paragraphs with detailed sections. While every sentence adds value, a more streamlined structure could improve readability. The length is justified by complexity, but conciseness is compromised.

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

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

Given the tool's complexity (multiple fan-out paths, response fields, safety checks) and the absence of an output schema, the description is remarkably complete. It covers the response structure (result.market, result.analysis, result.evidence), resolver confidence, parent_event extraction, news error handling, and edge cases like closed markets, illiquid spreads, and cancellation rules. No gaps are evident.

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

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

The input schema has 100% description coverage for all three parameters. The description adds substantial context beyond the schema, explaining the meaning of 'depth' values (quick vs thorough), the flexibility of 'market' input (slug, URL, question), and the effect of 'include_raw' on response size and usability. This aids correct parameter usage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet/Pipeworx data), and provides extensive detail on how it works. It distinguishes itself from siblings like polymarket_arbitrage or polymarket_edges by focusing on a single bet's comprehensive data pull.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-out by category. However, it does not explicitly mention when not to use it or compare it to alternatives, though the context makes it clear it's for individual bet research.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds critical context: it pulls latest financial data from SEC EDGAR/XBRL for companies (handling off-calendar fiscal years), FAERS data for drugs, and sorts results by primary metric. It also mentions returning citation URIs, no contradictions with annotations.

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

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

The description is informative but slightly verbose, with multiple examples and details. It front-loads example queries, which is good, but could be more concise while retaining all necessary information. Each sentence adds value, but the overall length could be reduced by 20–30%.

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 entity types, different data sources, sorting, citation URIs), the description is comprehensive. It explains what each type returns, how results are ordered, and what format the output takes (paired data + citations). No output schema exists, but the description adequately covers return values.

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

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

Schema coverage is 100%, but the description adds significant meaning: for type parameter, it explains what data is pulled for each enum value; for values parameter, it specifies tickers/CIKs for companies and drug names, and enforces 2–5 items. It also describes result ordering and citation URIs, adding value beyond schema.

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

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

The description clearly states that this tool performs side-by-side comparison of 2–5 companies or drugs, using specific data sources (SEC EDGAR/XBRL, FAERS). It distinguishes itself from sibling tools like lookups by explicitly stating it should be preferred over sequential single-pack lookups.

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

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

The description provides explicit examples of when to use the tool ('compare X and Y', 'which is bigger', 'rank these companies') and strongly recommends it over sequential lookups. It implicitly covers when not to use (if not comparing entities) and mentions replacement of 8–15 sequential lookups.

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

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

Discloses account requirement, paid plan for thorough depth, parallel decomposition, return format with gaps array, and expected duration (15-60s). Annotations already indicate readOnly and idempotent; description adds critical behavioral context without contradiction.

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

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

The description is somewhat lengthy but every sentence earns its place. It front-loads the critical account requirement, then explains functionality, alternatives, and return format. Minor redundancy (e.g., repeating 'structured data sources' multiple times) prevents a perfect score.

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

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

For a complex tool with parallel execution and no output schema, the description thoroughly covers input constraints, output structure (evidence with confidence, source, citation, gaps), timing, and typical use cases. No important aspect is left unexplained.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds detail: maps depth enum values to facet counts (quick=3, standard=5, thorough=8) and clarifies that question should be broad/multi-part, enhancing the schema's 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 performs grounded multi-source research across 1242 structured data sources, decomposes questions into facets, and returns a findings packet with evidence. It distinguishes itself from siblings like ask_pipeworx by emphasizing parallel tool routing and structured data, not open-web search.

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

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

Provides explicit guidance on when to use this tool (broad/multi-part questions over structured data) versus alternatives (ask_pipeworx for single lookups or breaking news). Also specifies account requirements and depth options, making it easy for the agent to decide.

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 reader-only and non-destructive nature; description adds that results are ready to call with curated examples, enhancing transparency without contradiction.

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

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

Two sentences with front-loaded purpose, efficient use of list format for domains, and no wasted words.

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

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

Despite no output schema, description explains that returns top-N tools with names, descriptions, and full schemas with examples, ready to call – fully sufficient for understanding the tool's function.

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 detailed parameter descriptions; description adds context about aliases and provides examples, slightly surpassing baseline.

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

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

The description clearly states 'Find tools by describing the data or task' and lists diverse domains, distinguishing it from sibling tools by advising to 'call this FIRST' when browsing options.

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

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

Explicitly states 'Use when you need to browse, search, look up, or discover what tools exist' and advises to call this first to see the option set, providing clear when-to-use guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds behavioral details: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, patents soft-fail until May 2025, and pass ticker or CIK. This adds value beyond annotations, though could mention response format more explicitly.

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

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

Description is a single dense paragraph that front-loads query examples, then lists data sources and return fields. It's informative but slightly long; could be broken into bullet points for clarity. 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?

Despite lacking an output schema, the description comprehensively lists return values: cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI. It also mentions patents soft-fail and name limitation. This provides sufficient context for an agent to understand what the tool returns and its limitations.

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 both parameters thoroughly described. The description adds that type only supports 'company' and value is ticker or CIK, but this is already in schema enums and description. No significant extra semantic value beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company' and provides example queries like 'Tell me about X' and 'profile for Microsoft'. It distinguishes from siblings by explicitly preferring over chaining individual lookups and directing name-only queries to resolve_entity.

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

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

Explicitly says when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also states when not to use: 'names not supported (use resolve_entity first if you only have a name)' and notes patents soft-failure. This provides clear usage boundaries.

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

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

Description clearly indicates a destructive action ('Delete'), aligning with destructiveHint=true. It adds context about clearing sensitive data, which is not in annotations. No contradictions.

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

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

Two sentences, zero unnecessary information, front-loaded with clear verb and resource.

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

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

Given the tool's simplicity (one required param, no output schema), the description fully covers 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 coverage is 100% and describes 'key' as 'Memory key to delete'. The description does not add further semantic detail 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?

Description states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Explicitly lists use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also mentions pairing with remember and recall.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains the workflow 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?

Three sentences, front-loaded with purpose, then additional detail. Every sentence adds value; no fluff.

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

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

Given the two parameters with full schema coverage and no output schema, the description adequately describes the output format ('single text blob in standard llms.txt markdown format'). It could mention edge cases (e.g., error handling, robots.txt respect) but is sufficient for a production-ready 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 mentions 'max_links' default and max values, and 'url' is implied in 'Fetches the page', but it adds no new semantic meaning beyond the schema.

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

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

Description clearly states the verb 'generate', the resource 'llms.txt file for any URL', and the intended audience 'AI crawlers (ChatGPT, Claude, Perplexity)'. It distinguishes itself from sibling tools, none of which perform this specific task.

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 provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not explicitly mention when not to use or name alternatives, but the context is clear enough for an agent.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds domain-specific context about orthologs/paralogs and cross-species comparison, which is useful 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?

Description is a single sentence with examples; it is concise and front-loaded with purpose. However, structure could be improved for readability.

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

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

Given output schema exists and annotations are rich, the description adequately covers use cases and examples. It mentions cross-species comparison, model organism work, and evolutionary analysis, which is sufficient for a tool with structured metadata.

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

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

Schema description coverage is 0%, so description must compensate. The description hints at target_species parameter with 'in [species]' but does not explain any parameter meanings, formats, or constraints. Examples in schema provide some context but description itself lacks detail.

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 finds orthologs and paralogs across species with example queries like 'ortholog of [gene] in [species]'. It lists use cases (cross-species comparison, model organism work, evolutionary analysis). However, it does not explicitly differentiate from sibling tools like 'lookup_symbol' or 'vep'.

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 provides example queries and mentions use cases (cross-species comparison, model organism work, evolutionary analysis). It gives context for when to use, but does not specify when not to use or mention alternative tools.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds value by detailing the return fields and the effect of the include_inactive parameter, with no contradictions.

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

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

Two sentences: first states the action and return fields, second gives usage guidance. No wasted words, information is front-loaded.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers what is returned and when to use it. It could mention default behavior (active only) but that is implied by the 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?

Schema coverage is 100% with a description for the single boolean parameter. The description reinforces the parameter's effect but does not add significant meaning beyond the schema.

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

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

The description clearly states the tool lists the caller's active subscriptions, and specifies the returned fields (id, type, params, etc.). This differentiates it from siblings subscribe and unsubscribe.

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

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

The description advises using this tool to review subscriptions before adding more or to find an id to cancel. It provides clear context for usage, though it could explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is safe and repeatable. The description adds value by specifying return fields (name, biotype, chromosomal position, strand, description) and the effect of the expand parameter (child features). 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 concise: a single paragraph that starts with alternative query patterns, then lists return fields, explains expand, and ends with an example. Every sentence adds value; no wasted words. Front-loaded with 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?

Given the output schema exists, the description does not need to detail return structure. It covers purpose, parameters, and behavior (with expand example) sufficiently for a simple lookup tool. No missing critical information for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds real-world context: 'Pass expand=true to include child features (transcripts of a gene, exons of a transcript)', which elaborates on the schema's brief 'Include child features.' It also provides an example with expand=true, enhancing 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 fetches metadata for an Ensembl stable ID, covering gene, transcript, exon, and translation types. It provides a specific example (ENSG00000157764 for BRAF), making the purpose concrete. Implicitly distinguishes from siblings like lookup_symbol by focusing on Ensembl IDs rather than symbols.

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

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

The description gives clear usage context: use this tool when you have an Ensembl ID and need metadata. It includes an example query pattern. However, it does not explicitly contrast with sibling tools like lookup_symbol, sequence, or vep, which could be more appropriate for other tasks (e.g., symbol lookup or sequence retrieval).

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 behavioral context by specifying the return data (Ensembl gene ID, chromosomal position, biotype, description) and the required species and symbol parameters. 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 concise (around 100 words) and well-structured, front-loading example queries to immediately convey the tool's purpose. Every sentence adds value without redundancy.

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

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

For a lookup tool with an output schema (mentioned but not shown), the description adequately explains the inputs, use case, and return data. It could mention potential limitations (e.g., supported species), but the provided examples and usage guidelines offer sufficient completeness for an agent to select and invoke the tool correctly.

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

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

The input schema has 3 parameters with only 33% documentation coverage (species has a description). The description provides example usages for symbol and species, and the input schema examples show expand:true, but does not explicitly explain the expand parameter. The examples partially compensate but leave room for improvement.

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: look up a gene by symbol within a species, returning Ensembl gene ID, chromosomal position, biotype, description. Example queries like 'BRCA1 / TP53 / BRAF Ensembl info' make the purpose immediately apparent and distinguish it from sibling tools like 'lookup'.

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

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

The description explicitly states when to use: 'Use to convert HGNC gene symbols to Ensembl IDs for genomics workflows.' It also provides example queries that imply appropriate usage contexts. However, it does not explicitly state when not to use or mention 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?

Describes rate limit of 5 per identifier per day, states it's free and doesn't count against tool-call quota, and mentions team reads digests daily. Annotations already indicate non-destructive write; description adds useful operational constraints.

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

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

Four sentences, front-loaded with purpose, no wasted words. Each 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 simplicity (3 params, no output schema), the description fully covers purpose, usage, constraints, and tips. It is complete and self-contained.

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

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

Schema already provides 100% coverage with detailed descriptions for each parameter. Description adds extra guidance for the 'message' parameter (don't paste user prompt) and clarifies when to use each type.

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 sends feedback to Pipeworx team and enumerates specific use cases (bug, feature, data_gap, praise). It is distinct from sibling tools which are for queries, research, or other actions.

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

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

Explicitly advises when to use each feedback type, instructs to describe in terms of Pipeworx tools/packs rather than user prompts, and mentions rate limits and quota-free usage.

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

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

Annotations confirm readOnly, idempotent, not destructive. The description adds valuable behavioral context: self-aggregating, no PII, cache TTL 5min-1h. No contradictions.

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

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

Concise and well-structured: front-loaded with what it returns, followed by bullet-pointed use cases and caching details. No extraneous information.

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

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

Given the simple tool with one optional parameter and comprehensive annotations, the description fully explains return values, intended uses, and caching. No gaps.

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

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

Schema coverage is 100% with a single parameter 'window' fully described. The description repeats the window options but adds no new semantic meaning beyond the schema's own 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 it returns trending tools, packs, and call volume, distinguishing it from sibling tools like ask_pipeworx or discover_tools. The verb 'returns' and resource 'top tools, top packs, and total call volume' are specific.

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

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

Three explicit use cases are listed (discovering hot data, confirming canonical choice, seeing alignment). While it doesn't explicitly state when not to use, the context implies alternatives for specific queries. Guidance is clear and actionable.

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

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

Annotations already indicate safe read-only behavior, and the description adds extensive behavioral details: Jaccard similarity threshold, placeholder filter, fill check logic, and response structure. No contradiction with annotations.

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

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

The description is comprehensive but slightly dense; however, it is well-structured with capitalized key terms (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and every sentence provides necessary information without 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 complexity (two optional parameters, advanced logic), the description covers all essential aspects: modes of operation, algorithmic details, edge cases, and response format. No output schema, but response structure is described.

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

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

Schema coverage is 100%, and the description adds rich context for both parameters: event mode recommended with example slugs, topic mode for cross-event with example seed questions, and explains how each mode works.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by specifying its unique approach and output.

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 explains three calling modes: no args for trending scan, event slug for specific market, or topic for cross-event scanning. Provides example slugs and seed questions, and advises when to use each mode. Also notes the fill check and references polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds extensive behavioral detail beyond annotations, including the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), response structure with diagnostics, edge metrics, tradeable-edge knobs, and caching at KV level. 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 verbose but well-structured, with clear sections for model families, knobs, and response top-level. While every sentence adds value, it could be slightly more concise without losing essential detail. The front-loading of purpose and key segments is effective.

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

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

Given the tool's complexity (9 parameters, 3 model families, no output schema), the description is exceptionally complete. It explains the response structure in detail, including segments, diagnostics, edge metrics, and caching. It covers edge cases like Fed candidates and why partition loops skip placeholder slugs.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds significant extra meaning, such as explaining why min_kelly skips small opportunities, detailing slippage assumptions and Polymarket liquidity, and clarifying how min_partition_leg_kelly applies to partition legs versus basket level.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for betting decisions. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_kalshi_spread by focusing on edge detection across three model families.

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 the tool's purpose ('what should I bet on today') and explains the three opportunity segments. It mentions caching behavior and parameter knobs for filtering. However, it does not explicitly state when not to use this tool versus alternatives, though the detailed context implies its specific use case.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds significant behavioral details: history bounded by 60-day TTL, gaps due to cache-miss, decay computed from daily closes, not intraday. 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 thorough but somewhat verbose. It is well-structured with front-loaded purpose, response details, and limits. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Given no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) with field details including edge cases and limits. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: 'days' lookback default 14 clamp 2-30, 'window' snapshot family default '1wk'. This goes beyond the schema parameter names and 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: tracking edge persistence and decay from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tool 'polymarket_edges' by focusing on history and trends rather than current data.

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

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

The description implies usage context by comparing fresh vs. old edges, but it does not explicitly state when to avoid this tool or recommend alternatives. It does provide limits and data characteristics that guide appropriate 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 readOnlyHint and idempotentHint are consistent with description's read-only behavior. Description adds significant context: returns verdicts (clean/degraded/cannot_fill), warns about thin books and partial basket fills converting to unhedged directional positions, which are critical behavioral traits not covered by 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 long but well-structured with bold headers and front-loaded purpose. Every sentence adds value. Could be slightly more concise, but given the complexity of two modes, it is 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?

Describes return fields exhaustively for both modes, warns about partial fills and directional risk, and covers edge cases (thin books) despite having no output schema. Complete for a tool with this many parameters and two distinct usage modes.

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 meaning: explains side defaults and auto mode for basket, size_usd interpretation as settlement notional for basket with clamp 10–1,000,000, and that default is 1000. 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?

Description states specific verb 'check' and resource 'edge against live CLOB order-book depth'. Clearly distinguishes single-market and basket modes, and differentiates from siblings like polymarket_arbitrage and polymarket_edges by stating this is a prerequisite 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?

Explicitly requires one of 'market' or 'event' and explains each mode. States 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing clear when-to-use and when-not-to-use guidance.

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

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

The description is extremely transparent, detailing the two modes, response structure (leg-by-leg prices, matched spreads, top_spreads_pp), and safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype). It explains edge cases clearly and does not contradict annotations (readOnlyHint, idempotentHint, destructiveHint false). The description adds significant behavioral context beyond the annotations.

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

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

The description is dense with useful information, front-loading the purpose and modes. While a bit long, every sentence contributes meaningful guidance. Minor redundancy in the safety fields section could be tightened, but overall well-structured.

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

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

Given the complexity of cross-venue spread computation and the lack of an output schema, the description thoroughly covers all aspects: modes, parameters, response fields, safety fields, and interpretation of warnings. It provides enough context for an agent to successfully invoke and interpret results.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining the interaction between topics and explicit tickers, providing concrete examples, and clarifying the mode logic. It does not repeat schema but enriches 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two distinct modes (topic shortcuts and explicit tickers) and differentiates from intra-venue tools like polymarket_arbitrage by focusing on cross-venue spreads.

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, including the limitations of pre-mapped topics and the meaning of safety fields. It explains when the tool returns no spread (compatibility warning) and why, which helps the agent avoid misuse. However, it does not directly contrast with sibling tools like polymarket_arbitrage.

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

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

Annotations indicate read-only and idempotent; description adds scoping to identifier and pairing context without contradiction.

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

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

Two sentences with zero waste, front-loaded with action and context.

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

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

Given one optional parameter and no output schema, description fully covers behavior, use cases, and scoping.

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

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

Schema already covers parameter meaning at 100%; description restates usage but provides only minor additional context.

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

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

Description clearly states the tool retrieves a saved value or lists keys, using specific verbs and distinguishing from siblings remember and forget.

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

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

Explicitly states when to use (look up stored context) and references sibling tools, but lacks explicit when-not-to-use or alternatives beyond the immediate family.

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

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

The annotations declare readOnlyHint=true, but the description describes mark_read:true as a parameter that flags events as read, which modifies state. This is a direct contradiction between the description and annotations, making the tool's behavioral profile misleading.

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 front-loads the main purpose. It is relatively concise but could be broken into shorter sentences for easier scanning. Every sentence adds value, so it 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 fully explains the return shape (source, citation_uri, raw payload). It also covers polling behavior and an alternative API endpoint. All 5 optional parameters are addressed, making the tool self-contained.

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

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

Although the input schema covers 100% of parameters, the description adds significant meaning: 'type' example ('sec_8k'), 'since' as ISO timestamp, 'limit' bounds (1-200), 'mark_read' effect on subsequent calls, and 'unread_only' behavior. This goes well beyond the schema's minimal 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 pulls fired events from a subscription feed. It specifies the return fields (source, citation_uri, payload) and provides filtering options. This is a specific verb+resource pair that distinguishes it from sibling tools like list_subscriptions or subscribe.

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

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

The description mentions that polling works fine and provides an alternative access method (GET registry.pipeworx.io/alerts.json). It does not explicitly state when not to use this tool, but the alternative suggestion gives clear context for usage.

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

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

The description provides rich behavioral context beyond annotations: it reveals the tool fans out to multiple APIs, includes a fallback strategy (GDELT→GNews), soft-fails for USPTO due to sunset, and details the since parameter's date interpretation. Annotations only indicate readOnly, openWorld, idempotent, non-destructive; the description adds essential operational details.

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

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

The description is front-loaded with usage examples, then covers sources, date formats, fallback, return structure, and sibling tool reference. Every sentence has a clear purpose; there is no redundancy or fluff. It is appropriately sized for the complexity of the tool.

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

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

With no output schema, the description explicitly states the return structure ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It covers parameter semantics, error handling (soft-fail), and fallback behavior. The tool is complex (multiple sources, non-trivial logic) and the description covers 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 explaining the typical use of 'since' (e.g., '30d' or '1m' for monitoring), clarifying that 'value' accepts ticker or CIK, and describing the fallback behavior tied to the parameters. This exceeds simple schema repetition.

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

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

Description starts with vivid user queries like 'What's new with X' and states it's a change feed for a company in a time window. It lists sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes from sibling tool entity_profile, which provides a static profile. This makes the purpose crystal clear and differentiates it well.

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 this tool (e.g., 'latest on Y', 'news on Tesla recently') and explicitly tells when not to use it: 'Use entity_profile instead when you want the static profile'. It also describes fallback behavior (GDELT→GNews), but lacks a broader statement of exclusions or alternative tools for other scenarios.

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 idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds important behavioral context: scoping by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. 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?

Four concise sentences, each serving a distinct purpose: stating the tool's function, providing use cases, describing storage behavior, and mentioning companion tools. No wasted words; 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 simplicity (2 required parameters, no output schema, no nested objects), the description covers all necessary context: why to use it, what to store, how scoping works, and retention details. No gaps.

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

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

Input schema has 100% description coverage for both 'key' and 'value', providing clear format hints (e.g., 'subject_property','target_ticker') and purpose. The description reinforces the meaning but does not go beyond the schema in a transformative way; thus a 4 is appropriate.

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

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

The description uses a specific verb ('Save') and resource ('data'), clearly states it stores key-value pairs for later reuse, and provides concrete examples (resolved ticker, target address, user preference). It is easily distinguishable from siblings like 'recall' and 'forget'.

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

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

Explicitly states when to use the tool: 'when you discover something worth carrying forward' so as to avoid re-lookup. It also explicitly mentions pairing with 'recall' to retrieve and 'forget' to delete, providing clear context on usage alongside 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 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?

Multi-line description is front-loaded with examples and usage directive. Every sentence adds value, though slightly verbose. Could trim some redundancy but overall 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 no output schema, the description details return formats for both entity types and explains internal cascading behavior. Covers disambiguation and citation URIs. Lacks error handling info, but annotations (openWorldHint) imply potential gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches this by providing specific value examples (e.g., 'AAPL', '0000320193', 'ozempic') and detailing the return format for each type (ticker + CIK + company_name for company; RxCUI + ingredient + brand for drug). This adds meaning beyond the schema.

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

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

Description explicitly states 'resolve a user-spoken NAME to the canonical/official identifier' with concrete examples ('What's the ticker for…'). It distinguishes itself by stating 'Use FIRST whenever you have a name but need an ID.' Among siblings like 'lookup_symbol' and 'entity_profile', this tool is clearly positioned for name-to-ID resolution.

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

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

Provides explicit when-to-use directive ('Use FIRST whenever you have a name but need an ID'). Lists supported entity types with input/output specifics. Lacks explicit when-not-to-use or alternatives, but the purpose is clear enough to imply appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: probes each entity via ai_visibility_check, ranks by score, and returns score, confidence, signal density. No contradiction with annotations.

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

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

The description is a single paragraph of five sentences that front-loads the main action and result. Every sentence adds information, though some minor repetition ('Useful for...') could be trimmed for tighter conciseness.

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

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

Given the tool's complexity and absence of output schema, the description adequately describes return format (ranked list with fields). Combined with annotations, it provides sufficient context for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds value by explaining the role of entities (first is 'subject', others are competitors), default for models, and context usage. This bridges the gap between raw schema and practical usage.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility'), clearly distinguishing it from sibling tools like ai_visibility_check. It explains the probe-and-rank process, making the purpose immediately clear.

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

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

The description provides explicit usage context ('competitive AI-marketing audits') and an example question. It implies the tool is for comparing multiple entities but does not explicitly state when to avoid using it or list 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?

Beyond annotations (readOnly, idempotent, non-destructive), it discloses partial failures, timing behavior ('bundlephobia's first measurement...can take 5-30s'), and the sources_failed field. 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?

Well-structured and front-loaded with a summary. Slightly verbose but every sentence adds value. Clear 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?

No output schema, but description thoroughly details return fields (summary block fields, per-advisory, links, alternative versions). Comprehensive for a complex tool.

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

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

Schema has 100% description coverage, so baseline is 3. Description adds nuance: mentions scoped packages are accepted and version defaults to latest. Adequate extra 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 it is a composite check for adding an npm package, covering safety, popularity, and size. It specifies the data sources (deps.dev and bundlephobia) and the output fields, distinguishing it from sibling tools like scan_competitor_ai_presence.

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

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

Explicitly states when to use: when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also notes ecosystem limitations (NPM only) and provides fallback guidance for other ecosystems.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds significant details: uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and returns character offsets. No contradiction with annotations.

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

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

Four sentences, front-loaded with the core purpose, followed by context and technical details. Every sentence is informative and necessary; no wasted words.

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

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

Despite no output schema, the description explains return format: 'top-N passages with character offsets and similarity scores,' which is sufficient. The tool's complexity is handled by the behavioral transparency section, and context signals are fully addressed.

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 value by explaining text max length (~200K chars), giving example queries, stating default limit (5), and describing the embedding-based search methodology, which clarifies how queries are processed.

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,' providing a specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded, making it clear this tool searches within provided text rather than fetching or grounding differently.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains that it 'saves context, returns only the passages that matter.' It also provides a clear alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by specifying that the type defaults to 'genomic' and that other forms (cdna, cds, protein) are available, which is beyond annotation scope. However, it doesn't discuss error handling or rate limits, but annotations cover safety.

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

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

The description is two sentences, front-loaded with concrete examples of natural language commands. Every sentence is informative and succinct, with no wasted words.

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

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

Given that an output schema exists (providing return type info), the description adequately covers input semantics and use cases. It doesn't explain pagination or performance, but for this tool it's appropriately 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 50% (type has description, id does not). The description compensates by explaining id is an Ensembl stable ID and type defaults to 'genomic', adding meaning beyond the schema. It clearly ties parameter usage to user intent phrases.

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 retrieves sequences by Ensembl stable ID, with specific verbs like 'sequence of [gene]' and 'FASTA for [Ensembl ID]'. It distinguishes itself from siblings by focusing solely on sequence retrieval, while siblings like 'variation' or 'homology' address other functions.

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

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

The description mentions use cases such as 'primer design, variant analysis, or downstream sequence tools', providing clear context. However, it lacks explicit guidance on when not to use this tool or alternatives, though the sibling names suggest other specialized tools.

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

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

Annotations indicate write, open-world, idempotent, non-destructive. The description adds context: requires OAuth, returns subscription id, delivery constraints (email, sms cap, webhook signing). No contradiction with annotations. Could mention idempotency implications.

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: purpose, requirements, type details, delivery channels. It is informative but somewhat lengthy; a few minor repetitions (e.g., phone verification mentioned twice) could be tightened.

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

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

Given 3 parameters, nested objects, and no output schema, the description covers input thoroughly. It explains types, parameters, and delivery options. The output is described as 'returns the new subscription id', which is sufficient but could detail the full return object.

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

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

Schema coverage is 100%, but the description adds significant value with concrete examples for each type and details on delivery channels (email validation, SMS verification, webhook HMAC signing). This goes beyond the schema's property descriptions.

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

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

The description states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly identifies the verb (create) and resource (subscription) and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explicitly requires a Pipeworx OAuth account, excluding anonymous/BYO users. It provides detailed usage for each subscription type with examples. However, it does not explicitly contrast with alternative monitoring tools among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful behavioral context: it returns categorized example questions with tool + argument shapes, and explains the effect of omitting or passing the topic argument. No contradictions.

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

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

The description is front-loaded with common user queries and is fairly comprehensive, but slightly verbose. However, every sentence contributes value; minor trimming could improve conciseness.

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

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

Despite no output schema, the description fully explains the return type (category-bucketed example questions with tool calls) and covers key usage patterns, making it complete for an onboarding tool.

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

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

Schema coverage is 100% and the description goes beyond by listing example values for the topic parameter ('finance', 'pharma', 'betting') and clearly stating the default behavior when omitted. This adds significant meaning.

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

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

The description clearly states the tool's purpose: to return example questions for onboarding a new agent. It uses specific verbs ('suggest', 'show', 'give ideas') and distinctively positions itself as the entry point, differentiating from siblings like ask_pipeworx and discover_tools.

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

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

The description explicitly advises when to use it ('FIRST when you do not yet know what Pipeworx can do for you') and provides context for focused queries via the topic parameter, effectively guiding the agent away from 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?

Description adds value beyond annotations by explaining 'row is deactivated (not deleted)' and impact on historical events. Annotations indicate non-destructive and idempotent; description clarifies the exact mutation 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?

Two sentences, no wasted words, purpose front-loaded. Highly concise and well-structured.

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

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

For a simple 1-param tool with annotations, description covers purpose, ownership, mutation behavior, and historical effects. Lacks return value info but acceptable.

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

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

Schema coverage is 100%, but description adds ownership context relating to the id parameter. Baseline 3, plus extra context justifies 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 states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'list_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?

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use. Lacks explicit alternatives but context is clear.

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

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

The description fully discloses the tool's behavior: it uses SEC EDGAR + XBRL, returns a verdict, structured form, actual value with citation, and percent delta. It also mentions idempotency and non-destructiveness. The annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with the description.

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 fairly concise for the amount of information it conveys, starting with example queries and then stating purpose. It could be slightly more streamlined, but it is well-structured and front-loaded with important cues.

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, no output schema), the description provides complete context: it explains the return value structure, the data source, and the tool's scope. The annotations also cover safety and behavior. The agent has all necessary information to use the tool correctly.

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

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

The single parameter 'claim' has 100% schema description coverage with a detailed description and examples. The tool description further contextualizes the parameter by specifying the claim types it supports (e.g., revenue, net income), adding 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's purpose: verifying natural-language claims against authoritative sources, specifically company-financial claims. It provides example query patterns ('Is it true that...', 'fact check') and distinguishes itself from siblings by noting it replaces multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the current scope (company-financial claims for public US companies). It does not explicitly state when not to use it 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotence. The description adds what fields are returned (alleles, location, etc.) but no additional behavioral traits. For a simple lookup, this is adequate but not exceptional.

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, focused paragraph: it front-loads natural language queries, states the action, lists return fields, and gives use cases. Every sentence adds value 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 has only 2 parameters, comprehensive annotations, and an output schema, the description is reasonably complete. It covers purpose, return content, and use cases. Minor omissions (e.g., species specification) are acceptable for a 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 50% (only variant_id has a description). The tool description provides an example with 'species' but does not explain the 'species' parameter (e.g., allowed values or default). It adds little beyond the schema; the description should compensate for the missing schema coverage but does not.

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

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

The description starts with common user queries, explicitly states it fetches a genetic variation record by ID (e.g., rs56116432), and lists return fields (alleles, genomic location, clinical significance, gene mappings). This clearly identifies the tool's purpose and distinguishes it from siblings like 'lookup_symbol' or 'vep'.

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 example use cases ('SNP lookups, pharmacogenomics, GWAS follow-up'), indicating when to use the tool. However, it does not explicitly state when not to use it or mention alternative tools (e.g., 'vep' for functional annotation), which would strengthen guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by detailing return contents (consequences, genes, predictions) and clarifying the prediction nature, which aligns with annotations. No contradictions.

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

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

The description is concise, front-loaded with natural language examples, and every sentence adds value. No redundant or vague language.

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

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

Given the presence of an output schema and annotations, the description adequately covers the tool's purpose, inputs, outputs, and use case. It is complete for an agent to understand 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 67%; description mentions 'region + allele' and species but does not deeply explain parameter syntax beyond the schema examples. It adds moderate context but relies on schema for details.

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 a Variant Effect Predictor, specifies inputs (region + allele) and outputs (consequences, genes, transcript impacts, SIFT/PolyPhen). It distinguishes itself from sibling tools like 'variation' by naming VEP and providing specific genomics context.

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

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

The description provides clear use context ('variant interpretation in clinical or research genomics') and example queries, but does not explicitly state when not to use it or compare with alternatives. The guidance is strong but lacks exclusion criteria.

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 the tool as read-only, non-destructive, idempotent, and open-world. The description adds that it returns cross-references from multiple databases (UniProt, RefSeq, etc.), which is useful context. However, it does not disclose additional behavioral traits like output structure or potential limitations, but given the annotations, the bar is lower.

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

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

The description is a single, well-structured sentence with examples in quotes, front-loading the most important information. Every word adds value, with no redundancy.

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

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

Given the output schema exists, the description adequately covers what the tool returns (external database IDs) and its purpose. It could mention that the output is a mapping of database names to IDs, but the output schema likely defines this. Overall, it is sufficiently complete for its complexity.

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

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

With 0% schema description coverage, the description must fully explain parameters. It implies 'symbol' is a gene symbol and that 'species' is needed (e.g., human), but does not explicitly define valid values or formats for species. The parameter semantics are partially inferred but not clearly documented.

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 external database IDs (cross-references) for a gene symbol, with specific examples like UniProt, HGNC, RefSeq. It distinguishes the tool's purpose of mapping between identifier spaces, though it does not explicitly differentiate from sibling tools like lookup_symbol or resolve_entity.

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

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

The description suggests using the tool 'to map between bio-database identifier spaces,' which implies the primary use case. However, it does not specify when not to use it or mention alternative tools for related tasks (e.g., lookup or homology), leaving the agent to infer from context.

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