Ensembl

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context: the default model is Workers AI (free), Anthropic calls require a BYO key and incur direct costs, and it returns a structured per-model result. This goes beyond the annotation baseline, though it doesn't address rate limits or latency.

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

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

The description is three well-structured sentences with the core purpose front-loaded. Details like the default model and cost implications are placed in parentheticals, and no sentences are wasted. It's dense yet easy to scan.

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?

There is no output schema, so the description appropriately explains the return shape: per-model {score, confidence, signals, raw_response} plus a combined view. It also covers model selection, costs, and use cases, making it fully contextual 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 coverage is 100%, so the baseline is 3. The description adds value by clarifying the default model, explaining that _apiKey enables Anthropic probing and that you pay Anthropic directly, and noting that context helps disambiguate common names. This supplements the schema without being redundant.

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

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

The description opens with a clear verb ('Probe') and resource ('one or more LLMs'), specifies the output (visibility score 0-100 per model), and adds concrete use cases (AI-marketing audits, pre-launch brand checks). This distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_presence by focusing on multi-model visibility scoring rather than Q&A.

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

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

It provides clear use-case context ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional Anthropic model ('pass _apiKey to also probe Anthropic'). However, it doesn't explicitly name alternatives or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already indicate read-only, idempotent, and open-world. The description adds that it routes to one of 5,563 tools, fills arguments, returns structured answers with stable citation URIs, and works on every tier with one fast call. No contradictions, though it could mention error handling or empty results.

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

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

The description is well-structured with front-loaded recommendation, clear functionality, usage guidelines, and sibling comparisons. It is somewhat verbose but every sentence adds value; no wasted content.

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

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

For a tool that routes to over 5,000 sources, the description covers purpose, usage, examples, and alternatives. No output schema exists, but the description hints at structured output with citations. Missing details on error states or limits, but still comprehensive.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. The description confirms natural language input and provides examples, but adds little beyond what the schema already conveys. 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 routes questions to a vast array of verified sources and returns structured answers with citations. It explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research, and provides a specific domain list.

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

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

The description explicitly tells when to use the tool (for factual questions, current/historical data) and when not to (for hallucination-resistant answers or broad multi-part questions, use ask_pipeworx_grounded or deep_research). It also provides concrete examples of user 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable context: it is a beta with candidate routing, currently no active candidate, and it 'falls back to nothing' indicating it is a full working router. 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 fairly concise and front-loaded with the key point 'Beta version'. It packs essential information about identity, state, and usage. A minor loss for wordiness (e.g., 'on outcome evidence 2026-07-26' could be simplified) 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 tool's complexity (a beta router over 5,563 tools), the description covers its current state, behavior, and relationship to the stable version. It mentions identical response shape, so no output schema is needed. It is reasonably complete for an agent to use it correctly.

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

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

Schema coverage is 100% with all parameters described in the schema. The description mentions 'same arguments' but does not add new meaning beyond what the schema provides for the single required parameter 'question' and its aliases. 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 this is a beta version of ask_pipeworx, an identical universal router with the same 5,563 tools and arguments. It explicitly distinguishes itself from the stable sibling by mentioning candidate routing improvements and the experimental nature.

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

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

It instructs to use this tool 'when you want the newest routing' and explains that results are compared against the stable router for decisions. It mentions that currently no candidate is active, so it matches ask_pipeworx. However, it does not explicitly state when to avoid it or prefer the stable version.

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 richly discloses behavior beyond the annotations. It explains the internal routing ('picks the right tool from 5,563 across 1462 sources, fills arguments, fetches the data—then EXTRACTS the answer using ONLY what the tool result contains'). It details exactly what is returned on success and failure, including the refusal reasons. The cost implication (extra LLM call) is disclosed. This fully satisfies the behavioral transparency requirement, going well beyond the annotation hints (readOnlyHint, etc.).

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

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

The description is structured well: starts with a clear one-sentence purpose, then elaborates on internal behavior, return format, and usage context. Every sentence provides unique value. It's slightly longer than ideal but justifiably so given the behavioral complexity. The mention of the extra cost vs. ask_pipeworx is relevant and well-placed. Score 4 for being appropriately sized for the content.

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 (self-routing, refusal logic, 5,563 tools, 1,462 sources) and the absence of an output schema, the description fully compensates by detailing the exact return shape and refusal reasons. It covers success fields (answer, evidence, confidence, source, fetched_at, refusal_reason:null) and failure reasons. With high schema coverage and this detailed behavioral disclosure, the description is complete for an AI to use safely.

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

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

Schema coverage is 100% with the description for the required 'question' parameter. The description adds value by explaining that the tool accepts question aliases (query, q, prompt, etc.), which is a deeper semantic than what the schema's descriptions indicate. However, the description does not elaborate on how the question should be formulated or constrained (e.g., length, scope), which might be helpful but isn't critical given the high schema coverage. Score 4 for meaningful addition.

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: 'Hallucination-resistant answer mode for high-stakes reads.' It distinguishes from the sibling ask_pipeworx by highlighting the grounded, refusal-capable behavior. The verb 'answer' with resource 'Pipeworx' is specific, and the contrast with ask_pipeworx is explicit.

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

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

The description provides explicit guidance on when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also states when to prefer the alternative: 'prefer ask_pipeworx for casual lookups,' with a cost justification (one extra LLM call). This is exemplary usage guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, but the description adds substantial behavioral context: resolver match confidence, low-confidence short-circuiting, closed-market statuses, wide-spread illiquidity warnings, news fallback retry behavior, and cancellation-rule risk parsing. This goes far beyond the annotation hints and provides actionable safety 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 long but exceptionally well-structured, with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.) that allow rapid scanning. Every section adds unique operational detail without redundancy, so the length is justified by the tool's complexity.

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

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

