Semrush

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it makes API calls to LLMs (free default, BYO key for Anthropic), explains cost implications, and details the return format (per-model score, confidence, signals, raw_response + combined view). 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 extremely concise: two sentences with no filler. The first sentence front-loads the core action, default model, and optional API key. The second sentence efficiently covers return structure and use cases. Every sentence earns its place 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 sufficiently explains the return structure (per-model fields + combined view) and use cases. It covers input parameters, cost implications, and purpose. It lacks details on error handling, rate limits, or maximum entities, but is nearly complete for a probe tool of 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 has 100% description coverage for all 4 parameters. The description adds meaning beyond the schema: it clarifies that 'models' defaults to workers-ai, '_apiKey' is only needed when probing Anthropic, and 'context' helps disambiguate entities. This extra context justifies a score above the baseline of 3.

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

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

Description clearly states the tool probes LLMs for entity knowledge and scores visibility (0-100). It specifies the default model and optional Anthropic integration, and lists concrete use cases like AI-marketing audits and competitive monitoring. The verb 'probe' and resource 'visibility score per model' are specific and distinguishable from siblings like 'scan_competitor_ai_presence'.

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 provides clear context for when to use the tool: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains the default model and the optional API key for Anthropic. However, it does not explicitly state when not to use this tool or compare it to alternative sibling tools, so guidance is strong but not exhaustive.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. Description adds valuable context: routes to 4,774 tools, returns structured answer with citation URIs, and is the default entry point. No contradictions. Description enhances annotation information without redundancy.

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 well-organized with key information front-loaded. Though somewhat lengthy, every sentence adds value, covering purpose, usage, examples, and differentiation. Efficient for the breadth of 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?

Despite lacking an output schema, the description fully explains the tool's behavior (routing, citations, types of questions), usage context, and differentiation from siblings. It leaves no important gaps given the tool's complexity.

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

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

Schema coverage is 100%, with all parameters documented as aliases for 'question'. Description repeats the schema's natural language description but does not add significant new semantic details beyond the examples. 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?

Explicitly states 'PREFER OVER WEB SEARCH' and lists a wide range of data types (SEC filings, FDA drug data, etc.). Distinguishes from siblings like ask_pipeworx_grounded and deep_research with clear differentiation. Provides concrete examples of questions, 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?

Offers explicit when-to-use guidance, including 'START HERE for most questions' and specific conditions for stepping up to alternatives. Covers both typical use cases and exceptions (e.g., breaking news), ensuring the agent can select correctly.

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 routing across 4,774 tools, argument filling, data fetching, and extraction limited to tool result. Details output format and refusal reasons. Complements annotations (readOnlyHint, openWorldHint) with actionable behavior. 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?

Single paragraph front-loads purpose, then details routing, output, and usage guidance. Every sentence is informative; no repetition or fluff.

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

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

With no output schema, description fully explains return structure and refusal reasons. Covers key aspects: purpose, routing, behavior, use cases, cost. Sufficient 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 aliases. Description adds context that question is natural language and explains how it is used in routing and extraction. Provides semantic 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?

Describes a specific mode ('hallucination-resistant') for high-stakes reads, clearly distinguishing from sibling tool ask_pipeworx by detailing extraction-only behavior and refusal mechanism. Lists concrete 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?

Explicitly states when to use (answers to be quoted/cited/acted on) and when not (casual lookups, prefer ask_pipeworx). Mentions cost trade-off and alternative tool.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds context about API unit consumption and the lack of a regional parameter, which is consistent and helpful, though no additional behavioral traits beyond annotations are disclosed.

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 efficiently includes a list of returned columns and a note. 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?

The tool has no output schema, so the description compensates by listing all returned columns. It covers the input parameters (all documented), the output structure, and a behavioral note about regionality, making it fully complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the description does not need to add parameter meaning. It lists output columns but does not elaborate on parameter usage beyond what the schema provides, meeting the baseline 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 clearly states it returns a backlinks summary for a domain or URL, specifying the resource (backlinks) and action (summary). It also notes the absence of regional filtering, distinguishing it from other tools that might accept a database parameter.

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 implicitly indicates when to use the tool (when needing a backlinks overview) and provides a negative guideline (no regional parameter). However, it does not explicitly differentiate from sibling tools like 'domain_overview' or provide when-not-to-use guidance.

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

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

