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?

It clearly discloses behavior beyond the readOnly/idempotent annotations: it is an automatic router, it fills arguments internally, and it returns structured answers with stable pipeworx:// citation URIs. Nothing contradicts the annotations, and the citation behavior is valuable context for trusting and using the result.

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 most important routing decision and is information-dense throughout. It loses one point for length and some redundancy: the trigger-phrase/examples section partly overlaps the opening domain list, and 'START HERE for most questions' restates the opening preference.

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 broad router with a single-required-parameter schema and no output schema, the description covers what is needed: what kinds of questions to ask, what the tool does internally, and what form the answer takes (structured with citation URIs). It also covers edge routing for complex, symbol-normalizing, and local 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?

Schema coverage is 100% and every parameter is described as an alias for the single natural-language `question` parameter, so the description does not need to add semantic detail. It adds only illustrative examples rather than new parameter meaning, matching the baseline for fully covered schemas.

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 names a specific action and resource: it takes natural-language questions and routes them to the right tool among thousands of verified sources, returning cited structured answers. It also separates itself from siblings by naming deep_research, ask_pipeworx_grounded, and lookup as alternatives, so an agent can distinguish this tool from them.

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

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

There is explicit selection guidance: 'PREFER OVER WEB SEARCH', trigger phrases ('what is', 'look up', 'current'), and explicit when-not-to-use conditions with named alternatives for complex multi-part questions, symbol-heavy questions, and local/on-device lookups. This leaves little to inference.

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 read-only, idempotent, open-world, and non-destructive. The description adds meaningful context: identical arguments and response shape to ask_pipeworx, live candidate routing only when a candidate is under test, current parity due to no active candidate, and that it is a full working router rather than a fallback. There is no contradiction with annotations.

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

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

The description is compact and front-loaded with identity, current status, and usage guidance. Details like '5,798 tools', the retirement date, and 'falls back to nothing' add useful specificity but are slightly more granular than strictly necessary. Overall, every sentence contributes.

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, but the description states 'same response shape' as ask_pipeworx, which is sufficient for an agent that understands the stable sibling. Input parameters are fully covered by the schema, and the description explains current behavior and experimental purpose. It does not enumerate the underlying tools, but that information is not required 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 schema provides 100% parameter description coverage, including aliases for q, text, input, query, and prompt, plus a full description of question. The tool description only says 'same arguments' and adds no parameter-specific meaning. Since the schema already documents parameters thoroughly, a 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 identifies the tool as a 'Beta version of ask_pipeworx' and a 'universal router', clearly anchoring it to the stable sibling. It distinguishes it from ask_pipeworx and ask_pipeworx_grounded by its experimental routing status and explicit use case ('when you want the newest routing'). However, because it currently behaves identically to ask_pipeworx, its standalone purpose is defined mostly by contrast rather than a direct 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?

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing', giving a clear condition and referencing the stable alternative. It also explains that results are compared against the stable router to decide merges. It does not explicitly state when not to use it, though 'beta' and 'experimental edge' imply caution.

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 description adds substantial behavioral context: it fills arguments internally, extracts only from fetched data, returns evidence as a verbatim quote, and refuses with specific refusal_reason values when data does not directly answer. This goes well beyond the annotation hints and matches 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 dense but every sentence earns its place: core guarantee, routing behavior, structured success/refusal outputs, usage context, and cost tradeoff. The key differentiator 'hallucination-resistant' 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 tool with no output schema, the description fully explains success shape, failure/refusal shape, refusal reasons, source of evidence, cost implication, and when to use it versus the sibling. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%: all six parameters are aliases for 'question', and the schema itself documents natural-language usage. The tool description adds no new parameter-level detail, so the baseline 3 is appropriate.

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

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

Description states a specific verb+resource: a 'hallucination-resistant answer mode' that routes like ask_pipeworx but extracts answers only from tool results. It clearly distinguishes itself from ask_pipeworx by the grounded answer guarantee and return format.

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

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

Explicitly says when to use: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete domains listed. It also gives exclusion guidance: prefer ask_pipeworx for casual lookups because this costs an extra LLM call.

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

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

Annotations already 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?

The annotations already cover readOnly/openWorld/idempotent, and the description adds substantial behavioral context: account and paywall requirements, parallel decomposition across 5,798 tools, explicit gaps[] with a 'never invented' guarantee, resolvable citation_uri, contradictions[], semantic excerpting, and latency expectations. There is no annotation contradiction.

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

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

The description is long but every sentence contributes a distinct behavioral fact, organized from auth and capability to use cases, return details, and latency. Minor redundancy with the input schema—such as repeating depth hop behavior and the paid thorough plan—keeps it from a perfect score.

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

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

With no output schema, the description provides a strong return contract: findings packet fields, gaps[], contradictions[], hop, citation_uri, and excerpting behavior. It also covers prerequisites, alternatives, source scope, and latency, so an agent has the information needed to invoke the tool and interpret results.

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

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

Schema description coverage is 100%, and the input schema already documents both the question parameter and the depth enum with facet counts, hop behavior, and the paid thorough tier. The description adds latency expectations and a little depth-related prose, but mostly restates what the schema already provides, so it stays at the high-coverage 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 names a specific action: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call.' It explicitly says what the tool is not ('NOT open-web search') and distinguishes it from ask_pipeworx, so an agent can tell this apart from siblings without opening the schema.

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 an explicit best-use case ('Best for broad/multi-part questions over structured data') with concrete examples, and names the alternative for the wrong case ('For a single lookup use ask_pipeworx instead'). It also handles the auth edge case by instructing unsigned-in agents to use ask_pipeworx.

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?