With no output schema provided, the description takes on full burden of explaining return values and does so thoroughly: result.market, result.analysis, result.evidence, market_match_score, parent_event, news fallback flags, and status codes. It also covers edge cases like closed markets, low-confidence matches, and cancellation rules, making it remarkably 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 descriptions cover all three parameters (market, depth, include_raw) with 100% coverage, so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema already explains; for example, it never mentions the depth or include_raw parameters explicitly, though the fan-out examples illustrate thorough mode implicitly.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' which clearly identifies the verb, resource, and methodology. It distinguishes itself from sibling tools by focusing on single-bet data fan-out and evidence synthesis, rather than broader scanning or arbitrage.

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

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

Explicit use cases are provided ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), and the classifier list gives concrete trigger categories. However, it does not explicitly name when NOT to use this tool or point to specific alternative sibling 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 declare read-only, idempotent, non-destructive behavior. The description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS, FDA), off-calendar fiscal year handling, sorting by primary metric, and return format with citation URIs. No contradiction.

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

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

Description is long but every sentence adds value: trigger phrases, capability, per-type details, sorting behavior, output format, and efficiency claim. No redundant filler, though dense enough to require careful reading.

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?

Even without an output schema, the description covers what is returned (paired data + citation URIs), sorting, and scope limits (2–5 entities, one call). It fully addresses the tool's complexity and likely usage scenarios.

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 meaningful enrichment: for type it explains the specific data pulled, and for values it gives examples (tickers/CIKs vs drug names). This goes beyond the bare schema definitions.

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

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

The description clearly states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with concrete examples of trigger phrases. It distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile.

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

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

Explicitly instructs to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities. It also describes what each type (company/drug) pulls, giving clear context for when to use which type.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral context: account requirements, paid depth tier, parallel decomposition, return structure (evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), second-hop iteration, semantic excerpting, and expected response times (15-90s). No contradictions with annotations; this is a model disclosure.

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 (~400 words) but every sentence adds value: front-loaded with critical account/fallback info, then purpose, then usage guidance, then detailed behavior. No redundancy. Could be slightly more structured (e.g., bullet points) but given complexity, the prose is well-organized.

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

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

Given 2 parameters, no output schema, and 37 sibling tools, this description is remarkably complete. It covers account prerequisites, fallback behavior, tool distinction, parameter details, return structure (gaps, contradictions, hop, citation), iteration semantics, time expectations, and limitations (not for breaking news). Leaves no critical gap for agent selection and invocation.

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

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

Schema covers 100% of parameters. Description adds meaning: explains 'depth' enum values with facet counts and capabilities (quick=3, standard=5+gap-recovery+contradictions, thorough=8+iterative+contradictions) and clarifies that 'question' should be broad/multi-part. This enhances what the schema provides.

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

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

The description clearly states it performs 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources in ONE call'. It distinguishes from siblings like ask_pipeworx (single lookup) and explains it decomposes questions into facets and routes to tools in parallel. The verb+resource+scope are specific and differentiated.

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

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

Explicitly tells when to use (broad/multi-part structured-data questions) and when not (single lookup -> ask_pipeworx; breaking/current news -> ask_pipeworx). Also addresses account requirements: free/paid plans and fallback tool if not signed in. Provides clear context and exclusions.

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

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

Annotations already mark the tool as readOnly, idempotent, non-destructive, so safety is covered. The description adds valuable behavioral detail: it returns top-N tools with 'names, descriptions, and full input schemas (with curated examples)' and notes 'each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations and helps the agent know what to expect.

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 then covers use case, return format, and a directive. The long list of data categories is somewhat verbose but serves to show the tool's coverage. Every sentence contributes, though the list could be trimmed without losing meaning.

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

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

Given there is no output schema, the description adequately explains what the tool returns and how to invoke it. It also provides clear usage context and practical guidance. It does not detail pagination or error cases, but for a discovery tool this is sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'top-N' which loosely relates to the 'limit' parameter, but it does not add parameter-specific syntax or alias explanations beyond what the schema already provides. Thus it meets but does not exceed the baseline.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It lists concrete domains (SEC filings, FDA drugs, etc.) and clarifies the tool's role as a discovery mechanism, distinguishing it from sibling tools that answer specific queries via the 'Call this FIRST... not just one answer' directive.

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

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

The description gives explicit when-to-use context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It contrasts with 'not just one answer' but does not name specific alternative tools, so it stops short of a full when-not/alternatives list.

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

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

Even though annotations already declare readOnly, openWorld, idempotent, and non-destructive, the description adds significant behavior: parallel fan-out across multiple sources, return fields, latest-10-K sorting, patent soft-fail due to API sunset, and GDELT→GNews fallback. This gives the agent a rich understanding of tool behavior beyond annotations.

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

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

The description is a single dense paragraph but is front-loaded with example queries and a clear value statement. Each detail in the return list is useful for a complex tool, though breaking it into labeled sections would improve scanability.

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

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

With no output schema, the description fully compensates by enumerating all returned components, listing caveats such as patent soft-fail, describing fallback behavior, and specifying input constraints. This is comprehensive for a read-only multi-source profile tool.

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

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

Schema coverage is 100% and both parameters are described in the schema, so the baseline is 3. The description adds extra value with concrete examples (AAPL, 0000320193), the requirement for zero-padded CIK, and the explicit statement that names are unsupported with a pointer to resolve_entity, going beyond what the schema provides.

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

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

The description opens with numerous concrete natural-language triggers and immediately states the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling single-purpose lookups by emphasizing the holistic, multi-source nature of the tool.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is requested, providing clear when-to-use guidance. It also states that names are not supported and directs users to resolve_entity when only a name is available, covering the key alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' is consistent and adds minimal extra behavioral context. It does add a note about 'sensitive data,' slightly enriching the safety profile, but doesn't go beyond what annotations convey overall.

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 only two sentences, front-loads the main action, and every phrase adds value—purpose, usage guidance, and sibling relationships—without any 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?