The description goes far beyond the annotations (which already mark it as read-only, idempotent, non-destructive). It details resolver contract, parent event extractor, news fallback fields, safety short-circuits, closed market handling, wide spread tradeability, and resolution-rule risk. All behavioral traits are disclosed 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 excessively long (several paragraphs) and mixes many details (classifiers, fan-out examples, response shapes, resolver contract, news fields, safety) without clear sectioning. Although front-loaded with the main purpose, it could be significantly condensed for better 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 tool's complexity and absence of output schema, the description covers most essential aspects: input formats, classifiers, fan-out examples, response structure (market, analysis, evidence), resolver behavior, safety mechanisms, closed market handling, wide spread handling, and cancellation rules. It lacks a structured listing of output fields but is otherwise comprehensive.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context (e.g., how depth affects fan-out) but does not significantly extend meaning beyond what the schema already provides for each parameter. The examples in the schema are helpful and aligned.

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 ('Research a Polymarket bet'), the resource ('relevant Pipeworx data'), and the scope ('in one call'). It provides clear use cases and distinguishes from siblings like polymarket_edges by focusing on 'what does the data say' queries.

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

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

The description gives explicit use cases ('Use for should I bet on X, what does the data say about Y, or is there edge in Z') and includes examples. However, it does not mention when not to use the tool or compare it directly to alternatives like polymarket_arbitrage or polymarket_fill_risk, which are sibling tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds rich context: data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, return of paired data with citation URIs, and the fact it makes a parallel call. No contradiction with annotations.

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

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

The description is dense but front-loaded with example trigger phrases. Some redundancy exists (explaining types again after schema), but every sentence contributes useful information. Minor reduction would improve conciseness.

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 explains input, data sources, sorting, and citation URIs. It covers the tool's behavior for both entity types. Could optionally mention rate limits or error handling, but it is sufficient for agent selection.

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 meaningful context: explains what data each 'type' value pulls (latest 10-K for company, FAERS for drug) and clarifies the format for 'values' (tickers/CIKs vs names). This goes beyond the schema's basic enumeration.

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 like 'compare', 'rank', and explains the tool produces side-by-side comparisons of 2–5 companies or drugs. It clearly distinguishes from siblings by stating 'ALWAYS PREFER over sequential single-pack lookups' and mentions replacing 8–15 sequential lookups.

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

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

The description provides explicit usage triggers ('X vs Y', 'which is bigger') and a strong preference over sequential lookups. However, it does not explicitly outline when not to use the tool (e.g., for single entities), leaving this as an implied alternative to entity_profile.

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, open-world, idempotent, non-destructive. The description adds the account requirement, that it's not open-web search, the parallel routing to 4,774 tools, return format with verbatim evidence and gaps, and expected response time (15-60s). 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?

Though lengthy, every sentence adds value. The structure is front-loaded: account requirement, then core functionality, then comparisons, then caveats. 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 complexity (multi-source, parallel execution, account tiers), the description covers all essential aspects: process, output format (findings packet with evidence, confidence, source, fetched_at, citations, gaps), and trade-offs with alternatives. No output schema, but return values are fully 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% with descriptions. The description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8) and clarifies that question should be natural language and broad/multi-part is fine.

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: grounded multi-source research across structured data sources, with decomposition into facets and parallel execution. It distinguishes itself from siblings like ask_pipeworx for single lookups and breaking news.

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 (broad/multi-part questions over structured data) and when not to (single lookup -> ask_pipeworx, breaking news -> ask_pipeworx). Also mentions account requirements and depth limitations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is established. The description adds valuable behavioral context by stating the tool returns '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 goes beyond annotations to clarify the output format and readiness for invocation.

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, provides a comprehensive list of use cases in a single sentence, and explains the return value and recommended usage pattern in a second sentence. No extraneous 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?

Despite no output schema, the description fully explains what the tool returns (top-N tools with schemas, ready to call). Parameter count (6) is well-handled by mentioning aliases. The description covers when to use, what to provide, and what to expect, making it complete for this tool’s complexity.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters (with aliases). The description provides examples of natural language queries and lists domains, which adds some context, but does not significantly extend parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description begins with 'Find tools by describing the data or task,' which is a specific verb+resource. It lists many example domains (SEC filings, financials, etc.), clearly distinguishing it from sibling tools that perform specific data lookups rather than tool discovery.

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 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear context for when to use the tool. However, it does not explicitly state when not to use it or name alternative tools, keeping it from 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 declare readOnly, idempotent, openWorld, and non-destructive, which are consistent. The description adds that it consumes API units, a behavioral trait not in annotations, and explains the return format.

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: first states purpose, second lists columns and API consumption. Front-loaded and efficient 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 return format and API usage, though missing pagination details. Given no output schema and good annotations, it is sufficiently complete for a 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%, but the description adds context: explains _apiKey is BYO and passed as key query param, provides example for domain, and notes default display_limit. 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 states it retrieves organic keywords for a domain with a specific Semrush type, distinguishing it from sibling tools like 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?

