Protein Atlas

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral traits: calls LLMs, requires API key for Anthropic (with cost implication), returns per-model data with raw response. Does not mention rate limits or error handling.

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 well-structured sentences: purpose, details (default model and key requirement), and use cases. No wasted words. Information density high and front-loaded.

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

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

Despite no output schema, description specifies return format (per-model fields + combined view). Covers input, output, use cases, and cost implications. Adequate for moderate complexity with 4 parameters and clear annotations.

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

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

Schema coverage is 100% (all 4 parameters described in schema). Description adds meaning: explains default model, indicates _apiKey only needed for Anthropic, and clarifies that context helps disambiguate common names.

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

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

Description clearly states it probes LLMs for business visibility and scores it 0-100. Verb 'probe' and 'score' with specific resource 'business/brand/product/topic'. Differentiates from sibling 'scan_competitor_ai_presence' by being more generic and providing per-model scores.

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

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

Explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Explains default model vs. Anthropic with key requirement. No explicit 'when not to use' or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds that the tool returns 'stable pipeworx:// citation URIs' and 'fills arguments', which provides some behavioral context but does not significantly extend beyond the safety profile given by annotations.

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

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

The description is a single paragraph that efficiently conveys purpose, usage, and examples. It is not overly verbose but could benefit from bullet points or clearer separation of guidelines vs. examples for easier scanning.

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

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

Given the complexity of a multi-tool router and the absence of an output schema, the description adequately covers what the tool does, when to use it, and what it returns (structured answer with citations). It could mention handling of ambiguous queries but overall is sufficient.

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

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

The input schema covers all parameters (100%), with description of the main 'question' parameter and alias fields. The description adds no additional semantic meaning beyond the examples, which are also present in the schema.

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

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

The description clearly states that the tool answers factual queries about real-world data (SEC filings, FDA drug data, etc.) by routing to multiple sources and returning structured answers with citations. It distinguishes itself from general web search but does not explicitly differentiate from the sibling 'ask_pipeworx_grounded', which limits clarity.

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 'PREFER OVER WEB SEARCH' and enumerates scenarios: questions about current/historical data, specific data types, and even provides example queries. It conveys when to use this tool instead of alternatives, fulfilling the guideline criterion.

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. Description goes beyond by detailing the extra LLM cost, the refusal reasons list (not_in_source, no_tool_match, etc.), and the exact return structure. No contradictions with annotations.

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

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

Description is detailed but front-loaded with the core purpose. Every sentence provides valuable context (routing, extraction, refusal, cost, use cases). Slightly longer than necessary but acceptable given the high-stakes nature and need for transparency.

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

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

No output schema, but description fully specifies the return object (answer, evidence, confidence, source, fetched_at, refusal_reason) and the possible refusal reasons. For a complex, high-stakes tool with many sibling tools, this ensures the agent knows what to expect.

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

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

Schema coverage is 100% with all 6 parameters described as aliases for 'question'. Description does not add new semantics beyond stating that arguments are filled by routing. Baseline 3 is appropriate as schema already covers parameter meaning adequately.

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

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

Description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads. It distinguishes from its sibling ask_pipeworx by specifying that it extracts answers only from tool results, with explicit refusal mechanisms. The verb 'extracts' and resource 'answer from tool result' are specific and unique.

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

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

Explicitly states when to use: 'when an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. Also provides a clear alternative: 'prefer ask_pipeworx for casual lookups.' This gives actionable guidance for tool selection.

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

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

The description extensively details behavior beyond annotations: classification, fan-out logic, resolver contract, parent event extractor, news fallback fields, safety short-circuits, and wide-spread warnings. It aligns with readOnlyHint, idempotentHint, and non-destructive annotations, adding significant transparency without contradiction.

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

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

The description is front-loaded with core purpose and structured using clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). It is lengthy but every sentence earns its place given the tool's complexity. Minor opportunity for tighter wording but still effective.

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

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

