Opentargets

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context such as the default free model, the cost implication ('you pay Anthropic directly'), and the return structure. This exceeds the bare annotation hints without contradicting them, so 4.

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

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

The description is four sentences, front-loaded with the core purpose and then progressing to configuration, output, and use cases. It is efficient and free of fluff, though slightly longer than strictly necessary, justifying a 4.

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

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

Given the tool has four parameters, no output schema, and strong annotations, the description covers purpose, configuration, costs, return shape, and use cases. It lacks a detailed scoring explanation but that is not essential for invoking the tool, so 4.

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

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

Schema coverage is 100% with descriptions for all four parameters, so the baseline is 3. The description does mention the default model and API key requirement, but this largely repeats schema information (e.g., 'workers-ai' free default, '_apiKey' for Anthropic) and does not add new parameter-level meaning, so 3.

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

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

The description states 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model,' which is a specific verb and resource. It clearly conveys the tool's function but does not explicitly contrast it with sibling tools, so it stops short of a 5.

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear when-to-use context, but no mention of when not to use it or alternatives is included, so 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavior context: routing to thousands of tools, filling arguments, returning structured answers with stable pipeworx:// citation URIs, and being 'one fast call.' It also implicitly warns of hallucination risk by recommending ask_pipeworx_grounded for verbatim evidence.

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 (over 250 words) but well-structured and front-loaded with the critical 'PREFER OVER WEB SEARCH' directive. Each section adds value: use cases, examples, sibling comparisons, and performance notes. While it could be trimmed, the length is justified by the tool's complexity and the need to differentiate from many siblings.

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 is a complex meta-router with no output schema, so the description carries the burden of explaining return format and usage context. It does so thoroughly: structured answers with citation URIs, when to escalate to grounded/deep_research, performance characteristics ('one fast call', works on every tier), and domain coverage. It also hints at potential hallucination by recommending grounded for verbatim evidence.

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

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

Schema coverage is 100% for the single required parameter, with clear alias documentation. The description enhances understanding by providing numerous example questions ('current US unemployment rate', 'adverse events for ozempic') that illustrate acceptable query formats. This goes beyond the schema's minimal 'Your question or request in natural language.'

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

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

The description clearly states the tool's purpose: it routes questions to 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It explicitly contrasts itself with web search and sibling tools like ask_pipeworx_grounded and deep_research, giving it a distinct identity.

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 guidance: 'Use whenever the user asks...' with concrete query patterns (what is, look up, get the latest, etc.). It also provides alternatives and step-up paths for ask_pipeworx_grounded and deep_research, and positions this as the default entry point ('START HERE').

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, idempotent, etc.), the description adds valuable context: the tool is a full working router ('falls back to nothing'), its current state (no active candidate), and that outputs are compared against the stable router for evaluation. This directly addresses experimental behavior and does not contradict annotations.

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

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

Four sentences, each informative: identity, current state, usage, and fallback clarification. The description is somewhat long but well-structured and front-loaded with essential context. It avoids fluff but could be tightened.

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

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

Given the tool's complexity (router to 5,529 tools) and no output schema, the description covers what it is, current behavior, usage, and evaluation purpose. It references 'same response shape' as ask_pipeworx, but without prior knowledge of that tool, the response format remains partially unspecified. Still, it is fairly 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?

The schema covers 100% of parameters (all aliases for 'question'), so the baseline is 3. The description says 'same arguments' but does not add semantic detail beyond the schema. No additional parameter meaning is provided.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tool set and response shape, distinguishing it from the stable ask_pipeworx and grounded variant. It specifies the scope (routing to 5,529 tools) and its experimental nature.

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

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

Explicit guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing' and that results are compared with the stable router. It clearly frames the intended use case but does not explicitly mention alternatives like ask_pipeworx_grounded or scenarios where the stable version is preferred.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses the grounding mechanism, the exact return contract on success ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}), and the explicit refusal reasons. It also reveals the cost implication (one extra LLM call). This is substantial behavioral context not inferable from 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 information-dense and front-loaded with the core value proposition. Every sentence contributes meaningful content, but the middle sentence is long and combines multiple ideas (routing, argument filling, fetching, extraction). It is well-organized but slightly verbose compared to ideal minimal descriptions.

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 success and refusal response envelopes, including evidence quoting and all refusal reason enums. It also covers routing behavior, cost trade-offs, and ideal use cases, making it complete for complex high-stakes decision-making.

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% coverage, listing all six parameters as aliases for the natural-language question. The description adds no new parameter semantics beyond what the schema already states; the mention of routing and argument filling is implicit in the schema's description of 'question'. Baseline 3 is appropriate.

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

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

The description clearly states this is a 'hallucination-resistant answer mode for high-stakes reads' and differentiates it from ask_pipeworx by emphasizing it extracts answers only from tool results. The verb+resource is specific: it takes a question, routes to tools, and returns a grounded answer. It is also distinguished from sibling tools like ask_pipeworx and validate_claim.

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 specifies when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also gives an explicit alternative: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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?

Goes far beyond the annotations by detailing response shapes (result.market, result.analysis, result.evidence), resolver confidence contracts, parent-event extraction, news fallback flags, wide-spread warnings, and cancellation-rule risk. This gives an agent substantial behavioral context for safe invocation and result interpretation.

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 a clear purpose, but it is an extremely long, dense block of text with uppercase section headers that would benefit from structured formatting or trimming. Each section does add value, yet the sheer volume reduces scannability and may overwhelm the agent.

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 meticulously documents all return-value shapes, statuses, edge cases, and safety mechanisms. It covers market data, analysis fields, evidence structure, match confidence, parent-event details, news fallback behavior, and resolution-rule risk, making the tool fully understandable without external documentation.

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 has 100% coverage with clear descriptions and examples for all three parameters. The description adds meaningful context through fan-out examples and classifier lists, but it does not introduce new parameter syntax or constraints beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further clarifies the input forms (slug, URL, question text) and gives concrete example use cases ('should I bet on X'), making the tool's purpose unmistakable and distinct from siblings like polymarket_edges.

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

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

