Semrush

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral context: default model is free, Anthropic probing requires user-provided API key and incurs direct cost to user. It also describes the return structure (per-model fields plus combined view), which is not in 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?

Five concise sentences, front-loaded with the primary action and purpose. Every sentence adds essential information: first sentence states core function, second covers default and key requirement, third describes return shape, fourth lists use cases. No superfluous content.

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

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

No output schema is provided, but the description mentions the return structure (per-model {score, confidence, signals, raw_response} + combined view), partially compensating. It does not cover error scenarios or rate limits, but given the idempotent and read-only annotations, the description is largely complete 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 coverage is 100% with descriptions for all four parameters. The description enhances understanding by explaining that models can include 'anthropic' only if _apiKey is provided, and that context helps disambiguate. It also reveals the default model and usage of _apiKey field, adding value beyond schema.

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

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

Description explicitly states the tool probes LLMs for knowledge about an entity and returns visibility scores. It specifies default model (Workers AI Llama-3.3-70b) and optional BYO key for Anthropic. This clearly distinguishes from sibling tools like entity_profile or scan_competitor_ai_presence in its focused scope on LLM knowledge assessment.

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 concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'). Does not explicitly state when not to use or list alternative tools, but the context is clear enough for appropriate selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable context: routes to 3,300 tools, fills arguments, and returns citations with stable URIs. No contradictions.

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

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

The description is relatively long but each sentence adds value. It is front-loaded with the core purpose, provides examples, and explains the mechanism. Could be slightly more concise, but maintains 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 (aggregating many sources), the description is thorough: it explains purpose, usage, mechanism, and return format. No output schema but describes citations. Highly complete.

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

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

Schema description coverage is 100% with clear descriptions of aliases. The description adds value with example questions, which aids understanding of how to use the parameter. Baseline 3 + examples = 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 explicitly states 'PREFER OVER WEB SEARCH' and lists specific domains (SEC filings, FDA drug data, etc.), making the purpose clear. It distinguishes itself from general web search and implicitly from sibling tools that are more domain-specific.

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

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

The description provides extensive guidance: 'Use whenever the user asks...' with examples. It clearly states when to prefer this tool over web search, but does not explicitly mention when not to use or provide alternatives among 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 indicate readOnly=true and idempotent, etc. Description adds that it consumes API units and notes the absence of a regional database parameter, providing useful behavioral context beyond annotations.

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

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

Description is reasonably concise with two sentences plus a column list. No unnecessary words, though the column list could be shortened. Overall efficient.

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

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

For a read-only summary tool with no output schema, the description adequately explains usage (target, API key) and returns (all columns). Covers cost (API units) and regional constraint. Lacks nothing critical.

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 3. Description adds minimal extra detail (e.g., example for target, note that _apiKey is passed as query param), but doesn't significantly enhance understanding beyond schema.

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

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

The description clearly states it provides a backlinks summary for a domain or URL, explicitly listing all returned columns. This distinguishes it from sibling tools, none of which are backlink-related.

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?

No explicit guidance on when to use this tool vs alternatives. It mentions that backlinks reports are not regional and that it consumes API units, but doesn't explain context for choosing this over 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?

Provides extensive behavioral details beyond annotations: resolver contract with match confidence levels, parent event extractor, news fallback mechanisms, safety handling for low-confidence and closed markets, and wide-spread liquidity warnings. Annotations already indicate safe read-only behavior, and description adds rich 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 lengthy but well-organized, starting with purpose, then classifiers, fan-out examples, response shapes, and safety mechanisms. Every section earns its place for a complex tool with many behavioral nuances. Could be more concise, but structure is logical.

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 all aspects: input flexibility, resolution process, fan-out categories, response fields, error states (low-confidence, closed market, wide spread), and fallback mechanisms. Without an output schema, this description provides sufficient context for an agent to correctly invoke and interpret results.

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

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