With only one parameter, complete schema coverage, and appropriate annotations, this simple tool is well-covered. The description explains when and why to use it and even identifies related tools, making it sufficiently complete 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?

The schema description coverage is 100%, and the 'key' parameter is fully documented as 'Memory key to delete.' The description adds no extra parameter-level detail, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb and resource: 'Delete a previously stored memory by key.' It also distinguishes itself from siblings by explicitly pairing with 'remember and recall,' making it evident that it is the inverse of remember.

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

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

The description provides explicit contexts for use: 'when context is stale, the task is done, or you want to clear sensitive data.' It mentions complementary tools (remember and recall) but does not explicitly state when not to use it, which keeps it at a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and clarifies output is a single text blob. This goes beyond the annotations without contradicting them.

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

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

The description is concise with a clear front-loaded statement of purpose, followed by process and use cases. Every sentence adds value. The 'Useful for' list is slightly verbose but acceptable, keeping it at a 4 rather than a 5.

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

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

For a simple two-parameter tool with strong annotations and a clear output format description, the description is complete enough. It explains what the tool does, when to use it, and what the result looks like. It lacks edge-case handling details (e.g., invalid URLs) but these are not essential for this low-complexity 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 the input schema fully documents both 'url' and 'max_links'. The description does not add parameter-specific details beyond what the schema provides, matching the baseline for full schema coverage.

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

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

The description clearly states the specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It distinguishes this tool from siblings by focusing on llms.txt generation, and briefly explains the process (fetches, extracts, emits), making the purpose unambiguous.

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

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

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'. However, it does not explicitly mention when not to use or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds that the tool returns both orthologs and paralogs, which clarifies the output type but does not elaborate on behavior like supported species or no-match handling. Given the annotations, this is adequate but not rich.

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

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

The description is concise and front-loaded with example queries, immediately conveying the tool's purpose. The second sentence adds use-case context without unnecessary elaboration. 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?

The tool has a simple input schema and an output schema (indicated in context), so the description mainly needs to convey purpose and use cases, which it does. It covers key scenarios like model organism work and evolution. However, it could mention what happens when target_species is omitted, but the schema's optionality handles that. Overall, sufficient for a query tool.

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

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

The input schema has three parameters with 0% coverage in the description. The examples illustrate usage with species, symbol_or_id, and target_species, but the description itself does not define each parameter's meaning or whether target_species is optional. More explicit parameter descriptions would be needed to compensate for the lack of schema descriptions.

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

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

The description clearly states it returns orthologs and paralogs for a gene across species, with specific example queries that show the tool's scope. This distinguishes it from sibling tools like lookup or sequence, which focus on different biological data. The mention of cross-species comparison and evolutionary analysis further clarifies its purpose.

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

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