Explicitly states intended use cases: 'Use for "should I bet on X"...' It also provides when-not behavior by describing blocking statuses for low-confidence matches and closed/inactive markets. However, it does not name specific alternative sibling tools or give exclusion criteria like 'use polymarket_edges for pure edge comparisons.'

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 read-only/idempotent annotations, the description reveals data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). This is rich behavioral context that helps the agent set expectations.

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 necessary with repeated phrasings like 'X vs Y' examples, but it front-loads the core purpose and all sentences carry substantive information. Minor redundancy prevents 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 tool with no output schema, the description covers purpose, usage, data sources, performance expectations (replaces 8–15 lookups), sorting behavior, and return format. This is sufficiently complete 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?

Although schema coverage is 100%, the description adds meaningful semantics: it explains what each type pulls (10-K financials for companies, adverse-event/trial counts for drugs) and gives concrete value examples (tickers/CIKs, drug names). This exceeds 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 the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with specific verbs like 'compare' and a precise scope. It distinguishes itself from sibling tools like entity_profile by focusing on multi-entity comparison and batch efficiency.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides type-specific guidance (company vs drug). This gives clear when-to-use instructions and indirectly signals when not to use it (single entity lookups, >5 entities).

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

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

While annotations already mark this as read-only and idempotent, the description adds substantial behavioral context: account/plan requirements, parallel decomposition across 5,529 tools, return format (findings packet with gaps[] and contradictions[]), citation URI behavior, semantic excerpting, and latency expectations. No contradictions with annotations exist.

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 carries useful information (account requirement, scope, output, use cases, alternatives, depth details, latency). It is structured with parentheses and semicolons, though the core purpose appears after the account prerequisite, slightly reducing front-loaded clarity.

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

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

Given the tool's complexity and absence of an output schema, the description provides a thorough account of prerequisites, output structure, failure modes (gaps), discrepancies (contradictions), citation resolvability, and performance expectations. 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% because both parameters have descriptions, but the tool description adds meaningful elaboration beyond the schema: it explains depth semantics (quick/standard/thorough hop behavior, gap recovery, contradiction scan) and clarifies that 'question' is meant to be broad/multi-part. This enhances 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 clearly states this is a 'grounded multi-source research' tool over structured data, contrasting with open-web search, and names the specific resource (1455 structured data sources). It also explicitly distinguishes it from siblings like ask_pipeworx and search, making its unique role evident.

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 guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also names alternative tools and explains why deep_research may be inappropriate for certain topics.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context by explaining that results include full schemas and are ready to call directly, eliminating the need for a second lookup. 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 front-loaded with a clear one-line summary, followed by a domain list and return-value explanation. The list of domains is long but serves as useful context for query examples. Overall it is efficient and well-structured, with no wasted words.

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

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

Even though there is no output schema, the description clearly explains what the tool returns (top-N tools with names, descriptions, full schemas, examples). It also covers the core use case and input expectation. The combination of purpose, return format, and usage guidance makes the description complete for an agent to invoke 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 description coverage is 100%, so the parameters are fully documented in the schema. The description does not add parameter-level detail beyond what the schema provides, but it does align the 'query' concept with 'describing the data or task.' This meets the baseline expectation for high 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 tool's purpose with a specific verb ('Find') and resource ('tools'), and it distinguishes itself from sibling tools by being a meta-search over the tool catalog. It also lists concrete domains (SEC filings, FDA drugs, etc.), making the scope immediately understandable.

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

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

The description explicitly says when to use it ('Use when you need to browse, search, look up, or discover what tools exist') and emphasizes calling it FIRST when many tools are available. It does not explicitly name alternatives or when-not-to-use scenarios, but the guidance is clear and actionable.

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

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

Annotations already declare the tool as read-only, idempotent, open-world, and non-destructive. The description adds behavioral context by naming the data source (Open Targets) and the specific fields returned, which goes beyond the annotation safety profile. It also hints at the ontology-driven nature, giving the agent a clear mental model. No contradiction exists with annotations.

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

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

The description is concise and front-loaded with command examples. Every clause contributes: it conveys the purpose, the data source, the parameter, the return fields, and a complementary tool in just two sentences. There is no wasted text or redundancy.

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

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

For a simple tool with one required parameter, an output schema, and comprehensive annotations, the description is complete. It states what the tool returns, how to invoke it, and how it connects to a sibling tool. The presence of an output schema means return values need no additional explanation, making the description fully sufficient for effective use.

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

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

The input schema already documents `efo_id` with an example, providing 100% coverage. The description then enriches the parameter by explaining that EFO stands for Experimental Factor Ontology and by showing the parameter in command templates. This adds beyond the schema's basic example, making it clearer for agents.

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 a specific action: fetching a disease profile from Open Targets by EFO ID. It lists the return fields (name, description, therapeutic areas, ontology cross-refs), and the command patterns ('Disease profile for [EFO_N]' / 'look up disease [ID]') reinforce the purpose. It also differentiates from sibling tools like disease_associations by positioning itself as the profile lookup complement.

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 instructs to pair with `disease_associations` to find drug targets, which both differentiates the tool and gives practical guidance. The command patterns also illustrate invocation. However, it does not explicitly mention exclusions or compare with other siblings like `entity_profile` or `resolve_entity`, though the pairing note provides strong 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 already indicate read-only, idempotent, and non-destructive behavior. The description adds context about the tool's ranking/scoring mechanism ('scored by integrated evidence') and that it returns 'top' candidates, which goes beyond the annotations. No contradictions found.

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, starting with example queries, followed by a clear definition and usage guidance. Every sentence contributes to understanding, with no filler or redundancy.

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

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