Input schema has 100% coverage; description adds value by explaining default behavior for 'depth' (quick vs thorough) and 'include_raw' (summary vs full payloads), and clarifies that 'market' accepts multiple formats (slug, URL, question text). This enhances 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 identifies the tool as researching Polymarket bets by pulling Pipeworx data in one call. It specifies the verb 'research' and resource 'Polymarket bet', and differentiates from sibling tools like polymarket_arbitrage and ask_pipeworx by stating its use case for betting decisions.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides fan-out examples by bet category, helping agents understand when to apply the tool. However, it does not explicitly mention when not to use it or suggest alternatives, though sibling tools exist.

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

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

The description adds significant behavioral detail beyond annotations: always pulls latest data, handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. Annotations already indicate read-only, idempotent, and non-destructive, and description aligns perfectly.

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

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

The description is well-structured, starting with main purpose, then detailing each type, and ending with behavioral notes. Every sentence adds value, 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 2 parameters and no output schema, the description explains return format (paired data + URIs) and behavior (sorted). It covers essential context, though error handling or edge cases could be 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% with descriptions for both parameters. The description adds value by explaining data sources (SEC EDGAR for companies, FAERS for drugs) and sorting behavior, 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 compares 2-5 companies or drugs side by side, with specific use cases like 'compare X and Y' and 'X vs Y'. It distinguishes two entity types with different data sources, making the purpose unmistakable.

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

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

The description explicitly says when to use: for comparison or ranking questions. It provides clear context and constraints (2-5 entities). It doesn't explicitly name alternatives but implies it replaces multiple sequential lookups.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N tools with names, descriptions, full schemas, and examples, and mentions default limit 20 max 50. 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?

Three sentences: purpose, domain list, usage guidance. Front-loaded with key info, no filler. 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 the tool's complexity (6 parameters, no output schema), the description adequately explains what is returned (tools with names, descriptions, schemas, examples). Could be more explicit about response structure but sufficient 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?

Schema coverage is 100% (all parameters have descriptions). Description does not add additional meaning beyond what is already in the schema, so 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?

Description clearly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, etc.), distinguishing it from sibling tools which are domain-specific. It is a meta-tool for discovering other 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?

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear when-to-use guidance and implying alternatives if you already know the tool.

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

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

The description adds value beyond annotations by explaining that the tool consumes Semrush API units and detailing the returned columns. Annotations already indicate read-only, idempotent, non-destructive behavior, which is consistent. The description 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 two sentences, front-loaded with purpose, then adds column details and API unit warning. It is concise and each sentence adds information. Could be slightly more structured but efficient.

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

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

Given high schema coverage and annotations, the description provides sufficient context: what data is returned (columns), cost (API units), and that it is a read operation. No output schema but columns listed. For a data retrieval tool, it is adequately 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?

Parameter descriptions in the schema are complete (100% coverage). The description adds column definitions for the returned data (Ph, Po, etc.), which is not in the schema. This enhances understanding of output beyond parameter 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 returns top organic search keywords for a domain using Semrush, and specifies 'type=domain_organic' which distinguishes it from sibling tools like domain_paid_keywords. The verb 'returns' and resource 'organic keywords' are specific and unambiguous.

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

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

The description implies usage for organic keyword analysis but does not explicitly state when to use this tool versus alternatives (e.g., domain_paid_keywords or keyword_overview). No guidance on when not to use it or prerequisites beyond having a Semrush API key.

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 value by warning that the tool consumes Semrush API units and describing the return format (parsed rows with columns), which is not in 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 relatively concise, with one main sentence and a list of columns. The column list is somewhat lengthy but necessary for output clarity. 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?

Given no output schema, the description adequately provides the column structure, input parameters (via schema), and behavioral context (API unit consumption). It is complete enough for a simple overview 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 detailed descriptions for all 4 parameters. The description adds minimal extra meaning, only noting that _apiKey is BYO and domain should be without scheme. 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 'Domain overview (Semrush type=domain_ranks): high-level SEO/PPC summary for a domain' and lists returned columns, distinguishing it from more specific sibling tools like domain_organic_keywords and domain_paid_keywords.

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 for a high-level overview but does not explicitly state when to use this tool over others. It mentions API unit consumption but lacks explicit when-not-to or alternative recommendations.

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 that the tool returns parsed rows with specific columns and consumes Semrush API units. This adds value beyond readOnlyHint and idempotentHint annotations by indicating cost/rate limiting. No contradictory information.

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, front-loaded with purpose and output structure. No 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?