No explicit guidance on when to use versus alternatives, though the purpose is clear. The description could mention not to use for paid keywords or competitive analysis.

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 and idempotent hints. The description adds behavioral context by noting that it consumes Semrush API units (a cost aspect) and lists the exact columns returned. This goes beyond annotations, though it omits error handling and rate limits.

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 sentences covering purpose, source, output columns, and a cost caveat. No wasted words, front-loaded with the core function.

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 exists, but the description compensates by listing all returned columns. It also discloses API unit consumption, which is critical for an API-key-based tool. However, it could be more complete by mentioning pagination or data freshness.

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 does not add new parameter details beyond the schema. However, it explains the response column abbreviations, which indirectly aids understanding parameter options (e.g., display_limit's effect). This is marginal extra value, so baseline 3 is appropriate.

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

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

The description clearly states it provides a high-level SEO/PPC summary for a domain, specifying the source (Semrush domain_ranks) and listing all returned columns. This distinguishes it from sibling tools like domain_organic_keywords and domain_paid_keywords, which focus on specific channels.

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 use for a general overview but does not explicitly state when to choose this over siblings like domain_organic_keywords or competitor tools. It mentions API unit consumption, which is a usage caveat, but lacks explicit 'when-to-use' and 'when-not-to-use' guidance.

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

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

Annotations already indicate read-only, idempotent, nondestructive. Description adds 'Consumes your Semrush API units', a key behavioral trait beyond annotations. Could mention data freshness or pagination but adds 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?

Two sentences with no fluff. First sentence defines purpose, second lists output columns. Front-loaded and concise.

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 lists returned columns. Also mentions API units. Lacks error handling or invalid domain behavior, but sufficient for a simple 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?

Schema coverage is 100% with clear parameter descriptions. The tool description adds minimal extra meaning (e.g., 'Semrush type=domain_adwords'). Baseline 3 is appropriate.

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

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

Description clearly states 'Paid (AdWords/PPC) keywords a domain bids on' with specific verb 'returns parsed rows'. It distinguishes from sibling tool 'domain_organic_keywords' by specifying paid vs organic.

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 implies usage for paid keywords but does not explicitly state when to use it or compare with alternatives like 'domain_organic_keywords'. No when/when-not guidance provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds: fans out across multiple data sources, returns specific fields with details (e.g., recent filings with URIs, fundamentals sorted), mentions USPTO patents sunsetting May 2025, and GDELT→GNews fallback. 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?

Well-structured: starts with example queries, then purpose, then detailed return breakdown. Every sentence adds value, though slightly verbose. Could be tightened but remains 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 complex tool with no output schema, description fully explains return values (CIK, filings, fundamentals, patents, news, LEI). Covers edge cases like patent sunset and name vs ticker/CIK. 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 covers both parameters with descriptions (100% coverage). Description adds examples ('AAPL', CIK), reinforces that names are unsupported, and clarifies value formats. This enriches the schema without redundancy.

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 concrete examples and clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes from siblings like 'resolve_entity' for name resolution. The verb is explicit: profile an entity.

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 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view'. Also advises to use 'resolve_entity' first if only a name is available, since names are not supported.

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 behavioral context beyond annotations: it clarifies the type of data (stored memories), reasons for deletion (stale, done, sensitive), and pairs with other tools. Annotations already mark it as destructive and idempotent, and the description aligns 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 two sentences, front-loaded with the action, followed by usage guidance. 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?

For a simple one-parameter delete tool with no output schema, the description covers purpose, usage, and pairing. Missing return value details, but given low complexity, this is acceptable. Slightly incomplete due to lack of outcome description.

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 provides 100% coverage with a clear description for the 'key' parameter. The tool description does not add extra semantic details beyond the schema, but the schema itself is sufficient. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key', with specific use cases. It distinguishes from sibling tools 'remember' and 'recall' by mentioning pairing, 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 provides explicit guidance on when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', though it 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?

The description explains it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. This adds behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), detailing the process and output format.

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 with the first sentence stating the purpose, the second adding technical detail, and the third listing use cases. It is front-loaded, concise, and contains 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 the simple tool (2 parameters, no output schema), the description adequately covers output format ('single text blob ready to drop at site-root/llms.txt') and intended use. It lacks error behavior details but is sufficient for a read-only, idempotent 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?