With an output schema present and good annotations, the description does not need to explain return values. It gives sufficient context for target discovery, but it does not mention pagination, result limits, or any constraints on the size parameter, which is a minor gap.

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

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

Schema description coverage is 0%, so the description must compensate. It explains efo_id as a disease identifier, but does not explain the optional 'size' parameter. Since efo_id is the required parameter and size is likely straightforward (number of results), partial compensation warrants a mid-range score.

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 specifies that the tool returns top drug-target candidates for a disease, using an EFO ID as input. It includes example queries that illustrate the use case, and the focus on disease distinguishes it from sibling tools like target_associations or target_known_drugs.

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

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

The description provides clear usage context: 'Use for target discovery in a therapeutic area' and gives example natural-language queries. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of full exclusion 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 readOnlyHint, idempotentHint, and destructiveHint: false, so the safety profile is covered. The description adds context by specifying the data source (Open Targets) and the exact return fields, but it does not disclose rate limits, auth requirements, or any subtle behaviors. This adds some value but not rich behavioral detail.

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 at two sentences, but the opening alternates three phrasings ('Drug info for [ChEMBL ID]' / 'look up [drug] target info' / '[CHEMBL...] mechanism') which adds redundant phrasing. Still, information is front-loaded and every sentence carries purpose.

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

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

For a simple one-parameter read-only lookup tool, the description covers what it does, what it returns, and when to use it. An output schema exists to define the return structure, so the description does not need to explain that in detail. The tool is fully contextualized.

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

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

The schema has 100% coverage for the single parameter chembl_id, including type and example values. The description merely reinforces that the tool expects a ChEMBL ID but adds no extra syntactic meaning beyond the schema. Baseline of 3 applies due to high 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 tool fetches a drug profile from Open Targets by ChEMBL ID and lists the returned fields (name, mechanisms, indications, target genes, trade names, clinical-trial phase). This specific verb+resource distinction separates it from sibling tools like disease or target.

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

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

The description provides a clear usage context: 'Use for drug research, mechanism queries.' This indicates when to invoke the tool, though it does not explicitly name alternatives or exclusions. It offers more guidance than a bare lookup but stops short of comparative 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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond this: it fans out across specific sources, soft-fails when USPTO is unreachable, uses GDELT→GNews fallback, returns up to 5 filings with URIs, and sorts fundamentals by period_end descending. This explains runtime behavior 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 appropriately sized for the tool's complexity. It front-loads user-facing examples, then systematically lists outputs, sources, fallbacks, and input limitations. Every sentence contributes actionable information without redundancy.

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

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

Despite no output schema, the description fully enumerates return fields and their sources. It covers prerequisites (ticker/CIK), limitations (names unsupported, patent API sunset), error behavior (soft-fail), and suggests a sibling tool (resolve_entity). For a multi-source profile tool, this is 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% and both parameters are described in the schema. The description reinforces value formatting with examples ('AAPL', '0000320193') and repeats the constraint that names are unsupported, adding slight value beyond the schema without introducing new semantic details.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It uses a specific verb ('profile') and resource ('US public company'), distinguishes from siblings like compare_entities and deep_research, and lists concrete outputs (cik, filings, fundamentals, patents, news, LEI).

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 provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives clear exclusions: 'names not supported (use resolve_entity first if you only have a name)' and specifies accepted input formats (ticker or zero-padded CIK).

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 convey destructive behavior (destructiveHint true) and idempotency (idempotentHint true). The description adds useful context about clearing sensitive data and the memory being previously saved, but does not disclose additional behavioral details such as irreversibility or behavior when the key does not exist.

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 clause adds value: purpose, use cases, and pointer to related tools. No unnecessary 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 single-parameter delete tool, the description combined with annotations (destructive, idempotent) and the explicit key parameter is nearly complete. It could mention what happens when deleting a non-existent key, but the idempotentHint already implies no destructive failure, and no output schema is needed for a basic delete.

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 covers the only parameter ('Memory key to delete') at 100%, so the baseline is 3. The description reinforces that the key refers to a 'previously stored memory' but does not add substantial new 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 states a clear verb and resource: 'Delete a previously stored memory by key.' It distinguishes itself from sibling tools remember and recall by specifying deletion of stored memories, and even references these siblings explicitly.

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 criteria ('Use when context is stale, the task is done, or you want to clear sensitive data') and points to complementary tools ('Pair with remember and recall'), offering clear guidance for when to use this tool versus 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 and destructiveHint=false, establishing the safe read-only nature. The description adds valuable context beyond that: it fetches the page, extracts content, and emits a single text blob rather than writing to disk. It also discloses that output is in standard llms.txt format. This supplements 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 tightly written in three sentences: first states the purpose and audience, second explains the mechanics and output, third lists concrete use cases. Every sentence contributes new information, with no filler or redundancy. Essential details (standard format, single text blob) are 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?