Lists all output columns and notes API unit consumption. Could elaborate column meanings further but is adequate for a read-only data retrieval 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?

All 4 parameters are described in the input schema (100% coverage). The description adds no additional parameter guidance beyond what the schema provides.

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

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

Clearly states the tool retrieves paid keywords a domain bids on using Semrush. Differentiates from sibling 'domain_organic_keywords' by specifying 'Paid (AdWords/PPC)' and 'Semrush type=domain_adwords'.

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?

Implicitly indicates use for paid keywords but provides no explicit when-to-use or when-not-to-use guidance. Does not mention alternatives despite sibling differentiation being available.

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, openWorldHint, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: it returns specific fields, mentions a bug fix for FY2025 numbers, notes the USPTO API sunset, and describes fallback behavior (GDELT→GNews). No contradictions.

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

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

The description is dense with information and front-loaded with purpose. However, it includes minor technical asides (like 'Run 6 fix landed...') that could be streamlined. Still, 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 thoroughly explains return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and their caveats (e.g., patents soft-failing). It covers all essential aspects of the tool's behavior and output.

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 critical context: which values to use for 'value' (ticker or CIK), that names are not supported, and that 'type' currently only accepts 'company'. This exceeds 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 explicitly states 'Get everything about a US public company in one call' and lists specific data sources (SEC EDGAR, XBRL, USPTO, etc.), clearly distinguishing it from siblings that provide individual services.

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

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

The description provides explicit usage scenarios ('tell me about X', 'research Acme') and when to avoid (using names), directing to resolve_entity for names. It also specifies accepted input formats (ticker or CIK) and unsupported name input.

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 destructiveHint=true, and the description reinforces this with 'Delete' and 'clear sensitive data', adding practical context about the type of data affected. No contradictions with annotations, and the extra detail helps the agent understand the tool's impact.

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

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

Two sentences, no redundant words. The first sentence immediately states the primary purpose, and the second provides usage guidance. Efficiently structured 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?

Given the tool's simplicity (single parameter, no output schema, clear annotations), the description covers all necessary aspects: purpose, usage scenarios, behavioral implications, and pairing with sibling tools. 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 'key' with a clear description. The description adds only 'by key' which aligns with the schema but does not provide additional semantics beyond what the schema already conveys.

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 action ('Delete') and the resource ('previously stored memory by key'). It also differentiates from sibling tools by mentioning pairing with remember and recall, providing clear context for when to use this tool over alternatives.

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

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

The description provides explicit usage contexts: 'when context is stale, the task is done, or you want to clear sensitive data'. While it does not include explicit 'when not to use' statements, the examples are specific and meaningful for agent decision-making.

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 it fetches the page and extracts content, which aligns with annotations. No additional behavioral traits beyond that, but 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?

The description is three sentences, front-loaded with the main action, and every sentence adds value. No redundancy or unnecessary words.

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

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

Given the tool's simplicity (two parameters, no output schema, no enums), the description explains the output format and use cases sufficiently. Missing error handling but acceptable for this complexity.

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

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

Schema coverage is 100% with adequate descriptions for both parameters. The description does not add significant 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 the tool's purpose: generate a production-ready llms.txt file for any URL, with specific mention of AI crawlers. It uses a specific verb and resource, and the purpose is distinct from the listed sibling tools.

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

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