The description explicitly says 'Use for cross-species comparison, model organism work, evolutionary analysis,' which provides clear context for when to select this tool. However, it does not mention exclusions or alternative tools, so it stops short of the highest score.

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, so the description is not required to restate those. It goes beyond annotations by clarifying the scope ('caller's active subscriptions') and explicitly listing the returned fields, which informs the agent about the output shape. It does not mention pagination or potential volume, but this is a minor gap given the annotations.

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

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

The description is two sentences: the first states the action and scope, the second lists return fields and provides usage guidance. Every sentence serves a purpose with no filler, and the most critical 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?

For a simple read-only list tool with one optional parameter, the description covers the function, output fields, and usage context. Combined with strong annotations and full schema coverage, it is complete enough 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?

Schema coverage is 100% and the only parameter, include_inactive, has a clear description in the schema. The tool description does not add extra meaning for this parameter, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also enumerates the returned fields, leaving no ambiguity about the tool's function.

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

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

It explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides direct context and contrasts with the actions of adding (subscribe) and cancelling (unsubscribe), serving as clear guidance among alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by specifying returned fields and explaining the effect of expand=true (e.g., transcripts of a gene, exons of a transcript). This goes beyond what annotations provide, though it doesn't discuss edge cases like versioning or errors.

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 slightly busy with multiple slash-separated query patterns, but every clause contributes useful information: what it fetches, return fields, expand behavior, and an example. It is front-loaded with the most important usage patterns and remains within a reasonable length.

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

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

For a simple 2-parameter tool with an output schema and full annotation coverage, the description is complete. It covers purpose, input patterns, expand behavior, and provides a concrete example. The return-value breakdown is redundant given the output schema, but the description is otherwise sufficient for correct invocation.

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

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

With 100% schema description coverage, both parameters are already documented. The description adds value by giving a concrete example (BRAF ENSG00000157764) and clarifying the expand semantics beyond the schema's 'Include child features' by specifying what child features are included. This enriches parameter understanding.

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

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

The description uses specific verbs ('fetch metadata') and a clear resource ('Ensembl stable ID') covering all four ID types (gene/transcript/exon/translation). It distinguishes from siblings like lookup_symbol (symbol-based) and sequence (sequence retrieval) by emphasizing stable ID metadata 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 provides query patterns ('Ensembl gene info for [ENSG...]', 'look up [Ensembl ID]', 'fetch [ENST.../ENSE.../ENSP...]') that clearly signal when to use the tool. It also explains when to use expand=true for child features. However, it does not explicitly name alternative tools or state when not to use this one.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, lowering the burden. The description adds value by specifying the exact return fields (Ensembl gene ID, chromosomal position, biotype, description), which provides 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 concise, starting with natural language examples, then a clear explanation, and a direct use-case sentence. Every sentence adds value, and there is no redundancy or fluff.

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

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

For a simple lookup tool with rich annotations and an output schema, the description is largely complete: it covers purpose, usage, and the main parameters. The only missing piece is the 'expand' parameter, but this does not prevent a user from successfully using the tool for its core 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 only 33%, so the description must compensate. It explains 'species' and 'symbol' with examples and clarifies 'symbol' is a gene symbol, but it does not explain the optional 'expand' parameter. The required parameters are well-covered, but the optional one is left undocumented, representing a clear gap.

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

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

The description clearly states the tool looks up a gene by symbol within a species and returns Ensembl IDs, chromosomal position, biotype, and description. It also explicitly names the conversion from HGNC symbols to Ensembl IDs, which distinguishes it from sibling tools like 'sequence' or 'variation'.

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 use cases ('Use to convert HGNC gene symbols to Ensembl IDs for genomics workflows') and includes example query phrasings. It does not explicitly mention when not to use it or name alternative tools, but the 'Use to' phrasing gives clear contextual 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 provide no behavioral hints beyond non-read-only, but the description discloses several important behaviors: rate limits (5 per identifier per day), free usage not counting against quota, anonymous filing returning a claim_token, the token's later use for status checks, and daily digest review cadence. This far exceeds the annotation baseline.

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

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

The description is dense but every sentence serves a purpose: purpose, use cases, exclusion, token mechanics, rate limits, and roadmap impact. It is front-loaded with the main verb and resource, and the structure flows logically from what/why to how/when.

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 feedback tool with no output schema, the description explains return behavior (claim_token, later status read), operational constraints (daily rate limit, quota exemption), and appropriate content (mention Pipeworx tools/packs, not end-user prompts). It covers all necessary context 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 the schema already documents each parameter. The description adds value by clarifying claim_token usage (pass it back to read resolution status) and by instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts. This is meaningful extra semantics 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 opens with a specific, action-oriented purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly identifies the verb+resource and immediately distinguishes this feedback tool from the many sibling research/lookup 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?

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and an explicit when-not-to-use with a concrete alternative: if the tool came from a different MCP server, file it with that server instead. It even offers a heuristic for identifying Pipeworx tools. This is model-level 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, non-destructive. The description adds valuable context beyond that: caching behavior (5min-1h), data lineage ('derived from CF analytics-engine'), privacy ('no PII'), and output structure ('just (pack, tool, count)'). This fully discloses what the agent should expect.

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: it opens with a hook ('What other AI agents are calling on Pipeworx right now'), then states outputs, lists practical use cases, and ends with data/behavior notes. Every sentence serves a purpose with no redundancy or fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, use cases, output shape, caching, and privacy. It provides enough detail for an agent to know exactly what to expect and how to leverage the tool, making it complete.

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

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

Schema description coverage is 100% for the single 'window' parameter, and the schema already explains enum values and trade-offs. The tool description reinforces the concept but doesn't add new parameter semantics beyond what the schema provides, 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's function with a specific verb ('Returns') and resource ('top tools, top packs, and total call volume'). It distinguishes itself from siblings like ask_pipeworx by focusing on aggregate trends rather than answering questions, and even notes it's a 'self-aggregating signal'.

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 three explicit use cases: discovering hot data sources, confirming canonical tool choices, and checking alignment with other agents. It also explains how window choices affect results ('shorter windows surface what's hot right now; longer windows show steady-state demand'), giving clear guidance on when to use the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral detail beyond that: the 3pp threshold for partition signals, the Jaccard similarity anchor for cross-event pairs, placeholder filtering with >20% threshold, and the fill check against live CLOB depth with explicit trading advice. This is a rich behavioral disclosure.

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

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

The description is long but well-structured with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the purpose and call modes. Some redundancy exists (e.g., the fill check is described twice), but every major section adds operational context. It is dense yet organized.

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

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

The tool is complex with no output schema, but the description thoroughly covers the response shape (opportunities[], partition_check fields), edge cases (placeholders, low similarity), and the critical fill-check behavior. It even references a sibling for custom sizing. This is a complete standalone description for an agent to correctly invoke the tool.

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

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

Schema coverage is 100% and both parameters have descriptions, but the tool description elevates semantics by explaining the two modes in depth. It gives concrete examples of event slugs and topic seed questions, explains how the tool behaves differently in each mode, and clarifies when to prefer one over the other. This goes well beyond what the schema entries provide.

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

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

The description opens with a specific verb+resource: "Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks." It clearly distinguishes this from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection and listing the three calling modes.

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

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

Explicit guidance is given for when to use each mode: "Call with NO args for a trending_scan... pass event... or topic..." It recommends event for a known market and explains when cross-event scan is better. It also names an alternative sibling: "For custom sizing use polymarket_fill_risk." This gives clear when-to-use and when-not-to-use context.

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

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

The description adds extensive context beyond the annotations: it details the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), the response structure (by_segment, fed_candidates, _diagnostics), the meaning of edge_pp_net, kelly_fraction, and even the 24h-move warning. It also explains why segments may be empty and caching behavior. This is far beyond what readOnlyHint conveys.

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

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

The description is long and dense, but each sentence carries specific information. It is front-loaded with the purpose and organized by categories (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, knobs, response). While it uses all-caps and no line breaks, the structure is mostly logical. Some redundancy exists (e.g., 'TRADEABLE-EDGE KNOBS') but overall it earns its length for a complex tool.

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

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

With no output schema, the description fully specifies the response top-level structure, including by_segment, fed_candidates/fed_note, and _diagnostics. It also explains the fields on each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.) and the conditions for empty segments. Given the complexity (9 parameters, multiple model families, filters), this description is remarkably complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by explaining the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and how they drop opportunities. It also explains the logic behind slippage_pp and the interaction between min_kelly and min_partition_leg_kelly. It doesn't describe all parameters in the description, but the schema already covers them.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly differentiates it from siblings like polymarket_arbitrage (focused on arbitrage) or polymarket_fill_risk (focused on execution risk). It also states the intended use case: 'what should I bet on today'.

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

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

The description clearly implies when to use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also includes exclusion notes (e.g., Fed bets excluded due to unreliability). However, it does not explicitly name alternative tools for different scenarios, so it lacks explicit when-not-to-use guidance.

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

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