Given the absence of an output schema, the description thoroughly explains return values (result.market, analysis, evidence), edge cases (low-confidence, closed markets), and how to interpret resolver fields. It covers all aspects needed for correct agent usage, leaving no critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter behavior (market input formats, depth default, include_raw effect) with concrete examples and fan-out illustrations, enriching the schema descriptions.

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

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

The description clearly states it researches a Polymarket bet by pulling relevant data in one call, specifying input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes itself from sibling tools like ask_pipeworx and polymarket_edges by being the comprehensive research tool for single bets.

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

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

The description explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides examples and explains when results are not actionable (low-confidence matches, closed markets). However, it does not explicitly exclude alternatives or state when to use siblings instead.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) indicate safe, non-destructive behavior. The description adds substantial behavioral context: for company type, it explains data source (SEC EDGAR/XBRL), financial metrics pulled, and off-calendar handling; for drug type, it lists FAERS, FDA approvals, and trial counts. It also mentions sorting by primary metric and citation URIs. No contradictions with annotations.

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

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

The description is somewhat lengthy but every sentence adds value—trigger phrases, type-specific details, sorting behavior, and citation mention. It front-loads with common query examples. Could be slightly tightened, but remains efficient for the complexity.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citations), the description is remarkably complete. No output schema exists, but the description covers return format (paired data + citation URIs) and data sources. It satisfies all contextual needs 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 coverage is 100% with descriptions for both type and values. The description adds significant meaning: it explains that type can be 'company' or 'drug' with data source examples, for values it specifies tickers/CIKs for companies and drug names, with min/max constraints. It also explains result structure (sorted by primary metric) and output format, going well beyond the 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, using common query phrases like 'compare X and Y' and 'head to head', and explicitly distinguishes from sequential lookups. It specifies the verb (compare) and resource (entities) with a clear scope.

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

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

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups' and provides contextual trigger phrases. It does not explicitly list when not to use or mention alternative tools, but the sibling list includes entity_profile and search_within, which could serve as alternatives. The guidance is strong but lacks exclusion criteria.

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

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

Annotations already state readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond annotations: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains output format and readiness, which is not covered by annotations.

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

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

The description is concise (~100 words) and well-structured: it front-loads the purpose and usage, then lists specific domains. Every sentence adds value, with no fluff or repetition.

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

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

No output schema is present, but the description explains what is returned (top-N tools with names, descriptions, full schemas, and examples). It also specifies the limit parameter and aliases. Given the tool's complexity and the richness of structured fields, the description is complete for an agent to understand 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%, so the baseline is 3. The description mentions the 'query' parameter is a natural language description and lists aliases, which adds minimal meaning beyond the schema's own description. The schema already provides examples and detailed descriptions for each parameter.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and emphasizes that it returns tool names, descriptions, and schemas. This distinguishes it from sibling tools, which are specific to particular tasks or data 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?

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' It implies not to use when you already know the tool or need a single answer, but it does not list explicit alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds rich behavioral context: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; notes USPTO PatentsView API sunset May 2025 with soft-fall; explains fallback from GDELT to GNews; details return fields including CIK, filings with URIs, fundamentals sorted, patents, news, LEI. No contradiction with annotations.

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

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

Description is detailed and well-structured, with key information front-loaded. Slightly verbose but every sentence adds value—examples, constraints, data sources, and return fields are all covered efficiently.

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

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

Despite no output schema, the description comprehensively lists return fields (CIK, filings, fundamentals, patents, news, LEI) and explains source behaviors and limitations (soft-fail, name restriction). For a complex multi-source tool, this is complete enough for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, but description adds value by clarifying that type is only 'company' currently, value must be ticker or zero-padded CIK, and names are not supported. Examples provided. Adds context beyond 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?

Description clearly states it profiles a US public company across multiple sources, provides example queries, and distinguishes from chaining single-pack lookups. The verb 'profile' and resource 'entity' are specific, and it defines the holistic scope.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and notes that names are not supported, directing to use resolve_entity first. This provides 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?