With 100% schema description coverage, the schema already documents both parameters (url, max_links). The description adds minimal value by mentioning 'any URL' but doesn't elaborate on parameter constraints or formats 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 generates a production-ready llms.txt file for any URL for AI crawlers, specifying the verb (generate), resource (llms.txt file for a URL), and context. This distinguishes it from sibling tools like 'scan_competitor_ai_presence' and 'ai_visibility_check'.

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 examples: getting a client's site indexed, drafting for own project, or auditing a competitor. While it doesn't explicitly state when not to use or name alternatives, the examples give clear context for when the tool is appropriate.

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, not destructive. The description adds beyond: 'Consumes your Semrush API units' (important cost/quota info) and describes the result format. 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?

Two concise sentences: first covers purpose and output, second warns about API units. No filler, front-loaded with key info.

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 3 params (100% schema coverage) and no output schema, the description covers all: purpose, output format, API cost. No gaps remain.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds minimal extra meaning (e.g., 'Semrush type=phrase_this') but the schema already covers phrase, _apiKey, database. 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 explicitly states it retrieves search metrics for a single keyword phrase, lists the returned columns (Ph, Nq, Cp, etc.), and clarifies it's a Semrush type=phrase_this call. This is specific and distinct from sibling tools like domain_overview or backlinks_overview.

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 (e.g., domain_organic_keywords). It is implied it's for a single keyword phrase, but no when-not-to-use or sibling differentiation.

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=true, destructiveHint=false, idempotentHint=true. The description adds value by detailing return fields and noting default behavior (active only) with an optional include_inactive parameter, enhancing 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?

Two sentences with no wasted words. Purpose is in the first sentence, usage in the second. Excellent conciseness.

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 lists return fields. Parameter is explained in context. Tool is simple and description covers all necessary information for correct 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?

Schema coverage is 100% with a single parameter (include_inactive) already described. The description does not add significant parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' and specifies return fields. It distinguishes the tool's purpose but does not explicitly contrast with 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?

Guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear when-to-use context, though it lacks explicit when-not-to-use instructions.

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, open-world, idempotent, non-destructive behavior. The description adds value by disclosing that the tool consumes Semrush API units, a cost implication not covered by annotations. It also describes the returned columns, aiding understanding of output.

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 with no extraneous content. The first sentence conveys purpose and return structure; the second adds a critical usage note. Every word 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 adequately details return columns (Dn, Cr, Np, Or, Ot, Oc). Parameters are fully covered in schema. The description sufficiently informs an AI about what the tool does and returns.

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

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

Schema includes all 4 parameters with descriptions; coverage is 100%. The description adds minor extra context by explaining that _apiKey is passed as the 'key' query param and that it consumes units, which is beyond the schema's own 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 tool returns 'organic search competitors for a domain' and specifies the Semrush API type. It distinguishes from siblings like 'domain_organic_keywords' by focusing on competitor discovery rather than keyword details.

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 it consumes Semrush API units, implying a cost and need for an API key. However, it does not explicitly state when to use this tool versus alternatives like 'domain_organic_keywords' or 'backlinks_overview', leaving usage context implicit.

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

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