Despite having no output schema, the description clearly explains the return value as a single text blob in standard llms.txt markdown, which is essential. It also covers input (any URL) and constraints (max_links via schema). It does not detail error behavior or handling of complex/SPA sites, but for a simple read-only generation tool with strong annotations, this is largely 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% for both parameters (url and max_links), so the schema already documents their meaning fully. The description adds no additional semantic detail about the parameters beyond what the schema provides (e.g., it does not explain edge cases, defaults, or constraints beyond the schema's own text). Baseline 3 is appropriate given the schema's completeness.

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: generating a production-ready llms.txt file for any URL for AI crawler indexing. It names the exact resource (llms.txt), the process (fetches page, extracts title/description/key links, emits markdown), and the target users (AI crawlers like ChatGPT, Claude, Perplexity). This specificity distinguishes it from sibling tools, most of which focus on research or market analysis.

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: getting a client's site indexed, drafting llms.txt for your own project, or auditing a competitor's AI visibility. This gives clear context for when to invoke the tool. However, it does not explicitly name alternative tools to use in other scenarios, leaving a small gap in when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by stating the specific output fields and the optional include_inactive parameter, enriching beyond annotations without contradiction.

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

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

Two sentences, front-loaded with the primary purpose, followed by return fields and a concrete use case. Every word earns its place; no filler or redundancy.

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

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

Given low complexity, strong annotations, and no output schema, the description is complete: it lists all return fields, states the default behavior (active only), and provides a usage example. Nothing essential 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 100% for the single parameter (include_inactive), so the schema fully documents it. The description adds no extra parameter semantics, but the baseline is 3 when schema coverage is complete.

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 from sibling tools like subscribe/unsubscribe. It also specifies the exact fields returned, 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?

The description explicitly states when to use the tool: 'review what you're monitoring before adding more' or 'find an id to cancel.' It provides clear use-context, though it doesn't explicitly mention alternatives or exclusions. Sibling tool names (subscribe/unsubscribe) implicitly differentiate it.

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

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

Annotations only state readOnlyHint=false, etc., but the description adds significant behavioral context: returns a claim_token anonymously, can be used later to read status, rate-limited to 5 per identifier per day, free, doesn't count against quota, and team reads digests daily. 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 lengthy but each sentence carries meaningful, non-redundant information. It is well-structured, front-loading the core purpose and then expanding into when-to-use, exclusions, token flow, and limits. Slightly long but justified by the tool's complexity.

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

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

For a tool with 4 parameters (including a nested object) and no output schema, the description is remarkably complete. It covers the full submission flow, anonymous claim_token handling, rate limits, scope boundaries, and even advice on disambiguating Pipeworx tools. No gaps.

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

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

The input schema already has 100% description coverage, so the baseline is 3. The description adds extra value by explaining the claim_token flow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and emphasizing it should be used 'with no other arguments.' It also clarifies the context object's optionality. This goes beyond the schema's descriptive text.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx tools) and differentiates from siblings by explicitly scoping to 'tools served by this Pipeworx connection' and excluding other MCP servers.

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 guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is strong usage guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses that data is self-aggregated from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. This adds valuable behavioral context about caching, privacy, and data source. 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 remarkably concise: two sentences. The first sentence states the primary function and output; the second elaborates with a bulleted use-case list. It is front-loaded with the action, and every sentence adds value without repetition 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?

The tool has a single optional parameter, no output schema, and read-only annotations. The description compensates by specifying the exact return contents (top tools, top packs, total call volume, and 'pack, tool, count' format), caching behavior, and privacy guarantees. For its simplicity, the description fully covers what an agent needs to know.

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% coverage of the single parameter 'window', including its enum values and a description of how shorter vs. longer windows affect results. The tool description merely repeats the window options without adding semantic detail beyond what the schema provides, so the baseline score 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 clearly states the tool's function: it returns top tools, top packs, and total call volume over a recent window. It explicitly focuses on 'what other AI agents are calling on Pipeworx right now,' which distinguishes it from siblings like ask_pipeworx (Q&A) and discover_tools (tool discovery). The verb 'returns' plus specific resources makes the purpose unambiguous.

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

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

The description provides a 'Useful for' list with three concrete scenarios, giving clear guidance on when to use this tool. It does not explicitly state when not to use it or name alternative tools, but the use cases implicitly contrast with asking a question (suggesting ask_pipeworx as alternative). This is strong contextual guidance, though not exhaustive.

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 readOnly/idempotent annotations by disclosing operational behaviors such as the semantic similarity threshold (∝0.30 Jaccard), placeholder filtering, and the fill check warning 'do not trade it' when realizable_edge_pp ≤ 0. These details help the agent understand limits and pitfalls.

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 bolded section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and every sentence carries operational value. It is not verbose in a wasteful way, but could be slightly tighter without losing critical context.

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

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

Despite lacking an output schema, the description enumerates the response fields (opportunities[], partition_check, fill_check) and covers all modes, edge cases, and caveats. It is self-sufficient for a complex tool and even references a sibling tool for related functionality.

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

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

Although the schema covers both parameters, the description enriches them with contextual examples (e.g., 'fed-decision-may-2026'), explains the behavior of each mode, and introduces a no-arg mode not visible in the schema. It clearly explains what to pass for each scenario and what happens internally.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', clearly stating the verb (Find), resource (arbitrage opportunities on Polymarket), and unique methodology. It distinguishes itself from sibling tools like polymarket_edges by focusing specifically on arbitrage detection rather than edge tracking or fill risk.

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 usage modes: 'Call with NO args for a trending_scan', 'pass event' for a specific market, or 'topic' for cross-event scanning. It recommends `event` for specific markets and points to an alternative tool: 'For custom sizing use polymarket_fill_risk.' This gives clear when-to-use and alternative 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 goes far beyond the annotations by detailing the internal model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), per-sport alpha values, filter logic (placeholder slug filter, partition skip threshold), the 24h-move warning, caching behavior (1h at KV level), and diagnostics. This rich behavioral context is additive to the readOnly/openWorld/idempotent hints, which it does not contradict.

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

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

The description is dense and lengthy, cramming model details, per-sport alphas, gate thresholds, and diagnostics into a wall of text. It is somewhat structured with bolded segment labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.), which aids navigation, but not every sentence earns its place—e.g., specific α values could be externalized. It is not concise; it is thorough but overstuffed.

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 high complexity and absence of an output schema, the description covers everything needed: the top-level response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity), the tradeable-edge knobs, and the Fed candidates exclusion rationale. It also explains caching and why segments may be empty, providing a complete picture for an agent.

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

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