The description provides explicit use cases (getting a client's site indexed, drafting for own project, auditing competitors) but does not include when-not-to-use or alternatives. The context is clear enough for an agent to decide.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it consumes Semrush API units and returns specific columns, providing transparency beyond annotations.

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

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

Two sentences: first states purpose and type, second lists return columns. 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?

Tool is simple with 3 parameters, all documented. Description explains return columns, compensating for missing output schema. Contextually complete.

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

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

Schema coverage is 100%, so baseline is 3. Description provides example for phrase parameter but adds little beyond schema. No contradiction.

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 provides search metrics for a single keyword phrase using Semrush type phrase_this. Distinguishes from sibling tools like domain_organic_keywords which handle domains.

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 it handles a single keyword phrase, giving clear context. Does not explicitly list alternatives or when not to use, but purpose is well-scoped.

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 read-only and idempotent annotations, the description explicitly mentions consumption of Semrush API units, adding transparency about cost. No contradictory behavior noted.

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 with front-loaded purpose, returning columns, and cost implication. Every sentence is essential.

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 purpose, output columns, and cost. Lacks pagination details and examples, but sufficient for a straightforward retrieval 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 descriptions are adequate. The tool description adds context about returned columns but does not enrich parameter meanings beyond schema.

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

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

The description clearly states the tool finds organic search competitors for a domain, including the Semrush type. It is specific and distinct from sibling tools like domain_organic_keywords.

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 for competitor data but does not explicitly state when to use vs alternatives or provide 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?

Discloses key behaviors beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that team reads digests daily affecting roadmap. 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?

Five sentences cover all necessary aspects without redundancy, but could be slightly more compact. However, it is well-structured and front-loaded with the core purpose.

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

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

Given no output schema and three parameters, the description fully covers purpose, usage, behavioral traits, and parameter semantics. There is no missing context for an agent to correctly invoke the tool.

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

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

Schema coverage is 100% and description adds value by elaborating on each enum value of 'type', explaining the optional context object, and specifying that 'message' should be specific and concise. Adds meaning beyond the schema.

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

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

The description clearly states the tool is for informing the Pipeworx team about issues or praise, using specific verbs like 'broken', 'missing', or 'needs to exist'. It distinguishes from sibling tools (which are for queries, checks, research) by being the designated feedback channel.

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: for bugs (wrong/stale data), features/data gaps (missing tools), or praise. Also provides guidance on how to describe issues (in terms of Pipeworx tools/packs, not user prompts) and mentions rate limits and that it's free.

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. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, caching (5min-1h), and output format (pack, tool, count). No contradictions.

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

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

The description is efficient: three sentences plus bullet-like points, front-loaded with purpose, and each sentence adds unique value. No wasted words.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, usage, data source, caching, and ethical notes. The output format is implied ('just (pack, tool, count)'), but explicit return structure would improve completeness.

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 descriptive enum and field description. The tool description repeats the window purpose (shorter = hot, longer = steady-state), adding minimal extra value 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 returns top tools, packs, and call volume over a recent window, using specific verbs like 'returns' and 'discovering'. It distinguishes from sibling tools by focusing on trending/aggregate data, which is unique among the given set.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, and aligning use cases) and explains window choices. It lacks explicit when-not-to-use guidance but provides 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: partition checks (sum of YES prices ≈1), similarity anchor (≥0.30 Jaccard), placeholder filtering, and detailed response structure. No contradiction with annotations.

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

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

The description is fairly long but well-structured: clearly presents two modes, then covers filters and response. It front-loads the purpose. Every sentence adds necessary detail for a complex tool; slight trimming possible but overall 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?

Given two optional parameters and no output schema, the description covers inputs, operational logic, filters, and output structure comprehensively. It provides sufficient information for correct invocation, especially with the detailed response schema explained.

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 provides descriptions for both parameters. The description adds deeper semantics: differences between event and topic modes, example inputs, and how parameters interact with internal logic (e.g., event mode checks partition). This enriches agent understanding beyond schema.

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

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

The description explicitly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and provides unique methodology, clearly separating it from sibling tools like polymarket_edges or polymarket_kalshi_spread.

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

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

The description clearly explains when to use each mode: single event slug vs cross-event topic search. It also details filters like similarity threshold and placeholder exclusion, aiding agent decision. However, it does not explicitly state when not to use the tool or mention alternatives.

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

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

The description fully aligns with the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations. It discloses caching behavior (1h KV level keyed on knobs), explains edge net of slippage, and includes a 24h-move warning. 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 well-structured with clear segments and front-loaded purpose, but it is verbose. Each sentence adds value, but some content could be streamlined without losing clarity. Slight score reduction for excessive length.

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

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

With no output schema, the description fully explains the response structure, including by_segment categories, fed_candidates, and _diagnostics. It covers all nine parameters in detail, making the tool's behavior and filter knobs completely transparent for an agent to invoke correctly.

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

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