Annotations provide destructiveHint=true and idempotentHint=true. The description adds 'delete' and 'memory' but does not detail behavior for missing keys or error conditions. With annotations covering the destructive nature, a score of 3 is appropriate.

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 action, then usage, then pairing. Every sentence adds value with no redundancy.

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

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

Low complexity tool with 1 parameter and good annotations. The description covers purpose and usage well, though it omits handling of missing keys and return value. Still sufficiently complete 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?

Input schema has 100% coverage with one parameter 'key' and description 'Memory key to delete'. The description adds 'by key' but no additional meaning. Baseline 3 for high 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 states 'Delete a previously stored memory by key', which is a specific verb-resource pair. It clearly distinguishes from siblings 'remember' (store) and 'recall' (retrieve).

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

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

The description explicitly says 'Use when context is stale, the task is done, or you want to clear sensitive data' and pairs with 'remember' and 'recall'. This provides clear context and alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context by detailing the process (fetches page, extracts title/description/key links) and output format (single text blob). 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: two effective sentences plus a bullet-like list of use cases. It front-loads the main purpose and avoids any fluff. Every sentence adds value.

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

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

Given no output schema, the description sufficiently explains the output format and usage. Annotations cover safety. Both parameters are documented. The tool's complexity is low, and the description covers all necessary aspects.

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 clear descriptions for both parameters. The description reinforces the default/max for max_links but adds minimal new meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's action ('generate a production-ready llms.txt file') and the resource ('any URL'). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on generating the file itself rather than scanning or checking.

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 (client site, own project, auditing competitor) which helps the agent judge applicability. However, it lacks explicit 'when not to use' or alternative tool recommendations, but the context is still clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value by stating 'keyless' (no API key needed) and describing the returned fields (trimmed profile). No contradictions.

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

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

Two sentences only, both packed with information. First sentence gives purpose with example and field list. Second sentence adds prerequisite and keyless info. Front-loaded and no wasted words.

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

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

No output schema, but description explains what is returned (gene, description, protein class, etc.). Mentions trimmed nature and keyless. For a simple retrieval tool with one parameter, this is adequate and 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?

Schema coverage is 100% with a good description. Description adds an example value and clarifies the format (ENSG...). Adds value beyond the schema.

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

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

Clearly states the action (get), resource (Human Protein Atlas profile), scope (trimmed, one protein), and key input (Ensembl gene id). Provides an example and lists fields returned. Distinguishes from sibling search_genes.

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

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

Explicitly says to use search_genes to find the Ensembl id before using this tool. Does not explicitly state when not to use it, but the prerequisite is clear. No alternatives mentioned for getting protein info.

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 and idempotentHint. Description adds that it returns specific fields and defaults to active subscriptions, which is consistent. No contradictions.

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

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

Two sentences: first states purpose and returns, second gives usage guidance. No redundant information, 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?

Given no output schema, the description specifies return fields. Single parameter fully covered by schema. Annotations cover safety. Description is complete for an agent to understand and use the tool.

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

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

Schema description coverage is 100% for the single parameter. The description does not add additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It lists the return fields and distinguishes from sibling tools like subscribe/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?

Explicitly states when to use: to review monitoring before adding more subscriptions or to find an id to cancel. Provides clear context and exclusion criteria.

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

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

Annotations provide no behavioral hints, but description adds critical behavior: rate-limited to 5/identifier/day, free, no quota impact, and describes how feedback is processed (daily digests, roadmap influence). 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?

Single paragraph with purpose first, then guidelines, then behavior. Every sentence adds value; no wasteful repetition.

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

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

For a feedback tool with 3 params and no output schema, description covers all necessary aspects: when to use, what to include, how it's processed, and constraints. Agent can invoke correctly without additional context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra guidance: message should be specific, use tool/pack terminology, and describes type enum values in more detail than schema.

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

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

Description clearly states the tool sends feedback to Pipeworx team, lists exact feedback types (bug, feature, etc.), and distinguishes itself from sibling tools by being a communication channel for issues/praise.

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

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