Despite annotations already declaring readOnly, idempotent, and non-destructive behavior, the description adds critical behavioral context: the USPTO PatentsView API sunset and soft-fail behavior, that empty sections mean real 'no data' not a bug, that FDA products showing none is expected for non-biologic companies, and that private companies return a notes line rather than a bare failure. These details go far beyond what annotations 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?

The description is appropriately sized for the tool's complexity — covering sources, return fields, edge cases, and input flexibility in about 250 words. It is front-loaded with the core purpose and examples. However, it is a single dense paragraph with heavy parenthetical asides; bulleted structure or section breaks would improve scannability without adding 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?

This tool has no output schema, so the description carries the full burden of explaining return values — and it does: cik, company_name, resolved_from/to, recent_filings with URIs, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used, and sources_failed. It also details failure semantics (soft-fails, empty sections, private companies) and parameter options, so an agent has everything needed to call 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%, so the baseline is 3, but the description adds meaningful semantics: the 'type' field accepts 'company' and 'ticker' interchangeably and behaves identically, 'value' can be a ticker, zero-padded CIK, or company name, and names resolve via SEC EDGAR's company-name match. It also clarifies future extension ('person/place coming soon') and gives concrete examples (AAPL, 0000320193, Moderna) that enrich 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 opens with a precise verb+resource statement: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' The example phrases ("Tell me about X", "brief me on Tesla") leave no doubt about what this tool does.

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 when-to-use guidance: use when the user asks for a holistic view and prefer over chaining single-pack lookups. It also details accepted input forms (ticker, CIK, company name) and boundary cases like private companies returning resolved:false instead of failing. This effectively routes the agent to call this tool for broad entity profile requests rather than individual lookup tools.

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

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

Annotations already declare 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?

Beyond the readOnly/idempotent annotations, the description discloses many behavioral caveats: keyword-based matching is not verified, compatibility_warning and compatibility_codes can be non-empty even when pairs return, gross spreads do not model Kalshi fees, temporal_alignment null means uncomputable not aligned, and unknown legs are never paired. 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 front-loaded with purpose, then modes, then safety fields, and then caveats — a logical order. It is dense and somewhat long, with minor redundancy (temporal_alignment_unknown is explained twice), but nearly every sentence earns its place given 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?

For a tool with no output schema, the description is remarkably complete: it details the response shape (prices, top_spreads_pp, flags, temporal_alignment, fees_note, skipped counters), when to trust vs distrust results, and how to interpret null/unknown values. An agent has enough to call it correctly and interpret outputs 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?

The schema already documents all three parameters with 100% coverage. The description adds meaningful mode semantics: providing topic triggers mode 1, providing explicit ticker/slug triggers mode 2, and both modes run the same matcher. It also enumerates the allowed topic shortcuts, which reinforces but goes slightly beyond the schema's enum-like list.

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 opening sentence is specific: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly names the resource (cross-venue spread) and the two venues. It also differentiates from siblings by emphasizing cross-venue comparison and the token-overlap matcher, which is distinct from arbitrage and edge tools.

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

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

The description gives clear context on when to use which mode (topic vs explicit pairing) and repeatedly cautions about false positives and non-tradeable spreads. It does not explicitly name alternative sibling tools, but the specificity of the purpose and the explicit two-mode explanation make the intended usage clear.

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

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

Annotations already declare 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?

The description goes far beyond the annotations, disclosing graceful degradation when GLEIF/OpenFIGI is unavailable, ambiguity handling via figi_candidates, explicit unresolved fields, source-labelled identifiers, internal cascading lookups, and coverage of non-US issuers through ISIN-to-LEI mapping. This is rich, accurate behavioral context that annotations alone could not 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 long and dense, and some sentences are run-ons with nested clauses. However, almost every detail earns its place given the tool's complexity, and the opening examples + priority statement front-load the most critical information. Slightly tighter organization would improve 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 there is no output schema, the description compensates thoroughly: it explains returned identifiers, candidate lists on ambiguity, unresolved fields, source labelling, and citation format for drug lookups. It also covers edge cases such as non-ticker securities and ISIN-to-LEI resolution. Nothing essential for correct invocation appears 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?

Though schema coverage is 100%, the description adds substantial meaning: it defines what counts as a valid value with examples (AAPL, 0000320193, 'ozempic'), warns against passing full noun phrases for bonds, and explains how ISINs resolve to legal entities. This meaningfully exceeds the schema's simple property descriptions.

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

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

The description clearly states the tool's job: resolving a user-spoken name to canonical/official identifiers. It gives concrete query examples ('What's the ticker for…'), names the supported entity types, and makes clear this is the go-to when you have a name but need an ID, distinguishing it from sibling tools like lookup or xrefs.

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 'Use FIRST whenever you have a name but need an ID' and details both supported types with acceptable inputs. It does not explicitly name alternative tools or state when NOT to use it, but the use case is unambiguous and strongly prioritizes this tool over siblings.

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

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

Annotations already declare readOnlyHint=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.