The description adds significant value beyond the input schema's parameter descriptions, providing context for each knob (e.g., min_partition_leg_kelly explains why min_kelly doesn't apply to partition arbs) and offering default values and practical usage tips (e.g., slippage_pp typical range).

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, explicitly targeting 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_kalshi_spread by detailing its unique model families and response segments.

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 guidance on when to use the tool (e.g., 'what should I bet on today'), explains the knobs for filtering (min_liquidity, max_spread_pp, etc.), and notes limitations like unreliable Fed signals without paid data. However, it does not explicitly state when not to use it or compare to 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?

Beyond the readOnlyHint and idempotentHint annotations, the description provides rich behavioral context: it explains the two modes, compatibility_warning cases (non-equivalent bet shapes or semantically unrelated events), temporal alignment, and skipped cross-type/subtype counters. It honestly states that real spreads are rarer than the macro-shortcut list suggests. 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 somewhat long but well-structured with explicit headings (TWO MODES, RESPONSE, SAFETY FIELDS) and clear case explanations. Every sentence adds value, though it could be slightly more concise without losing key details.

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 (3 optional parameters, no output schema), the description fully covers what the response contains: leg-by-leg prices, matched spreads with top_spreads_pp, compatibility_warning details, and temporal_alignment. All necessary information for correct invocation is present.

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

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

Schema description coverage is 100%, with each parameter having a clear description. The tool description adds significant value by enumerating the 10 pre-mapped topic shortcuts, explaining that explicit tickers/slugs override topic-mapped sides, and providing examples in the schema. This goes well 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?

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket, explains two modes (topic mode and explicit pairing), and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on the same resolving question across venues. It provides a specific verb-resource pair (cross-venue spread) with sufficient detail to differentiate.

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 (to find spreads between venues) and provides two clear modes with explicit instructions for pre-mapped topics or custom pairings. It also warns that most pre-mapped topics currently return compatibility_warnings, guiding appropriate use. It does not explicitly state when not to use, but the context is clear enough for decision-making.

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 are readOnly, idempotent, non-destructive, and description adds scoping and behavior when key is omitted, providing full transparency.

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

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

Concise, each sentence adds value; well-structured 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?

Covers retrieval, listing, scoping, and pairing; missing explicit return format but adequate for a 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% and description adds meaning about omitting key to list all keys and the retrieval purpose.

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

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

The description clearly states it retrieves a value saved via remember or lists all keys, differentiating it from siblings.

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 context for using the tool to look up stored information and mentions pairing with remember/forget, but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds value by explaining parallel fan-out to multiple sources, fallback logic (GDELT → GNews), and soft-failure for USPTO due to API sunset. 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 a single dense paragraph that efficiently front-loads the purpose, then systematically covers sources, parameter format, return structure, and alternative tool. Every sentence adds value, with no filler 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?

Given the tool's complexity (multiple sources, fallback, parameter options, and no output schema), the description is thorough: it explains each source's behavior, fallback, soft-failure, parameter formats, return structure (changes[] grouped by source, total_changes count, citation URIs), and alternative tool. Minor missing detail: it doesn't mention any output schema, but the description itself states the return structure.

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% (each parameter has a basic description). The description adds significant meaning: for 'since', it explains both ISO date and relative shorthand with examples ('7d', '30d', '3m', '1y') and suggests '30d' or '1m' for typical monitoring. For 'value', it clarifies ticker vs zero-padded CIK. This goes well 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 starts with 'What's new with a company in the last N days/months?' and provides explicit example queries ('what's happening with X', 'updates on Y'), making the primary purpose immediately clear. It also distinguishes itself from the sibling tool 'entity_profile' by contrasting the dynamic change monitoring with static profile retrieval.

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 this tool (change-monitoring, news updates) and when not to (use entity_profile for static profiles). It also details the fallback behavior for news sources (GDELT preferred, GNews fallback) and notes the USPTO soft-failure, providing clear guidance on tool behavior in various scenarios.

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

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

Annotations already indicate non-read-only and non-destructive. Description adds that memory is scoped by identifier and persistence differs for authenticated vs anonymous users (24h). It could mention that storing same key overwrites, but still good.

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 well-structured, front-loaded with purpose. Could be slightly more concise, but 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?