The description discloses rate limits ('Rate-limited to 5 per identifier per day'), impact ('signal directly affects roadmap'), and cost ('Free; doesn't count against your tool-call quota'). Annotations indicate non-destructive, non-readonly, non-idempotent behavior, and the description aligns with these traits 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 5 sentences, front-loaded with purpose and usage, followed by behavioral details. Every sentence adds essential information without redundancy, making it highly efficient and easy 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?

Despite lacking an output schema, the description covers what happens after sending (team reads, affects roadmap), rate limits, quota exemption, and feedback types. Given the tool's complexity (nested object parameter), this is complete and leaves no gaps for an agent to safely 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 each parameter is described clearly in the schema. The description adds marginal value by expanding on the enum values (e.g., 'bug = something broke or returned wrong data') and implying the purpose of the context parameter, but does not significantly enhance 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 explicitly states 'Tell the Pipeworx team something is broken, missing, or needs to exist' and enumerates the types of feedback (bug, feature/data_gap, praise), clearly distinguishing this from sibling tools like ask_pipeworx which are for inquiries.

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 conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also instructs how to format feedback ('Describe the issue in terms of Pipeworx tools/packs -- don't paste the end-user's prompt.') and notes rate limits and quota exemption.

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 read-only, open-world, idempotent, non-destructive. Description adds value: data source (CF analytics-engine), no PII, return format, and caching behavior (5min-1h). 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 compact sentences: main function, use cases, data details. No wasted words, front-loaded with key action.

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

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

For a simple read-only trend tool with one param and no output schema, description covers all needed: return content, data source, privacy, caching. Context is complete.

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

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

Only one parameter (window) with full schema coverage. Description adds functional meaning: shorter windows surface hot trends, longer show steady-state demand, beyond enum values.

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 specified windows. It distinguishes from sibling tools by focusing on trending usage among AI agents, not general tool discovery or queries.

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?

Three explicit use cases are provided (discovering hot sources, confirming canonical choice, checking alignment). No explicit when-not-to-use or alternatives, but the enumerated uses give sufficient guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral details: walks child markets, computes partition checks, filters placeholders, and performs fill check against live CLOB depth. 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?

Well-structured with sections and bold labels, but somewhat lengthy. Front-loaded with purpose. Every sentence adds value, but could be slightly more concise without losing 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?

Covers all aspects: modes, output fields (opportunities[], partition_check details), fill check behavior, edge cases (skipped_low_similarity, placeholder filters). No output schema but description compensates adequately.

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

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

Both parameters have schema descriptions (100% coverage). Description adds usage details: event slug examples for event, seed question examples for topic. Explains behavioral differences between modes, adding significant 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?

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from siblings like polymarket_edges by specifying unique methods and modes (trending_scan, event, topic).

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

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

Explicit guidance: call with no args for trending_scan, pass event for specific market, pass topic for cross-event scan. Examples provided for both modes. Also references polymarket_fill_risk for custom sizing, giving clear alternative.

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

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

The description fully discloses behavioral traits beyond annotations: caching (1h KV-level), response structure (three segments, diagnostics), filter interactions (e.g., min_kelly does not filter partition arbs), and assumptions (slippage, lack of fees). No contradiction with readOnlyHint, openWorldHint, idempotentHint, destructiveHint.

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 very long and detailed, covering model families, diagnostics, and parameter knobs extensively. While front-loaded with the purpose, it could be more concise. The structure improves readability with segment headers (MODEL_DRIVEN, etc.), but the sheer length still impacts conciseness.

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 (9 parameters, no output schema), the description is exceptionally complete. It explains the response structure (by_segment, fed_candidates, diagnostics), return fields (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h-move warning), and how each filter works. This fully compensates for the lack of an 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?

Schema coverage is 100% (all parameters have descriptions). The description adds extra context: default values, usage scenarios (e.g., slippage_pp explains Polymarket's typical spread), and clarifications (e.g., min_partition_leg_kelly exists because min_kelly doesn't filter partitions). This exceeds the baseline 3 for high schema coverage.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case of 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage and polymarket_kalshi_spread by its focus on edge detection with multiple model families.

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

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

The description provides clear context for when to use the tool (discovering betting opportunities) and gives guidance on tradeable-edge knobs (e.g., min_liquidity, max_spread_pp). It also notes limitations (e.g., Fed bets surface but are excluded due to unreliable signals). However, it does not explicitly compare to sibling tools or state when not to use this tool over 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, destructiveHint=false. The description adds that it reads snapshots, shows time-series, computes trend and decay, lists expired opportunities, and notes gaps. 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 well-structured with front-loaded core question, details on output format, and limits. While slightly long, every sentence adds value. Could be slightly tighter but 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?

Given simple parameters (2, none required) and no output schema, the description thoroughly explains the output structure (tracked, expired, snapshot_dates) and covers limits and caveats. Complete for the tool's complexity.

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

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

Schema coverage is 100% with both parameters described. The description adds meaningful context: days default 14, max 30 (consistent with schema), and window default '1wk' meaning snapshot family. It provides extra nuance 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 that the tool answers 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling polymarket_edges by being an analysis layer on top of snapshots.

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 context: a fresh wide edge vs. a 3-week-old wide edge are different trades. It also mentions limits like 60-day TTL and snapshot start. However, it doesn't explicitly state when not to use or name 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 details the operational behavior (walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, etc.) and warns about risks such as partial basket fills converting an arb into an unhedged directional position. The annotations (readOnlyHint, idempotentHint) are consistent, and the description adds significant context beyond them.

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

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

The description is relatively long but well-structured with bolded mode names, bullet-like lists, and a clear concluding directive. Every sentence contributes value, and there is no redundant content.

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

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

Despite the lack of an output schema, the description covers all essential aspects: input modes, parameter usage, return fields, risk factors, and practical usage guidance. It is complete enough for an agent to understand what the tool does and 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?

The schema already provides descriptions for all 4 parameters (100% coverage), but the description adds extra meaning: e.g., for 'size_usd' it notes clamping (10–1,000,000) and differentiates the interpretation in basket mode. It also explains the default behavior for 'side' in basket mode.

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 a 'realizable-vs-theoretical edge check' and details two distinct modes (single-market and basket). It explicitly distinguishes itself from sibling tools by stating when to use this tool before acting on polymarket_arbitrage or polymarket_edges signals.

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

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

The description provides explicit guidance on when to use the tool ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains the risks of not using it. However, it does not explicitly state when not to use it, though the positive conditions are 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?

Beyond annotations (readOnly, idempotent), description discloses safety fields, compatibility_warning triggers, temporal_alignment check, and skipped comparisons. No contradictions with annotations. Rich behavioral 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?

Dense but well-organized: purpose, comparison context, modes, response, safety. Every sentence adds value; slightly lengthy but justified by complexity. Front-loaded with key info.

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 3 optional params and no output schema, description fully explains response structure (leg-by-leg, spread array, compatibility_warning, temporal_alignment). Covers edge cases and expected behavior. Complete for a moderately complex tool.

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

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

100% schema coverage already, but description adds substantial meaning: lists exact topic shortcuts, explains how explicit parameters override topic-mapped sides. Goes beyond schema 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?

Clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same question. Distinguishes from siblings like polymarket_arbitrage by focusing on two-venue comparison. Specific verb+resource.

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 describes two modes (topic shortcuts vs explicit tickers) with examples. Warns that most pre-mapped topics return compatibility warnings, setting realistic expectations. Provides guidance on when spreads are meaningful (temporal alignment, comparable bet shapes).

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

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

Adds significant detail beyond annotations: dual behavior (single key vs list all), scope, and pairing with other tools. 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?

Three sentences, front-loaded with main action, no wasted words. Efficient and clear.

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 explains return behavior (value or list). Covers essential aspects for a simple 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% with description of key parameter. Description reinforces and adds context (saved via remember, omit for list) but could have slightly more detail on return format.

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 retrieves a value saved via remember or lists all keys, with specific verb and resource. Distinguishes from sibling tools remember 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 (look up stored context), pairs with remember/forget, and notes scoping to user identifier. Provides both use case 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?

Description adds value beyond annotations by explaining mark_read behavior and return fields. No contradictions with annotations (readOnlyHint, destructiveHint).

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 covering purpose, return fields, filter options, and alternative access. No unnecessary words, front-loaded with action.

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

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

No output schema, but description fully explains return content. Covers all five optional parameters and their use cases. Mentions alternative access method for scripts.

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 each parameter. Description enriches by explaining effect of mark_read on subsequent calls and mentions limit default.

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

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

Description uses specific verb 'Pull' and resource 'fired events from your subscription feed'. It details return fields and filtering options, clearly distinguishing from siblings like 'list_subscriptions'.

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?

States when to use the tool versus the direct endpoint ('Polls work fine; same feed at...'). Provides context on mark_read behavior and unread_only, but does not explicitly list when not to use.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds valuable context: fans out to SEC, GDELT→GNews, USPTO; explains GNEWS rate-limiting fallback; mentions USPTO soft-fail. 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?

Single dense paragraph efficiently conveys purpose, sources, parameter guidance, and alternative. Could benefit from slight structuring (e.g., bullets for sources) but remains concise 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?

No output schema exists, but description explains return structure ('changes[] grouped by source', 'total_changes count', 'pipeworx:// citation URIs'). All required params are documented with usage detail. No gaps for this tool's complexity.

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

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

Schema description coverage is 100%. Description adds meaning beyond schema: explains 'since' format (ISO vs relative) with examples, clarifies 'type' enum limits, and gives example 'value' inputs. Adds typical usage hints.

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's a change feed for a company in a time window, with specific query examples ('What's new with X', 'latest on Y'). Explicitly distinguishes from sibling tool 'entity_profile' which is for static profiles.

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 guidance on when to use this tool vs. 'entity_profile'. Also advises on typical 'since' values like '30d' and explains fallback behavior between GDELT and GNews.

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 idempotentHint, readOnlyHint, destructiveHint. The description adds critical behavioral context: memory is scoped by identifier, persistent for authenticated users, 24-hour for anonymous. 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?