Explicitly tells when to use each feedback type, provides a negative instruction (don't paste end-user prompt), and mentions rate limits and cost/free nature.

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 provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds value by disclosing the data source ('derived from CF analytics-engine'), stating no PII, and noting caching behavior ('Cached 5min-1h depending on window'). No contradictions.

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

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

Two short paragraphs; first sentence immediately states the main function. Every sentence adds value without redundancy. 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?

Despite no output schema, the description explains return values (top tools, top packs, total call volume) and caching. Annotations cover safety and idempotency. The single optional parameter is fully documented. Complete for this simple tool.

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

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

Schema coverage is 100% with enum descriptions that explain the effect of each window (shorter for trending, longer for steady-state). The description reinforces this. The baseline is 3 due to high coverage, but the description adds extra context about window behavior.

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 and resource: 'Returns the top tools, top packs, and total call volume'. It clearly distinguishes from sibling tools like 'discover_tools' by focusing on trending data derived from analytics.

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

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

Description explicitly lists three use cases (discovering hot data sources, confirming canonical choices, aligning use cases). However, it does not explicitly state when not to use the tool or mention alternatives, though the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context, such as requiring one parameter, walking child markets, running partition checks, and the structure of the response (opportunities array, partition_check). It also explains edge cases like skipped_low_similarity and placeholder 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 somewhat verbose but every sentence adds important detail. It front-loads the requirement for one parameter and explains both modes, response structure, and filtering logic. Could be slightly more structured, but it is informative 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 complexity of two operational modes, the description fully explains the response (opportunities array and partition_check), edge cases (low similarity, placeholder filtering), and behavioral constraints (requires one parameter). No output schema exists, but the description compensates with clear return value details.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds further value by noting that full Polymarket URLs are accepted for 'event' and providing example values for both parameters, as well as explaining the semantic anchor and partition filter rules.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between 'event' mode for a specific market and 'topic' mode for cross-event scanning, providing a specific verb and resource with differentiation between the two modes.

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

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

The description explicitly recommends 'event' for a specific market and 'topic' for cross-event scanning, explaining when each mode is appropriate and that cross-event mode catches patterns single-event misses. However, it does not explicitly state when not to use the tool altogether.

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

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

Description discloses extensive behavioral details beyond annotations: model families, edge calculation, response structure, caching (1h KV-level), diagnostics, Fed note, and parameter interactions. All consistent with readOnlyHint and idempotentHint.

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

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

Description is lengthy but well-structured with sections. Front-loaded with purpose then details. Every sentence adds value, but could be trimmed slightly for agent efficiency. Still effective.

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

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

Given no output schema, the description thoroughly covers return structure (by_segment, diagnostics, Fed candidates), parameter effects, and caching behavior. Complete for an agent to invoke correctly without additional context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra meaning by explaining how knobs like min_partition_leg_kelly and max_spread_pp affect filtering, which is beyond schema descriptions.

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

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

Clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. Specifies target use case 'what should I bet on today' and distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx data divergence.

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 guidance on when to use (betting advice) and how to tune with tradeable-edge knobs, but does not explicitly exclude use for other purposes or contrast with sibling tools. Still clear enough for an agent to determine applicability.

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

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

The description adds substantial context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by explaining bet shape equivalence, temporal alignment, compatibility warnings, and skipped types. It honestly discusses limitations, making the tool's behavior fully transparent.

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

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

The description is verbose but well-structured, front-loading the core purpose and using clear sections for modes, response, and safety fields. Some redundancy could be trimmed, but each sentence adds value.

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

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

The description adequately explains inputs, behavior, and outputs, including response structure, compatibility warnings, temporal alignment, and counters. Despite no output schema, an agent can fully understand what the tool returns and how to interpret 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?

With 100% schema description coverage, the description still adds meaning by explaining the two modes and how parameters interact (e.g., topic auto-fetches, explicit overrides). Examples in the schema further clarify usage.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific verb ('compute' implied) and resource ('spread'). It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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 outlines two modes (topic shortcuts and explicit pairing) and warns that most pre-mapped topics return compatibility warnings, indicating when not to use. However, it does not explicitly name alternative sibling tools for single-venue analysis, though it is 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 readOnlyHint=true and destructiveHint=false, so the description does not need to repeat that. It adds useful context: behavior when key is omitted (list all keys), scoping to identifier, and pairing with remember/forget. No contradictions.

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

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

Four sentences, no wasted words. Front-loaded with core action, then purpose, then scoping and pairing. Efficient and well-organized.

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

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

For a simple retrieval tool with one optional parameter, rich annotations, and no output schema, the description covers all necessary aspects: when to use, behavior with/without key, scoping, and relations to other tools.

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

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

Schema coverage is 100% with a description for the 'key' property. The description reinforces the behavior of omitting the key and provides examples of typical key values (ticker, address, notes), adding meaning beyond the schema alone.

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

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

Clearly states the tool retrieves a saved value or lists all keys. Specifies verb 'retrieve'/'list' and resource 'memory'. Differentiates from siblings remember and forget by explaining pairing. Provides concrete examples of use cases.

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?

Describes when to use: to look up previously stored context without re-deriving. Specifies scoping to identifier. Implicitly suggests alternatives by mentioning remember and forget siblings, but does not explicitly state when not to use or exclude other 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?

The description states that setting mark_read=true flags events as read, causing a state change. This contradicts the readOnlyHint annotation which indicates no state modification. Contradiction detected.

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

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

The description is three sentences, front-loaded with the core purpose, no redundant information. Every sentence adds value.

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

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

The description explains key behaviors (filtering, mark_read side effect) and alternative access. However, it lacks a full specification of the return format beyond mentioning three fields, which would be helpful given no output schema.

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

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

With 100% schema description coverage, the baseline is 3. The description adds valuable context: examples for type (e.g., 'sec_8k'), clarification that since is an ISO timestamp, and the behavioral effect of mark_read. This justifies a 4.

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

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

The description clearly states it pulls recent alerts from a subscription feed, specifies return fields and filtering options. The tool name and context distinguish it from siblings like list_subscriptions, subscribe, and unsubscribe.

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

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

The description mentions polling works and provides an alternative URL for scripts/dashboards, implying usage context. However, it does not explicitly guide when to use this tool versus sibling tools like list_subscriptions.

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, destructiveHint, idempotentHint, and openWorldHint. The description adds valuable context about the underlying data sources (SEC EDGAR, GDELT→GNews fallback, USPTO) and soft-fail behavior, exceeding what annotations provide.

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

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

The description is front-loaded with usage examples and is well-structured. Every sentence adds value, though it is slightly verbose for a highly experienced audience.

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

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

Given the complexity of the tool (multiple data sources, fallback logic, parameter flexibility), the description covers all essential aspects: fan-out, sources, parameters, return structure (changes grouped by source, total_changes, citation URIs). Even without an output schema, the return shape is described.

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

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

Schema coverage is 100%, but the description adds crucial details: 'since' accepts ISO dates or relative shorthand with examples, and 'value' can be ticker or CIK. This goes beyond the schema description.

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

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

The description explicitly states the tool's purpose with concrete examples: 'What's new with X', 'latest on Y', etc. It clearly defines it as a change feed for a company in a recent time window and distinguishes it from the sibling tool entity_profile.

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

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

The description provides clear usage patterns, including example queries and when to use this tool over entity_profile. It explains the fan-out logic across multiple data sources.

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 idempotentHint=true and destructiveHint=false. The description adds critical behavioral context: scope by identifier, persistent vs. anonymous session retention (24 hours), and pairing semantics. 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?

Three sentences front-load the core purpose, then progressively add usage, scoping, and pairing details. Every sentence serves a purpose; no redundant information.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, data persistence, authentication nuance, and tool interdependencies. No gaps remain for agent 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?

Schema description coverage is 100%, providing clear parameter explanations with examples. The description adds value by framing key-value as 'scoped by your identifier' and emphasizing reusability, but the schema already handles format details adequately.

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

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

The description uses specific verbs ('save data', 'reuse later') and explicitly lists example payloads (resolved ticker, target address, user preference). It clearly distinguishes from sibling tools recall and forget by mentioning them as complementary actions.

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

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

Explicitly states when to use ('when you discover something worth carrying forward'), provides context (across conversation/sessions), and directs pairing with recall/forget. No ambiguity about its role.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructive behavior. The description adds that each call cascades through several endpoints internally, and details what each type returns (ticker, CIK, RxCUI, citations). This enriches the transparency beyond the annotations.

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

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

The description is a single paragraph that is well-organized and front-loaded with examples. It is slightly lengthy but each sentence adds necessary context. Minor redundancy could be trimmed, but overall it is effective.

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

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

Given the tool has only 2 parameters, full schema coverage, safety annotations, and no output schema, the description covers all necessary aspects: use cases, supported types, return values, disambiguation, and replacement of multiple lookups. The agent has sufficient information to use the tool correctly.

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

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

Schema coverage is 100% with basic descriptions. The description greatly expands on both parameters: for 'type' it explains supported entities and their return contents; for 'value' it provides input examples (ticker, CIK, names) and mentions auto-disambiguation for companies.

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

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

The description starts with concrete examples like 'What's the ticker for...' and clearly states the tool resolves names to canonical IDs. It distinguishes itself from siblings by focusing on ID lookup and explicitly recommends using it first when an ID is needed.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It also mentions that the tool replaces multiple manual lookups. However, it does not explicitly state when not to use it or suggest alternatives for unsupported entity types, though the context is clear enough.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also describes the return format (ranked list with score, confidence, signal density). No contradiction.

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

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

Three sentences, front-loaded with main action ('Compare AI visibility across multiple entities side-by-side'). Every sentence adds value without redundancy.

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

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

Given no output schema, the description compensates by explaining return values (ranked list with score, confidence, signal density). It covers usage, examples, and behavioral context comprehensively for a moderate-complexity tool.

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

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

Schema coverage is 100%, so every parameter is described in the schema. The description adds meaning: 'Probes each entity with ai_visibility_check' for entities, 'Passed to api.anthropic.com per probe' for _apiKey, 'Disambiguates common names' for context, and 'Omit for just workers-ai' for models. This significantly aids understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 it is useful for competitive AI-marketing audits and provides an example quote. However, it does not explicitly state when not to use or alternatives beyond the sibling 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 already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and lists exact return fields.

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

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

The description is front-loaded with the core purpose but includes a detailed list of returned fields which, while necessary, makes it somewhat lengthy. Still concise for the complexity.

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

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

With no output schema, the description fully explains return values (summary block, advisories, links, alternatives) and handles edge cases like timeouts. Complete for a composite tool.

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

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

Schema coverage is 100% and the description adds extra meaning: it clarifies scoped packages are accepted and that version defaults to latest when omitted, going beyond the schema.

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

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

The description clearly states it is a composite check for npm packages combining deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency', and distinguishes itself from a diverse set of sibling tools by focusing on this specific 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?

Explicitly defines when to use: when an agent asks about safety, popularity, size, or cost. Also notes NPM-only in v1 and points to alternatives for other ecosystems.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds 'Keyless' indicating no authentication needed, but does not disclose other behaviors like pagination or rate limits, which are still useful context.

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

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

The description is two sentences, front-loaded with the core purpose, and includes only essential information without fluff.

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

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

Given low complexity and full schema coverage, the description adequately covers the return fields (Ensembl id, synonyms, description) and the keyless nature, though pagination behavior is not explicitly mentioned.

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%, both parameters have descriptions. The description restates query as 'gene symbol or keyword', adding no new semantic detail beyond the schema.

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

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

The description clearly states it searches the Human Protein Atlas by gene symbol or keyword, and specifies the returned fields including Ensembl gene id needed by sibling tools get_protein and top_tissues, distinguishing it from them.

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

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

The description implies usage context by mentioning that the Ensembl id is required by get_protein and top_tissues, but does not explicitly state when not to use or list alternative tools.

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

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

Goes beyond annotations by detailing output (passages with offsets and similarity scores), embedding model (BGE-base-en), chunking strategy (500-char windows), and 200K char limit with truncation flag. Annotations only hint at safety and idempotency.

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 concentrated sentences plus technical detail. Front-loaded with core purpose. Every sentence adds value with no redundancy.

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

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

Covers when to use, what to expect (passages with offsets), technical limitations (200K chars, truncation), and relationship with sibling tool. No output schema, but description compensates well.

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

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

Schema coverage is 100%, but description adds meaning: explains 'text' as already fetched, 'query' as natural-language with examples, and 'limit' as max passages. Adds value beyond parameter names and types.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article). It distinguishes from siblings like ask_pipeworx_grounded by explaining the fetch-then-search workflow.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. Provides clear context but doesn't explicitly exclude other use cases.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, which align with the description's creation behavior. The description adds context on account requirements (OAuth), delivery channels, and SMS caps. It does not contradict annotations, though it could clarify idempotency implied by idempotentHint=true.

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: first sentence states purpose, then detailed behavior, requirements, and delivery options. Every sentence adds value with no redundancy.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description covers return value, requirements, and delivery details. Missing elements like error handling or rate limits are minor, but overall it's complete enough 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?