Complete for a storage tool: explains data is stored, scoped by identifier, persistence durations, and pairs with recall/forget. No output schema needed.

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 key and value. Description mentions key-value pair and examples, but does not significantly add beyond 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?

Clearly states the tool saves data for later reuse across conversations/sessions, distinguishing it from sibling tools recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. It also mentions pairing with recall and forget, providing clear 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing safety and idempotence. The description adds that the call cascades through several endpoints, which is useful but does not reveal behavioral traits beyond what annotations provide. Thus, the description adds moderate value.

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

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

The description is a single paragraph that front-loads the core purpose and then efficiently details the supported types and their inputs/outputs. Every sentence adds value without redundancy or fluff.

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

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

Given the tool's complexity (two entity types with different return values) and the absence of an output schema, the description thoroughly explains what each call returns, including citation URIs. It also clarifies the cascading behavior, making it complete for agent selection and invocation.

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

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

The input schema has 100% coverage, but the description adds substantial meaning: for company, it details acceptable inputs (ticker, CIK, name) and outputs (ticker, CIK, company_name, citation URI); for drug, it specifies inputs (brand/generic name) and outputs (RxCUI, ingredient, brand, citation URI). This goes well beyond the schema's brief 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 clearly states the tool resolves user-spoken names to canonical identifiers, specifying supported types (company, drug) and their outputs. It distinguishes from sibling tools by noting that other tools require these IDs as input, 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?

The description explicitly says 'Use FIRST when you have a name but need an ID,' providing clear guidance on when to use it. It also mentions efficiency gains (replaces 2-3 manual lookups). However, it does not explicitly state when not to use it or list alternatives, which 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.

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds context by explaining the underlying method (calling ai_visibility_check) and output format (ranked list with score, confidence, signal density). No contradictions.

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

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

The description is concise (4 sentences), front-loaded with the main purpose, and every sentence adds value. No redundant or vague language.

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

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

Given no output schema, the description explains the return format sufficiently. It covers parameters, method, and use case. Minor gaps: missing error handling (e.g., fewer than 2 entities) and unclear if multiple models can be used simultaneously.

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 critical semantics: entities must be 2-8, first entry treated as subject, models default to workers-ai, and _apiKey required for anthropic. These details are not in 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 uses a specific verb ('compare'), a clear resource ('AI visibility across multiple entities'), and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (other metrics). It also provides a concrete 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 states it is 'useful for competitive AI-marketing audits,' implying when to use. It mentions probing each entity with ai_visibility_check, which suggests a single-entity alternative, but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds crucial behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed reports timeouts. 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?

The description is a single paragraph but well-structured: starts with purpose, then lists return fields, then constraints and fallbacks. It is informative without being overly verbose, though it could be broken into shorter sentences for readability.

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

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

Without an output schema, the description thoroughly explains return values: summary block, per-advisory detail, links, and alternative versions. It also details behavior on partial failures. This is comprehensive enough for an agent to understand 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 clear descriptions for both parameters. The description adds that version defaults to latest and accepts scoped packages, but these are also implied by the schema. Since coverage is high, baseline is 3, and the description adds minimal extra parameter insight.

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

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

The description clearly states the tool is a composite check for npm packages, integrating data from deps.dev and bundlephobia. The verb 'scan' and resource 'dependency' are specific, and the summary of return fields distinguishes it from sibling tools like 'compare_entities' or '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 states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes the NPM-only scope in v1 and directs alternative ecosystems to 'deps.dev:version'. This provides clear guidance on appropriate contexts.

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 indicating read-only and idempotent, the description details the return verdict types, citation format, percent delta, and performance improvement over alternatives.

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?

Several sentences but each contributes meaning. Slight redundancy in synonyms ('fact-check, verify, validate') but overall 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?

Covers purpose, usage, scope, inputs, and output types. Even without an output schema, the description sufficiently explains what the agent can 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 covers the single parameter fully; description adds helpful natural-language examples showing valid inputs, which adds value 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?

The description clearly states it fact-checks natural-language factual claims against authoritative sources, distinguishing it from siblings by noting it replaces multiple sequential calls and is specialized for company-financial claims.

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

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

Explicitly says to use when checking if something is true, provides example queries, and notes scope limitations (company-financial claims for public US companies).

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