The description provides rich behavioral context beyond the readOnlyHint and idempotentHint annotations: snapshot TTL, cache-miss write behavior, data gaps, computation of decay from daily closes, and the sign convention for edge_pp_net. It also explains the limitation of history depth and snapshot start time. No contradiction with annotations; it enhances them.

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

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

The description is well-structured with labeled sections (Args, RESPONSE, LIMITS) and front-loaded purpose. Despite being fairly long, every sentence adds essential information about behavior, response fields, or limitations. No fluff or redundant content.

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 thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and key fields (trend, decay_pp_per_day, lifespan_days). It also covers edge cases like data gaps, snapshot TTL, and computation methodology. The tool's complexity is 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?

The schema already covers both parameters with clear descriptions (days lookback with default and clamp, window family with options). The description adds 'lookback' and 'snapshot family' semantics, which is marginal reinforcement, and even introduces a slightly contradictory 'max 30' vs schema's 'clamp 2-30'. With 100% schema coverage, the baseline of 3 is appropriate; the description does not significantly compensate.

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

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

The description clearly defines the tool as edge persistence and decay telemetry built from daily polymarket_edges snapshots, answering a specific question about edge age and shrinkage. It distinguishes itself from the sibling polymarket_edges by focusing on historical persistence and decay rather than current edges. The purpose is specific and unambiguous.

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

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

The description implies the tool is for analyzing edge history and decay, contrasting a fresh edge with an old one to justify its utility. It does not explicitly name sibling tools or state when not to use it, but the context of snapshots and the competition clock strongly implies the intended use case. Clear context without formal exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral context beyond these: it requires one of two mutually exclusive parameters, walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), and highlights forced_directional_risk for basket mode. This enriches the agent's understanding of side effects and failure modes.

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

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

The description is long but well-structured: it starts with a one-line purpose, then details single-market mode, basket mode, and usage guidance. Every sentence provides necessary information for a complex tool with two modes. It could be slightly more concise (e.g., splitting into bullet points), but the density is purposeful and 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 complexity (4 parameters, no output schema, no nested objects), the description is remarkably complete. It explains return values for both modes, parameter behavior, risk factors (thin_legs, forced_directional_risk), and concrete usage thresholds. There is no ambiguity about what the tool does or what it returns.

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 each parameter described, but the description goes further by explaining mode-specific interpretations: size_usd means 'max spend on buys, target proceeds on sells' in single-market mode but 'settlement notional S (shares per leg)' in basket mode. It also clarifies defaults ('default buy_yes', 'default auto from partition sum') and clamps (10–1,000,000), 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 opens with a specific verb+resource phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the tool from related siblings like polymarket_arbitrage by focusing on fill-risk assessment rather than signal generation. The two modes (single-market and basket) are explicitly named and contrasted.

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

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

The description provides explicit usage direction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial fills create unhedged directional positions), which tells the agent when this tool is necessary and what alternatives exist.

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

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

The description discloses extensive behavior beyond annotations: response structure (leg-by-leg prices, spread array), the meaning of compatibility_warning with two distinct trigger conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It also explains that real cross-venue spreads are rare, adding a crucial honesty layer. No contradiction with annotations.

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

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

The description is dense and long, but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose and uses the length to convey essential operational caveats. Slightly verbose in the final warning, but each sentence contributes meaning.

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

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

With no output schema, the description takes on the burden of explaining return values and edge cases. It documents the response format, key safety fields, and failure modes, plus the current reliability of topic shortcuts. This is sufficient for an agent to set expectations and decide invocation.

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

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

Schema already covers 100% of parameters with descriptions and examples. The tool description adds value by explaining how the parameters interact (topic vs. explicit overrides), what the shortcut list contains, and the purpose of each mode. This goes beyond a simple schema listing.

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

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

The description opens with a specific verb+resource pairing: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling tools by emphasizing cross-venue comparison and enumerates two distinct operational modes (topic shortcuts and explicit pairing).

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

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

The description provides clear context on when to use each mode: topic shortcuts for pre-mapped macro events, explicit ticker/slug for custom pairings. It also warns that most pre-mapped topics currently return compatibility_warning, advising the agent to treat pre-mapped as not necessarily tradeable. However, it doesn't explicitly contrast this tool with sibling alternatives 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 already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds non-redundant behavioral context: scoping to 'anonymous IP, BYO key hash, or account ID' and the list-all behavior when the key is omitted. 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 three sentences, each earning its place: the first defines the action, the second gives a use case and examples, and the third explains scoping and relationship to sibling tools. It is front-loaded with the primary operation and contains no filler.

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

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

For a simple tool with one optional parameter, no output schema, and safety annotations, the description provides complete context: purpose, usage scenarios, data scoping, and how it fits with remember and forget. The agent has enough information to invoke it correctly without additional clarification.

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

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