With 100% schema description coverage, the baseline is 3, but the description adds concrete examples (e.g., items:['5.02']) and clarifies defaults and delivery validation, significantly 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?

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, specifically for sec_8k filings. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by detailing the creation behavior and requirements.

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

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

The description explains when to use the tool (for monitoring sec_8k filings) and mentions account prerequisites. However, it does not explicitly contrast with siblings or state when not to use it, though the context is clear.

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

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

Annotations already declare readOnlyHint and no destruction; description adds 'keyless' (no API key) which is useful additional context. 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?

Two concise sentences, no wasted words. Purpose is front-loaded, making it quick to parse.

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

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

For a simple read-only tool with rich annotations, the description is complete. It explains input requirements, ordering, and access (keyless). No output schema needed for such a list.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds context like 'highest first' but does not significantly extend beyond schema. Baseline 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?

Clearly states the verb 'list', resource 'top-expressing human tissues by RNA expression (nTPM)', and scope 'for one Ensembl gene id'. Distinguishes from sibling tools like search_genes by directing users to it for ID lookup.

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

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

Provides explicit context: when to use (need top tissues for a gene) and prerequisite (use search_genes to find Ensembl id). Does not explicitly state when not to use, but clarity is sufficient.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description reveals that the row is deactivated not deleted, and that historical events remain available via recent_alerts. This adds valuable behavioral context and has 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?