Every sentence serves a purpose. The description is concise, front-loaded with the main action, and efficiently covers usage, scope, and pairing.

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?

All necessary context is provided: persistence details, scoping, and pairing instructions. No output schema needed; description is self-sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'key-value pair' and gives naming examples, adding marginal value 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?

The description clearly states the tool's purpose: saving data for later reuse, and provides concrete examples (ticker, address, preference). It explicitly distinguishes from siblings (recall, forget) by naming 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 specifies when to use the tool ('when you discover something worth carrying forward') and provides explicit guidance on pairing with recall and forget, offering clear 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 mark it as readOnly, openWorld, idempotent, and non-destructive. The description adds that each call cascades through several lookup endpoints, providing useful behavioral context beyond the annotations.

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

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

The description is well-structured with examples upfront and clear delineation of supported types. It is slightly verbose but every sentence adds value; a minor trimming could improve conciseness.

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 specifies return fields (ticker, CIK, company_name, RxCUI, etc.) and mentions citation URIs. It provides sufficient context for the tool's purpose 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% with descriptions for both parameters. The description adds examples (e.g., 'ozempic', 'metformin') and details on accepted input 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 resolves user-spoken names to canonical/official identifiers, with specific examples like ticker, CIK, and RxCUI. It distinguishes from sibling tools by noting it replaces 2-3 manual lookups.

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

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