The schema already describes the only parameter ('key' with 'Memory key to retrieve (omit to list all keys)'), giving 100% coverage. The description enriches this by providing concrete examples of key values (user's target ticker, address, prior research notes) and reinforcing the omit-to-list behavior, which adds practical 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 dual purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the resource (memory values) and directly distinguishes from siblings by referencing remember (save) and forget (delete).

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

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

It explains when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also provides lifecycle guidance by pairing with 'remember to save, forget to delete.' It does not explicitly mention alternatives like lookup or search_within, but the contextual use case 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 states that setting mark_read:true flags events as read, which is a state-modifying behavior. This directly contradicts the readOnlyHint annotation that claims the tool is read-only. This is a serious inconsistency.

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

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

The description is three sentences, front-loaded with purpose, and each sentence adds useful information. The mention of the HTTP endpoint is relevant for scripts/dashboards and 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?

For a tool with no output schema and 5 optional parameters, the description adequately covers return payload elements (source, citation_uri, raw payload), filtering, mark_read semantics, and polling suitability. It leaves limit and unread_only to the schema, which is 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?

The schema already provides complete descriptions for all 5 parameters. The description adds meaningful value by giving a concrete type example ("sec_8k") and explaining the consequence of mark_read ("the next call only shows newer ones"), which goes beyond the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed, using a specific verb and resource. It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on the alert feed and its polling 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?

Provides clear context for use: polling, filtering by type and since, and the mark_read side effect. It also offers an alternative access method via HTTP endpoint. However, it does not explicitly exclude scenarios or name sibling alternatives, so it stops short of a 5.

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

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

Despite annotations already declaring readOnly/openWorld/idempotent, the description adds substantial behavioral detail: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-failure due to API sunset, accepted since formats, and return structure (changes[] grouped by source, total_changes, pipeworx:// 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 dense but every clause earns its place, starting with relatable query examples then moving to source behavior, since syntax, return shape, and alternative tool. No filler or redundant restatement of the title.

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 there is no output schema, the description fully covers return values (structured changes[] grouped by source, total_changes, citation URIs). It also documents data-source caveats (PatentsView sunset), fallback logic, and the parameter range, making the tool usable without additional lookups.

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%, and the description largely repeats schema details (ISO or relative since, ticker or CIK, type only company). It adds a minor recommendation ('Use 30d or 1m for typical monitoring') and contextualizes how since affects sources, but does not significantly deepen parameter semantics 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 opens with concrete user phrasings and defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call,' then names the exact sources fanned out to. It explicitly contrasts with entity_profile ('Use entity_profile instead when you want the static profile'), so it distinguishes from a major sibling tool.

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

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

It provides clear use-case triggers ('What's new with X', 'latest on Y') and gives an explicit when-to-use-alternative rule: use entity_profile for static profile regardless of window. It also documents fallback behavior (GDELT preferred, GNews when rate-limited or 5xx) and a soft-fail caveat for USPTO, giving agents enough context 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?

Beyond annotations (idempotentHint, destructiveHint), it adds key behavioral details: key-value scoping by identifier, persistence differences between authenticated and anonymous sessions, and pairing with recall/forget. 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, each earning its place: purpose, when to use, storage behavior, and sibling tools. Front-loaded with the core action 'Save data'.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage, storage, persistence, and relationships to recall and forget. Nothing important is missing.

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 scoping context ('key-value pair scoped by your identifier') and examples, but these are largely redundant with the schema's own field 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 saves data for reuse later, with specific examples (ticker, address, preference). It distinguishes from siblings by explicitly pairing with 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 says 'Use when you discover something worth carrying forward' and provides concrete use cases. It also tells how to retrieve (recall) and delete (forget), giving clear context and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical behavioral context: 'Each call cascades through several lookup endpoints internally,' graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), and explicit treatment of unresolved identifiers. This goes far beyond what annotations provide.

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

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

The description is relatively long but well-structured and front-loaded with example queries. Every sentence adds value—detailing supported identifiers, fallback behavior, and output conventions. While it could be trimmed slightly, the density of information justifies the length.

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

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

Given the tool's complexity (multi-source entity resolution, graceful degradation, multiple identifier types), the description covers the key aspects: input acceptance, identifier sources, failure handling, and that it replaces 2-3 lookups. Without an output schema, the description explains what is returned (identifiers with source labels, unresolved stated explicitly). A minor gap is not describing the exact response structure, but overall it is highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial meaning: for 'type' it details what each entity type returns (company: CIK+ticker+LEI+FIGI; drug: RxCUI+ingredient+brand). For 'value' it lists accepted inputs (ticker, CIK, ISIN, name for company; brand/generic for drug) and explains behavior like ISIN resolving to legal entity via GLEIF. This enriches the schema significantly.

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

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

The description opens with concrete example queries ('What's the ticker for...' / 'find the CIK for...') and explicitly states: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from siblings by specifying supported types ('company', 'drug') and noting it replaces 2-3 manual lookups.

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

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

The description provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also gives numerous example phrasings that trigger this tool. While it does not explicitly exclude siblings like 'lookup_symbol', the context is sufficiently clear for correct tool selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context beyond that: it internally calls ai_visibility_check for each entity, ranks results by score, and returns a ranked list with specific fields (score, confidence, signal density). This gives an agent a clear picture of side effects (none) and output structure that annotations do not convey.

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 tightly written sentences, each earning its place. The first sentence states the core action, the second explains the mechanism, the third gives a concrete use case, and the fourth specifies the return fields. No fluff or repetition.

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

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

The tool has moderate complexity (multi-entity probing, ranking) and no output schema, so the description compensates by disclosing return fields. It does not mention error handling, rate limits, or how the score is calculated, but given the strong annotations and full schema coverage, this is sufficient for selection and invocation. Slightly more detail on the relationship to ai_visibility_check would have pushed it to 5.

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 all 4 parameters are fully documented in the schema. The description does not add parameter-level meaning beyond what the schema already states (e.g., 'entities' array, first entry as subject). Baseline 3 is appropriate because the schema carries the burden.

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

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

The description opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes itself from single-entity tools by stating it probes each entity and ranks them, and the competitive angle is explicit ('your brand + N competitors'). The example question reinforces the purpose.

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

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

Provides clear context: 'Useful for competitive AI-marketing audits' and gives an example use case. It implies this is for multi-entity comparison rather than a single check, but does not explicitly name alternatives or state when not to use it. No exclusions are given, so it earns a 4.

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

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

The description discloses significant behavior beyond annotations: it fans out across two external services, returns a specific summary block with field names, includes per-advisory details and alternative versions, and explains partial-failure behavior with a concrete timing constraint ('bundlephobia's first measurement can take 5-30s; sources_failed will list it if it times out'). This exceeds the safety hints provided 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?

The description is dense but every sentence earns its place: purpose, usage context, return format, ecosystem scope, and failure-handling are each covered in separate, well-structured sentences. It front-loads the core purpose and avoids fluff. Five sentences is appropriate for a composite tool of this complexity.

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

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

With no output schema, the description must convey return values, and it does: it lists the summary fields, per-advisory detail, links, and alternative versions. It also covers limitations (NPM-only), timing, and graceful degradation, making it complete for an agent to understand what to expect and how to handle edge cases.

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

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

The input schema already covers both parameters with clear descriptions (package name, version with default behavior), and schema description coverage is 100%. The description adds context around what the tool returns but does not materially enrich the meaning of the parameters beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description opens with a specific, concrete purpose: 'Composite "should I add this npm package to my project" check in ONE call'. It clearly identifies the resource (npm package) and the action (scan/evaluate), and immediately differentiates itself from siblings by naming the composite data sources (deps.dev, bundlephobia). It also explicitly scopes to 'NPM ecosystem only in v1', making it distinct from broader tools like deep_research.

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

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

The description gives explicit usage triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides a clear exclusion/alternative for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), telling the agent when NOT to use this tool and what to use instead.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the embedding model (BGE-base-en), the retrieval method (cosine over 500-char overlapping windows), and the hard 200K char cap with truncation-flag behavior. This is exactly the kind of implementation detail that helps an agent reason about input limits and result quality.

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

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

The description is compact but information-dense: a one-sentence purpose, a usage rationale, a sibling pairing, and a technical behavior clause. Every sentence serves a distinct role with no padding or repetition.

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

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

Even without an output schema, the description specifies what the agent gets back: 'top-N passages with character offsets and similarity scores.' It covers input constraints, output shape, and failure behavior (truncation flag), making the tool fully usable from the description alone.

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 the baseline is 3. The description adds value by giving concrete example queries ('supply-chain risk', 'fiscal year 2024 revenue') and clarifying that 'text' is the already-fetched record content. It also reinforces the limit defaults and the top-N passage output, going slightly beyond the schema's bare 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 opens with 'Semantic search INSIDE a fetched record' — a specific verb, resource, and clear scope. It explicitly contrasts with ask_pipeworx_grounded, telling the agent this is the tool for searching within text you've already pulled, not for grounding over a whole document.

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

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

The description says 'Use when the record is too big to cram into the prompt' and explains that it 'saves context, returns only the passages that matter.' It also names a sibling tool (ask_pipeworx_grounded) and describes the intended pairing, giving 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?

Beyond the readOnly/idempotent annotations, the description reveals that the type defaults to 'genomic' and that 'cdna', 'cds', or 'protein' must be passed for processed forms. This adds useful behavioral context 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?

The description is two sentences and front-loaded with examples. The first sentence is dense but efficient, noting the default type and alternatives. No wasted words, though structure could be slightly clearer.

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 annotations indicating a safe read operation and an output schema present, the description covers defaults, input types, and use cases. It is complete enough for straightforward sequence retrieval without over-explaining.

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

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

The schema only describes the type parameter, leaving 'id' underdocumented. The description clarifies that 'id' is an Ensembl stable ID (gene or transcript) and explains the valid type values and default, effectively compensating for the 50% schema coverage.

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

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

The description explicitly states the tool retrieves DNA/cDNA/CDS/protein sequences by Ensembl stable ID, with concrete example queries. This distinguishes it from sibling tools like lookup or variation, making its purpose unmistakable.

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

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

It provides clear use cases ('primer design, variant analysis, or downstream sequence tools') and explains the default type behavior. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

The description adds significant behavioral context beyond the annotations: account requirements, the always-on feed, phone verification and SMS caps, the one-time webhook secret return, and auto-disable after 10 failures. These details are relevant to how the subscription behaves after creation, and there is no contradiction with 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 long but front-loaded with the core purpose and return value in the first sentence. The length is justified by the tool's complexity—five subscription types and three delivery channels—and every sentence contributes either constraints or examples, though it could still 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 the complex nested schema and no output schema, the description does a good job covering return values (subscription id, one-time webhook secret), account prerequisites, delivery mechanics, and failure behavior. It is nearly complete, with only minor details like explicit idempotency semantics left to the annotations.

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

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

The input schema already describes all parameters in detail with type-specific schemas, so the baseline contribution is high. The description supplements this with concrete and clarifying examples (e.g., items:['5.02'], topic:'fed', series_id:'UNRATE') and delivery constraints like phone verification, which adds practical 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 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns the new subscription id. This distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action and its 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?

It provides explicit context for when this tool should be used, including the requirement for a Pipeworx OAuth account and the note that anonymous/BYO cannot persist subscriptions. It also gives per-type usage examples, but it does not explicitly name alternative tools or contrast with them.

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, and the description adds the return format (bucketed example questions with tool+argument shapes) and mentions the live catalog, which implies dynamic content. No contradictions with annotations.

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

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

The description is a single detailed paragraph with front-loaded usage examples and clear separation of purpose, output, parameter usage, and when-to-use. It is longer than necessary but every sentence contributes value.

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

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

For a simple one-parameter tool with no output schema, the description fully explains the return value and the two invocation modes (full spread vs. focused topic), and the annotations cover safety. No gaps remain.

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

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

The schema already covers the topic parameter with a description listing valid values and the omission behavior, achieving 100% coverage. The description only repeats the same examples, adding no new 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?

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape, distinguishing it from sibling tools like discover_tools and ask_pipeworx.

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 directs the agent to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions passing a topic to focus, providing clear when-to-use context. It does not explicitly contrast with alternative discovery tools like discover_tools, so it falls short of a 5.

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

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

The description discloses key behaviors beyond annotations: ownership enforcement, deactivation instead of deletion, and the impact on historical events (still accessible via recent_alerts). This complements the annotations (idempotentHint=true, destructiveHint=false) and adds value beyond the structured metadata.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds essential information (what it does, ownership, deactivation behavior, historical availability). There is no redundant information or padding.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, side effects, and behavior. It doesn't mention the response format (e.g., success indication), but given the low complexity and the presence of helpful annotations, the description is sufficiently complete for correct invocation.

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

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

The input schema already provides 100% parameter coverage with a clear description ('Subscription id (uuid) returned by subscribe'). The description only repeats 'by id' and adds no additional semantic detail about the parameter itself, so the baseline of 3 applies.

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

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

The description opens with a specific verb ('Cancel') and resource ('subscription') and specifies the identifier ('by id'). This clearly distinguishes it from sibling tools like subscribe (create) and list_subscriptions (list), providing unambiguous purpose.

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

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

The description gives clear context: ownership is enforced (only your own subscriptions) and mentions that historical events remain available via recent_alerts. It doesn't explicitly say 'use this when...' or name alternatives for cancellation, but the ownership restriction and the note about recent_alerts provide practical usage guidance.

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

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

Annotations already mark it readOnly and non-destructive, but the description adds critical context: the meaning of 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source found). It also discloses the routing behavior and the return of verdict, evidence, and reasoning, which goes 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 longer than average but well-structured: front-loaded with trigger phrases, then purpose, routing, outcome meanings, and efficiency gains. Each sentence adds necessary information for a complex tool, though some redundancy exists (e.g., 'grounded pipeline' explanation).

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

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

With no output schema, the description fully covers the return values: verdict enum, actual value with citation, reasoning, and special handling for 'could_not_verify' and 'unsupported'. It also explains the two routing paths and the efficiency benefit, making it complete for an AI agent to select and invoke correctly.

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

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

Both parameters are fully described in the input schema (100% coverage), so the baseline is 3. The description's example for 'claim' adds a concrete illustration, and 'tolerance_pct' is already well-defined in the schema. No additional parameter-level semantics are provided in the 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 explicitly states the tool performs 'natural-language claim verification against authoritative sources' with clear trigger phrases ('is it true that...', 'fact check'). It distinguishes two execution paths (SEC EDGAR fast path vs grounded pipeline) and differentiates from sibling tools by focusing on verifying factual claims.

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

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

It gives explicit guidance to 'use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing for company-financial vs other claims. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds value by revealing the output content (alleles, location, clinical significance, gene mappings), which helps the agent set expectations but stops short of deeper caveats like data availability or versioning.

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

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

Two sentences, front-loaded with trigger phrases and examples. Every sentence adds meaning: first defines purpose, second lists returns and use cases. No redundancy or filler.

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

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

Given the tool's simplicity (2 required params, rich annotations, output schema present), the description is complete. It covers purpose, usage scenarios, and output contents, and it leverages annotations and output schema for the rest. No critical information is missing.

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%: variant_id has a description (e.g., 'rs56116432') and species has none. The description reinforces variant_id semantics through examples but does not explain species values or required format. The schema example shows 'human' but the description itself adds little beyond that. This partially compensates but leaves a gap for the required species parameter.

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

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

The description clearly states the tool fetches a genetic variation record by ID, with specific examples like 'What is [rsID]' and 'look up SNP [rs...]'. It also lists return fields (alleles, genomic location, clinical significance, gene mappings), distinguishing it from sibling tools like sequence or homology. The verb-resource pair is specific and unambiguous.

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

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

The description explicitly says 'Use for SNP lookups, pharmacogenomics, GWAS follow-up', providing clear context for when to invoke this tool. It does not mention alternatives or exclusions, so it falls short of a 5, but the guidance is sufficient for typical use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing what the tool returns (consequences, affected genes, transcript impacts, SIFT/PolyPhen predictions) without contradicting the annotations. It does not mention rate limits or auth needs, but these are not critical for a read-only, idempotent operation.

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

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

The description is concise and well-structured, opening with user-style queries, then a single-sentence technical summary, followed by the intended usage. Every sentence contributes meaningful information without redundancy. It is front-loaded with the most important information (what the tool does and how to invoke it).

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, the description is not required to enumerate return fields in detail, but it still provides a helpful summary of typical results (consequences, genes, SIFT/PolyPhen). It is complete enough for a read-only variant interpretation tool. It could have mentioned the species parameter more prominently, but the overall context is adequate.

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

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

The schema covers 67% of parameters (region and allele have examples, species has none). The description adds meaning by explaining that 'region + allele' constitute the genomic change to predict consequences for, but it fails to mention 'species' as a required parameter, leaving that parameter semantically underdescribed. The description does not fully compensate for the missing species 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 identifies a specific verb+resource combination: 'predict consequences of [genomic change]' via the Variant Effect Predictor. It lists concrete outputs (missense, synonymous, splice, SIFT/PolyPhen) and distinguishes this from general variant lookup by focusing on consequence prediction, setting it apart from sibling tools like 'variation'.

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

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

Provides clear usage context: 'Use for variant interpretation in clinical or research genomics.' It also gives example query phrasings to signal the intended input style. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description only mentions that external database IDs are returned, which is essentially the output rather than a behavioral trait. No additional behaviors (e.g., rate limits, disambiguation rules) are disclosed beyond the annotations.

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

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

The description is concise, front-loads the purpose with example queries, and contains no wasted words. It conveys the essential information in three short sentences, making it highly efficient.

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

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

The tool is relatively simple, and annotations plus output schema cover safety and return structure. However, the description omits explanation of the required 'species' parameter and does not clarify whether it is a free-form string or uses a controlled vocabulary. This gap makes the description not fully complete for correct invocation without further inference.

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

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

The input schema has no descriptions for the two required parameters (symbol, species), and the description only elaborates on 'symbol' as a gene symbol via examples. The 'species' parameter is not explained at all, leaving the agent to infer its purpose. With 0% schema description coverage, the description fails to fully compensate for the missing parameter semantics.

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

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

The description clearly identifies the tool as providing cross-references (external database IDs) for a gene symbol, with specific example queries. It specifies the verb 'cross-references' and the resource (gene symbol), and the scope of mapping between bio-database identifier spaces distinguishes it from sibling tools like lookup_symbol or sequence.

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

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

The description states 'Use to map between bio-database identifier spaces,' which provides clear context on when to use the tool. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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