Two concise sentences that front-load the core action and follow with key behavioral details. No unnecessary words; every sentence adds value.

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

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

For a simple tool with one parameter, the description covers the action, ownership constraint, deactivation behavior, and links to a related tool (recent_alerts). It is complete given the schema and annotations richness.

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 id parameter described. The description adds context that the id is returned by subscribe, which aids in understanding its origin beyond the schema's description.

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

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

The description clearly states the action (cancel) and the resource (subscription by id). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and soft deactivation.

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

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

The description explicitly mentions ownership enforcement as a condition for use, providing clear context on when the tool is appropriate. It does not explicitly mention alternatives or when not to use it, but the sibling list provides implicit cues.

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 annotations by detailing the output structure (verdict types, structured form, actual value with citation, percent delta) and explaining its efficiency gains over multiple calls. Annotations already indicate safety, and the description adds rich behavioral context without contradiction.

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

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

The description is front-loaded with the core purpose, uses bullet-like phrasing for clarity, and every sentence adds necessary information. It balances detail with readability.

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

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

Given the lack of an output schema, the description adequately explains the return values and behavior. It also notes the domain limitation, ensuring the agent understands 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% with a clear description of the 'claim' parameter. The tool description adds value by providing example claim formats, 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?

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It gives concrete examples and distinguishes itself from potential alternatives by specifying the domain and replacing multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also limits the scope to company-financial claims, providing clear guidance on appropriate usage. However, it does not explicitly mention when not to use or provide alternatives.

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