The description says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance. While it does not explicitly list when not to use it, the examples and context imply appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description's safety profile is clear. The description adds that it probes each entity with ai_visibility_check and returns a ranked list with scores, confidence, signal density. It doesn't mention potential latency or API key handling beyond schema.

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 of description plus a brief example are extremely concise. The critical information is front-loaded in the first sentence ('Compare AI visibility across multiple entities side-by-side'), and the rest adds necessary detail 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?

The tool has 4 parameters and no output schema, so the description must explain both input and output. It does so effectively, listing the return fields (score, confidence, signal density per entity). However, it could be slightly more explicit about the exact structure of the ranked list (e.g., array of objects).

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 significant context: explains that first entity is treated as subject for narrative, that 'models' can be omitted for free default, that _apiKey is only needed if 'anthropic' is used, and that context disambiguates common names. This meaningfully enriches 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 AI visibility across multiple entities, using 'compare', 'probe', 'rank', and 'surface most/least recognized'. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on AI visibility and ranking.

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

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

The description provides a concrete use case (competitive AI-marketing audits) and an example query. It implies use for comparing 2-8 entities but does not explicitly state when not to use it, nor mention alternatives like using ai_visibility_check individually.

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 adds behavioral detail beyond annotations, such as partial failure handling ('sources_failed will list it if it times out, the rest still returns') and timing (first measurement can take 5-30s). Annotations (readOnlyHint, idempotentHint, etc.) are consistent with the described behavior.

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 well-structured, front-loading the core purpose, then detailing use cases, ecosystem scope, and failure behavior. Every sentence adds value, and the length is justified by the tool's complexity.

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

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

Given the tool's complexity (fans out to two services, multiple data fields, partial failures, version handling), the description covers all essential aspects: composite nature, return fields (listed), failure mode, ecosystem restriction, and default version behavior. No output schema exists, but the description sufficiently documents return values.

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 covers both parameters with full descriptions (100% coverage). The tool description mentions defaults and version omission but does not add semantics beyond what is already in the schema. 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?

Description clearly states the tool performs a composite check for npm packages across deps.dev and bundlephobia, answering 'should I add this npm package to my project'. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes from unrelated sibling tools by its unique domain.

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 specifies when to use: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. It also notes limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear guidance on 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 indicate read-only, idempotent, non-destructive. Description adds rich behavioral detail: embedding model (BGE-base-en), chunking (500-char overlapping windows), character limit (200K chars) with truncation and flagging. 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?