Although the input schema provides 100% parameter coverage, the description adds meaningful grouping and behavioral nuance: 'TRADEABLE-EDGE KNOBS' groups min_liquidity/max_spread_pp, and it explains that min_kelly does not apply to partition arbs, pointing to min_partition_leg_kelly instead. It also gives actionable advice (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'), which is beyond the schema's descriptive sentences.

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 states the tool's purpose and distinguishes it from sibling tools like polymarket_arbitrage (which likely finds cross-market discrepancies) and polymarket_edge_tracker (which suggests historical tracking). The 'what should I bet on today' phrase grounds the use case.

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

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

The description gives clear context for when to use it ('Built for "what should I bet on today"—agents discover opportunities without paging hundreds of markets') and explains usage knobs (e.g., min_liquidity, max_spread_pp) and the tradeable-edge concept. However, it does not explicitly name alternatives or state when not to use it relative to siblings, 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=true, idempotentHint=true, and destructiveHint=false; the description adds significant behavioral context: 60-day snapshot TTL, snapshot write-on-cache-miss causing gaps, decay computed from daily closes of edge_pp_net rather than intraday, and the meaning of expired opportunities. 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?

Although the description is long, it is well-structured with labeled ARGS, RESPONSE, and LIMITS sections. Every sentence provides necessary operational or output detail, and the core purpose is front-loaded in the first sentence.

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 fully carries the return-value documentation burden. It details tracked[] fields, expired[] lifespan, snapshot_dates[], and relevant limitations, making the tool behavior complete for an agent invoking it.

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

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

The input schema already covers both parameters 100% with descriptions, defaults, and choices. The tool description mostly repeats the defaults and adds minimal context like 'snapshot family', so it adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a crisp question: 'how long has this edge existed and is it shrinking?' This is a specific verb+resource scope that clearly differentiates it from sibling tools like polymarket_edges.

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 the tool's intended use through the question it answers and discusses the conceptual difference between fresh and old edges. It does not explicitly name alternatives or exclusions, but the specialized purpose strongly implies when it should be selected 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: it enumerates return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, per-leg fill detail, thin_legs, forced_directional_risk), explains the semantics of size_usd for buys vs sells, and highlights the risk of partial basket fills creating unhedged positions. No contradiction with annotations.

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

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

The description is long but structured with mode-specific sections and a front-loaded summary sentence. Every section provides necessary operational detail (parameters, return fields, caveats, usage guidance), though it could be slightly more scannable. Given the tool's complexity, the density is appropriate.

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

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

With no output schema, the description compensates by explicitly listing the return fields for both single-market and basket modes, including verdict values, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers defaults, clamping, and the risk of unhedged positions, making it self-sufficient for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant cross-parameter meaning: market vs event are mutually exclusive modes, side defaults differ by mode (buy_yes for single-market, auto for basket), and size_usd is interpreted as spend for buys, target proceeds for sells, and settlement notional for basket mode. It also mentions clamping to 10–1,000,000, which is not in the schema. This goes beyond the schema's per-parameter descriptions.

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

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

The description states a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates from sibling tools by prescribing use before polymarket_arbitrage SELL/BUY-EVERY-LEG signals and polymarket_edges trades above ~$500.

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 usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when basket mode is needed and warns against using it for small trades where theoretical overround is likely uncapturable.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds extensive context: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs both venues >5 legs), temporal_alignment behavior, skipped_cross_type/subtype counters, and response structure. This goes well beyond the annotations.

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

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

Front-loaded with the core purpose and modes, but the description is a single dense paragraph with many safety-field details. Every sentence contributes, but it could be better structured with headings or bullet-like separation for agent parsing.

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

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