Description is well-structured: purpose, usage example, pairing, technical details. Slightly long but each sentence adds value, no fluff. 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?

Given no output schema, description explains return format (passages with offsets and scores). Covers truncation behavior, pairing, and use case. Fully sufficient 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%, baseline 3. But description adds meaningful context: 'Pass the text you already pulled' and 'top-N passages with character offsets and similarity scores', which clarifies the tool's output and usage 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 uses 'Semantic search INSIDE a fetched record' with clear verb and resource. It provides concrete examples like SEC 10-K body and article, distinguishing it from general search or fetch tools. The purpose is 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefits (saves context, returns relevant passages). Mentions pairing with ask_pipeworx_grounded, but no explicit when-not-to-use. Still, good guidance.

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

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

Beyond annotations, the description details account requirements, delivery channel constraints (phone verification, SMS cap, webhook signing secret), and that subscriptions are mutable. Annotations indicate idempotentHint=true but description does not explicitly confirm idempotency, though 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 fairly long but well-structured with clear sections for purpose, requirements, types, and delivery. Every sentence adds necessary detail; however, it could be slightly more concise without losing 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 complexity (3 parameters, nested objects, enums, no output schema), the description covers all aspects: authorization, type-specific params, delivery channels, constraints, and return value behavior (subscription ID, webhook secret). No gaps are apparent.

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 significant value by explaining each subscription type with examples, item codes, delivery options, and constraints (e.g., phone verification, webhook secret). This goes 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's purpose: 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns a subscription ID. This distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 creating subscriptions but does not explicitly contrast with alternatives (e.g., list_subscriptions for viewing, unsubscribe for deleting). It provides prerequisites (OAuth account required) but lacks 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=false, providing a solid safety profile. The description adds valuable behavioral context: it's the onboarding entry point, returns example questions with tool/argument shapes from the live catalog, and explains parameter behavior (no args = full spread, topic = focused). 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 somewhat long but well-structured. It front-loads the key phrases and uses a bullet-like list of categories. Every sentence adds value, though a slightly more condensed version could exist. It is appropriately sized for the tool's 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 the tool's simplicity (1 optional parameter, no output schema), the description covers all necessary context: purpose, when to use, parameter semantics, and expected return value (category-bucketed example questions with tool shapes). It fully compensates for the lack of an 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?

Schema coverage is 100% with a clear description for the 'topic' parameter. The description enriches this by providing concrete examples ('finance', 'pharma', 'betting') and listing the allowed focus areas, which 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's purpose: it returns category-bucketed example questions that show what Pipeworx can answer, including the exact tool and argument shapes. The title 'What Can I Ask Pipeworx?' is descriptive and the description lists all categories. It distinguishes itself from siblings like ask_pipeworx by being the onboarding discovery tool.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains when to omit the topic parameter for full spread versus passing a specific topic to focus. Lists sibling meta-tools for further reference.

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 reveals that the row is deactivated, not deleted, and historical events remain available. Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true; the description adds context about ownership and data persistence 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 concise with two sentences, front-loading the action and key constraints, and contains 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 the tool's simplicity (one parameter, no output schema), the description adequately covers behavioral aspects (ownership, deactivation) and provides sufficient context for correct invocation.

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

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

Schema coverage is 100% with a single parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds no further parameter detail, meeting the baseline expectation.

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 a subscription by id', specifying the verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 notes ownership enforcement ('you can only cancel your own subscriptions'), providing a key constraint. However, it does not compare with alternative tools or mention 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?

The description adds significant behavioral context beyond the annotations: it explains the return verdicts, extracted structured form, and that it replaces 4-6 sequential calls. Annotations indicate read-only, idempotent, and open-world, which are consistent.

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 but informative, front-loading the core purpose and examples. 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?

Despite no output schema, the description fully explains the return values (verdict type, structured form, actual value with citation, percent delta) and the domain scope, making the tool behavior completely clear.

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 only parameter (claim) with a clear description, high coverage (100%). The description adds value by providing natural-language examples and confirming the format, so it goes beyond mere schema repetition.

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 ('validate', 'verify') and resources (factual claims against authoritative sources) and distinguishes itself from siblings by explicitly stating it replaces 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?

Provides clear usage context ('Use whenever the agent needs to check whether something a user said is factually correct') but does not explicitly list alternatives or exclusions beyond the domain limitation to company-financial claims.

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