No output schema, but the description fully covers the response format (leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and edge cases, making it self-sufficient for a complex multi-mode tool.

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

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

Schema covers 100% of parameters with descriptions. The description adds override semantics (explicit ticker/slug overrides topic-mapped side) and explains how topic shortcuts auto-fetch matching events, enhancing understanding beyond the schema.

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

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

Clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' with specific verb+resource+scope. Distinguishes from siblings by explaining two modes and the compatibility_warning conditions that separate it from pure arbitrage 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 TWO MODES and when each is appropriate, and warns that 'pre-mapped ≠ tradeable' to set expectations. However, it does not name alternative tools for cases where the spread is not meaningful, so it lacks explicit 'use this instead' 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds useful behavioral detail about scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the optional listing behavior. This goes beyond what annotations provide.

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

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

Three sentences, front-loaded with the core action. Each sentence adds necessary context: behavior, use case, and scoping. 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 and no output schema, the description covers the retrieval action, the listing mode, scoping, and integration with sibling tools (remember, forget). It is sufficiently complete for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, with the 'key' property already described as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this by explicitly noting the omission behavior and giving examples of typical values, but adds no new semantic information 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 defines the tool's action ('Retrieve a value' or 'list all saved keys') and resource ('previously saved via remember'). It distinguishes from siblings by referencing 'remember' and 'forget' and giving concrete use cases (ticker, address, research notes).

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

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

Explicitly states when to use: when the agent needs context saved earlier, without re-deriving it. It also instructs how to list all keys (omit the key argument) and mentions pairing with remember (save) and forget (delete). This provides clear usage context and lifecycle 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 cover readOnly, idempotent, and non-destructive behavior. The description adds valuable context: mark_read side effect ('the next call only shows newer ones'), return item fields (source, citation_uri, raw payload), and the existence of an external endpoint for the same feed. This supplements the annotations without repeating 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?

Three sentences pack the core purpose, return features, filtering options, side effect, and an alternate access method without waste. The most important information is front-loaded in the first sentence.

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

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

With no output schema, the description compensates by listing what each alert carries and how to filter. It does not explicitly state that the result is an array or mention ordering, though 'most recent alerts' implies order. Overall, it provides sufficient context for an agent to correctly invoke the tool and interpret basic responses.

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 enhances parameter understanding with a concrete type example ('sec_8k'), clarifies since as an ISO timestamp, and explains mark_read's effect in more detail than the schema. Limit and unread_only are left to the schema, which already has adequate 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 a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly distinguishes this tool from siblings like list_subscriptions and recent_changes by focusing on fired alert events with source, citation_uri, and raw payload.

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 'Polls work fine' and mentions the same feed at an HTTP URL for scripts and dashboards, giving some usage context. However, it does not explicitly state when to prefer this tool over sibling tools or when not to use it, so it lacks clear exclusions or alternative tool comparisons.

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 fallback behavior (GDELT preferred, GNews when rate-limited or 5xx), USPTO soft-fail due to API sunset, and the response shape (structured changes[] grouped by source, total_changes count, and pipeworx:// citation URIs). This goes well beyond the readOnlyHint and idempotentHint annotations, giving the agent a clear understanding of what happens during execution.

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 dense single paragraph that front-loads the core purpose and includes essential details like source fallbacks and date formats. Every sentence earns its place, though bullet points for sources and parameters could improve scannability. It is effective but slightly unstructured.

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

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

Despite no output schema, the description explicitly explains what is returned (changes[] grouped by source, total_changes count, citation URIs) and covers important edge cases (API sunset, fallback behavior). It also provides a pointer to the sibling tool entity_profile for static profile needs, making the context complete for an agent to choose 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 covers all three parameters with descriptions, so the baseline is 3. The description adds extra context by linking `since` to the query phrasing ('last N days/weeks/months') and providing examples for `value` (ticker or CIK), though it mostly reinforces schema information. This adds marginal but useful value.

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

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

The description clearly states the tool provides a change feed for a company over a time window, specifying the sources (SEC, GDELT/GNews, USPTO) and the output format. It also distinguishes itself from entity_profile with an explicit 'Use entity_profile instead' guidance, 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?

It explicitly tells when to use this tool (e.g., for 'what's new with X' or 'latest on Y' queries within a time window) and provides a clear alternative for static profiles. It also advises a typical monitoring window ('Use '30d' or '1m' for typical monitoring'), which is 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?

Adds significant context beyond annotations: key-value storage scoped by identifier, persistence differences for authenticated vs anonymous sessions (24 hours), and cross-session retention. These details are not in annotations and are crucial for safe use. 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 concise, front-loads the core action, and every sentence contributes value—usage, behavior, retention policy, and related tools without redundancy.

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

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

Given the simple two-parameter schema and annotations, the description fully covers the tool's purpose, persistence behavior, and relationship to sibling tools. No output schema needed for a store operation.

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

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

Schema already provides 100% parameter descriptions, so the baseline is 3. The description reinforces key-value semantics and offers examples in the usage guidance, but does not add substantial new information about the parameters themselves.

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 later reuse using the verb 'save' and specifies the resource (data/memory). It distinguishes itself from siblings by explicitly mentioning 'recall' for retrieval and 'forget' for deletion, aligning with the sibling tool names.

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 guidance: 'Use when you discover something worth carrying forward' and lists examples like resolved ticker or user preference. It also names alternatives: 'Pair with recall to retrieve later, forget to delete,' giving clear 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 goes beyond the annotations by explaining graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), explicit handling of unresolved identifiers ('stated explicitly under `unresolved` rather than omitted'), and the cascading nature of internal lookups. These are valuable behavioral details that the annotations (readOnly, idempotent, non-destructive) do not convey. 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 longer than typical but front-loaded with user phrasing examples and the key directive 'Use FIRST whenever you have a name but need an ID.' It is well-organized by entity type, and every sentence adds functional value. A slightly tighter presentation would have earned a 5, but the detail is justifiable 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 only two parameters and no output schema, the description fully compensates by covering return values, failure behavior, source attribution, and internal fallback logic. It explains what the agent can expect in terms of results and edge cases, making it complete for the given complexity.

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

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

Although the schema already covers both parameters with examples, the description adds substantial semantic depth. For 'company' it details the cross-source identity spine, the specific identifiers returned (CIK, ticker, LEI, FIGI), and accepted input forms. For 'drug' it specifies the return payload (RxCUI, ingredient, brand) and the citation format. This exceeds the baseline of 3 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 clearly states that resolve_entity maps a user-spoken name to canonical/official identifiers, with specific examples like ticker, CIK, LEI, and RxCUI. The phrase 'Use FIRST whenever you have a name but need an ID' directly distinguishes it from sibling tools such as entity_profile or search, which focus on exploration or retrieval rather than ID resolution.

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

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

The description provides strong usage guidance, explicitly saying 'Use FIRST whenever you have a name but need an ID' and outlining the supported entity types and accepted input formats for each. However, it doesn't explicitly mention when not to use the tool or compare it with alternatives like entity_profile, so it falls slightly short of a perfect 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 read-only, idempotent, and non-destructive behavior. The description adds valuable context: it probes each entity via ai_visibility_check, ranks by score, and returns per-entity score, confidence, and signal density. No contradiction with annotations.

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

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

The description is concise and front-loaded: it states the primary action first, then explains the method, use case, and return format. Every sentence adds value with no redundant or vague phrasing.

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

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

Given no output schema, the description appropriately explains the return value (ranked list with score, confidence, signal density). It also references the internal mechanism and use case. Lacks details on edge cases or error conditions, but these are not critical for basic understanding.

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

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

Schema coverage is 100%, so the description doesn't need to explain parameter syntax. It does add the nuance that the first entity is treated as the 'subject' for narrative, but this is already present in the schema's entities description. Minimal added 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 function: comparing AI visibility across multiple entities side-by-side. It distinguishes itself from the sibling tool ai_visibility_check by emphasizing multi-entity comparison and ranking, and mentions its output of a ranked list.

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

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

Provides explicit use case for competitive AI-marketing audits with an example scenario. It implies that ai_visibility_check is the single-entity alternative but does not explicitly list exclusions or when not to use.

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

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

Adds latency and failure behavior beyond the readOnly/idempotent annotations: bundlephobia's first measurement can take 5-30s, and partial failures degrade gracefully with sources_failed listing timed-out sources. This is rich behavioral context annotations cannot 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?

Five dense sentences, each serving a distinct purpose: definition, use cases, return shape, ecosystem scope, and failure mode. Slightly longer than minimal but well organized with 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?

With no output schema, the description lists the complete summary block fields and other return components (per-advisory detail, links, alternatives). It also covers edge cases like the 5-30s first-measurement timeout, making the tool fully predictable.

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 already cover both parameters (package name, scoped package support, version default), so the description adds no new parameter-level detail. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description opens with a specific composite check definition and names the two external services (deps.dev, bundlephobia). It clearly distinguishes itself from unrelated sibling tools by scoping to npm package evaluation.

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?

Contains an explicit 'Use whenever...' clause with example queries ('is X safe / popular / small') and an explicit exclusion for non-npm ecosystems, directing users to deps.dev:version directly for other package managers.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds value by detailing the return format (ranked matches with canonical IDs for each entity type) and the scope of the search, which 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?

Despite being moderately long, every segment serves a purpose: example phrasings, scope, return values, and workflow guidance. The structure is front-loaded with user intents and ends with actionable next steps, making it dense yet highly informative.

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 an output schema present, the description need not detail return fields. It covers the search scope, entity types, and ID prefixes, and explains the intended workflow. It omits edge cases like pagination or error handling, but the annotations and schema cover the essential context for a search 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 schema covers size and entity, but not the required query parameter. The description compensates by explaining query through examples ('what's the Open Targets ID for [X]') and by mapping entity values to target/disease/drug. This adds meaningful context, especially for the undocumented query param.

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 a text search across diseases, drug targets, and drugs in the Open Targets Platform, returning ranked matches with canonical IDs. It distinguishes from sibling detail tools by explicitly positioning it as the first step to find IDs before calling target/disease/drug.

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

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

Provides explicit usage guidance: 'Use first to find IDs, then call target/disease/drug for details.' It also offers example user intents ('Find [disease / drug / gene target]'), which clarify when to invoke the tool. This is strong, actionable guidance.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, but the description adds substantive behavior beyond that: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-character overlapping windows, and enforces a 200K character cap with truncation flags. These are valuable operational details not inferable from 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 dense sentences deliver purpose, use case, companion tool, and technical caveats without fluff. The description is front-loaded with the core action, then progresses logically to when and how to use it, ending with constraints. Every sentence 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?

With no output schema, the description compensates by explicitly stating the return payload: 'top-N passages with character offsets and similarity scores.' It also covers edge-case behavior (truncation over 200K chars) and the embedding/windowing approach, giving the agent a complete mental model for planning calls.

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 parameters are well-documented structurally. The description reinforces the meaning of 'text' ('you already pulled') and 'query' (natural-language with examples), adding pragmatic context. However, it doesn't elaborate on 'limit' beyond the schema, though the schema itself already explains its range and default.

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,' which immediately identifies a specific verb, resource, and scope. It clearly distinguishes this tool from siblings like 'search' and 'ask_pipeworx' by emphasizing that it operates on already-fetched text rather than external sources.

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

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

Explicit guidance is provided: 'Use when the record is too big to cram into the prompt.' It also names a complementary tool, 'ask_pipeworx_grounded,' and explains the pairing: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' 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?

Annotations provide readOnly, idempotent, and destructive hints, and the description adds meaningful context: OAuth requirement, phone verification for SMS, 10/day SMS cap, and the always-on feed. No contradictions; the additional details go beyond the annotations.

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

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

The description is dense but every sentence carries value — covering purpose, auth, types, and delivery. It is front-loaded with the core action and return value, though the length is near the upper bound for a tool description.

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

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

The description is largely complete for a subscription-creation tool: it covers return value, auth, supported types with examples, feed and email/SMS channels, and SMS limitations. It omits the webhook delivery channel (present in schema), but the schema covers that, so the omission is minor.

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

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

Schema covers 100% of parameters with detailed descriptions, and the description augments this with concrete examples (e.g., items:['5.02'] = officer change, topic:'fed', series_id:'UNRATE'). This adds semantic richness beyond the schema's generic type 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 a specific verb+resource statement: 'Create a proactive monitoring subscription to a live-data event stream.' It also states it returns the new subscription id, clearly distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context: requires a Pipeworx OAuth account, excludes anonymous and BYO users, and explains how to pull alerts from the always-on feed. It doesn't explicitly name alternatives like 'use list_subscriptions to manage existing subscriptions,' but the usage context is well implied.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds concrete behavioral context: it returns example questions grouped by category, each with the corresponding tool and argument shape, and supports optional topic filtering.

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

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

The description is a single dense paragraph but front-loads the questions a user would ask. It covers purpose, output, parameters, and usage guidance without excess. The length is justified by the tool's onboarding role.

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 adequately explains the return format: category-bucketed example questions with exact tool and argument shapes. It also covers parameter behavior and usage context, making it complete for this tool's scope.

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

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

Schema coverage is 100% for the single optional parameter. The description adds value by giving example values ('finance', 'pharma', 'betting') and explaining that omitting the topic returns a cross-category spread, enriching the schema's basic enum 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 description clearly identifies the tool as the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape to answer them. It uses action-oriented language and distinguishes itself from siblings by positioning it as the first tool to use when uncertain.

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 to use this tool FIRST when you don't know what Pipeworx can do, and mentions learning to call meta-tools as an alternative. It lacks an explicit 'when-not' clause but the context strongly implies it.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context about the identifier system (Ensembl gene IDs) and the return fields (approved symbol, name, biotype, protein IDs, pathways, synonyms), which goes beyond the raw 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 compact yet information-dense. It front-loads example queries, then states the purpose, return fields, and use case in a single coherent statement. Every sentence earns its place with no fluff or redundancy.

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

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

For a single-parameter read-only tool with an output schema, the description covers all essential aspects: what it does, what input it expects, what it returns, and when to use it. The presence of an output schema reduces the need to describe return values in detail, and the description already lists key return fields.

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

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

The schema covers the single parameter 'ensembl_id' with a description and example, so baseline is 3. The description reinforces that Ensembl gene IDs are used as target identifiers, but this mostly restates the schema example. No additional parameter semantics beyond the schema are provided.

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

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

The description clearly states the tool's function: 'fetch a drug-target profile' for a given gene. It also provides concrete example queries ('Drug target profile for [gene]', 'is [gene] a druggable target') and distinguishes it from sibling tools like target_associations or target_known_drugs by focusing on the core profile.

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

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

The description provides clear usage context: 'Use for target characterization in drug discovery' and supports it with example query phrasings. It does not explicitly list exclusions or alternatives, but the context implies when this general profile tool is appropriate versus more specialized sibling tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context by listing the evidence categories (genetics, expression, animal models, drugs, literature, pathways) and that results are 'scored' and 'top'. 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 moderately concise but front-loaded with example queries that make the purpose immediately clear. The evidence list adds length but provides useful context; no redundant or empty phrases.

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 2 parameters, a rich output schema, and annotations, the description fully covers the tool's purpose, input format, and use case. It doesn't describe output details, but the output schema handles that, making the description adequate for the tool's complexity.

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

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

The schema only describes `size`, leaving `ensembl_id` undocumented. The description fills this gap by specifying it as an 'Ensembl gene ID' and showing examples. It does not add detail for `size`, but schema covers it, so the description meaningfully compensates for the missing param.

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 explicit natural-language queries ('What diseases is [gene] involved in') and then precisely states the tool returns 'top disease associations for a drug target (Ensembl gene ID), scored by integrated Open Targets evidence'. It clearly distinguishes from sibling tools like disease_associations by specifying the target-centric direction and unique evidence integration.

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 frames the intended use case: 'Use to triage what diseases a candidate target might address.' This gives a clear context for when to invoke. However, it does not name alternative tools or exclusion conditions, so it stops short of full when/when-not 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds scope context ('clinically tested or approved') and output details, but these are more about data scope than behavioral traits like rate limits or side effects. It does not contradict annotations.

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

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

The description is concise yet packs valuable information: example queries, scope, output fields, and use case. Every sentence adds value, and the structure is front-loaded with examples.

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 query tool with one required parameter and an output schema, the description provides sufficient context. It explains the purpose, the data scope, and the intended use cases, making it complete for an agent to select and invoke the tool correctly.

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

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

The schema covers size with a description, but ensembl_id lacks any description. The clarification that the target is an 'Ensembl gene ID' compensates for the missing schema description, improving parameter understanding. Size is already documented.

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

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

The description clearly states the tool's function: identifying drugs that have been clinically tested or approved against a given Ensembl gene ID. It explicitly lists the output content (drug names, mechanisms, indications, phases) and provides example queries. This distinguishes it from sibling tools like target and target_associations.

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

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

It gives explicit usage context: 'Use for competitive landscape / drug-repositioning queries.' This is clear guidance on when to use the tool, but it does not mention when not to use it or suggest alternatives, 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?

Discloses key behavioral traits beyond annotations: the row is deactivated (not deleted) and historical events remain available via recent_alerts, and ownership is enforced. This adds meaningful context about side effects and permissions that the annotations (idempotentHint, destructiveHint) do not capture.

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

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

Three sentences, each earning its place: the action, the ownership constraint, and the soft-delete behavior. No filler or repetition; it is front-loaded with the core action.

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

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

For a simple one-parameter mutation tool with annotations and no output schema, the description fully covers what the tool does, its authorization constraints, and its side effects. It even mentions how historical data remains accessible, providing complete context for the user.

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 fully describes the 'id' parameter as a subscription uuid returned by subscribe, so the description adds little beyond referencing the parameter by name. With 100% schema coverage, the description need not elaborate further, and it does not introduce any additional 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?

Description clearly states 'Cancel a subscription by id' with a specific verb and resource, and the ownership enforcement note distinguishes it from related tools like subscribe and list_subscriptions. The action and scope are 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?

Usage context is implied: the tool cancels subscriptions, but there is no explicit guidance on when to use this tool over alternatives like list_subscriptions or recent_alerts. The ownership note ('only your own subscriptions') hints at prerequisites, but no direct when-to-use or when-not-to-use instructions are provided.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description exposes important behavioral nuances: the SEC EDGAR fast path vs. grounded fallback, the meaning of each verdict type, and crucially, the distinction between 'could_not_verify' (verification failed, must not be treated as evidence) and 'unsupported' (no source found). This significantly enhances the agent's ability to interpret results correctly.

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 richly informative but efficiently organized. It opens with concrete invocation phrases, then states purpose, describes processing paths, lists output types, and ends with critical caller caveats. Every sentence carries unique information; no filler or repetition. It is long but necessary for such a multi-path, high-stakes verification 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?

Despite no output schema, the description fully documents the return values (verdicts, actual value with citation, reasoning) and explains error semantics. It covers the two distinct execution paths, routing logic, and the important negative case ('could_not_verify'). The description is complete for a tool of this complexity, leaving no major operational gaps.

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

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

While schema coverage is 100%, the description adds substantial value beyond field descriptions. For 'claim' it provides realistic examples ("Apple's FY2024 revenue was $400 billion"), and for 'tolerance_pct' it explains how it overrides implied tolerance, recommends values for hallucination detection (1–2), and clarifies the default behavior (implied by wording, capped at 5). This goes well beyond the schema's basic 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 function: natural-language claim verification against authoritative sources. It uses strong action phrases ('fact check', 'verify the claim that') and provides concrete examples. It also distinguishes itself from sibling tools by focusing on factual claim verification rather than general search or research, and explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.'

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

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

The description provides explicit when-to-use guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the two-path routing for company-financial vs. other claims. It also notes efficiency ('Replaces 4–6 sequential calls'). However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks the full when-not/alternatives coverage that would merit a 5.

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