Serpapi

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds value by revealing billing behavior (free default, BYO key for Anthropic) and response structure (per-model scores). No contradictions.

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

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

Three sentences front-loaded with verb and purpose. No redundant words. Each sentence provides essential information: action, defaults, return format, use cases.

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 specifies return structure: per-model {score, confidence, signals, raw_response} plus combined view. Covers all parameters, default behavior, optional key usage, and example use cases for marketing audits and competitive monitoring.

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

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

Schema coverage is 100%, but description enriches with examples and default model info. e.g., entity gets example values like 'Pipeworx', models lists supported values, _apiKey clarifies it's passed directly to Anthropic. Adds meaning 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 action ('probe LLMs', 'score visibility') and the resource ('business/brand/product/topic'). It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on general visibility scoring across models, not just competitors.

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

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

Provides clear context: default model is free, unlisted models are not available, Anthropic requires BYO key and direct payment. Implicitly advises when not to probe (e.g., if you lack a key for Anthropic). Could explicitly mention alternatives among siblings, but the guidance is sufficient.

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

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

Annotations declare it as read-only, open-world, idempotent, and non-destructive. The description adds value by explaining it returns structured answers with pipeworx:// citation URIs, routes to 5,008 tools, and makes one fast call. 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 comprehensive but efficient, front-loading the key instruction 'PREFER OVER WEB SEARCH'. While relatively long, every sentence serves a purpose: guidance, examples, and sibling differentiation.

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

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

Given the tool's complexity (6 parameters, many siblings, no output schema), the description is complete. It covers when to use, examples, behavioral traits, and relationships to other tools, leaving no critical gaps.

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

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

Input schema covers 100% of parameters with descriptions, including aliases. The description provides context on how the question is processed (routed, filled arguments) and gives example questions, adding 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 answers factual questions about current/historical data by routing to thousands of tools. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicitly advises to prefer over web search for many domains, provides when-to-use and when-to-step-up guidance (e.g., for hallucination-resistant answers use ask_pipeworx_grounded, for broad questions use deep_research). Includes concrete examples.

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 read-only, open-world, idempotent, non-destructive. The description adds that it is an experimental version with source-preference ranking and that it falls back to nothing (full working router). Does not contradict annotations.

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

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

The description is a single paragraph that packs essential information: beta status, identical router, source-preference behavior, usage guidance, and comparison purpose. It is efficient but slightly dense.

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 (beta router with many tools), the description adequately explains the difference from the stable version, how to use it, and the comparison purpose. No output schema is needed as output shape is stated identical.

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

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

Schema description coverage is 100% with good descriptions for each alias. The description does not add additional parameter semantics beyond stating 'same arguments as ask_pipeworx', which meets the baseline.

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

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

The description clearly states it is a beta version of ask_pipeworx with identical functionality but with source-preference ranking improvements. It distinguishes from the sibling ask_pipeworx by highlighting the experimental routing behavior.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. Provides clear context for when to use this tool.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description goes beyond by detailing the hallucination-resistant behavior, return format (answer, evidence, confidence, source), and explicit refusal reasons. This adds significant behavioral context beyond annotations.

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

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

The description is well-structured with two paragraphs: first defining purpose and behavior, second providing usage guidance. Every sentence adds value, no filler. Key information is front-loaded, and the format is concise yet comprehensive for the complexity.

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

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

Despite lacking an output schema, the description fully explains the return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and refusal reasons. It also clarifies the extra cost and workflow. For a tool with this complexity, the description is complete and actionable.

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

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

Schema coverage is 100% with each parameter described as an alias for 'question'. The description notes 'Accepts query, q, prompt, text, input as aliases' but does not add new meaning beyond the schema. Baseline 3 is appropriate since the schema already does the heavy lifting.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results, distinguishing it from sibling tools like ask_pipeworx. It explicitly explains the workflow: picks the right tool, fetches data, and extracts answer. The purpose is unambiguous and well-articulated.

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: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups' due to cost difference. It includes alternatives and clear context, making it easy for an agent to decide when to invoke this tool.

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

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

The description goes far beyond the annotations (which already declare readOnlyHint, idempotentHint) by detailing market resolution, fan-out behavior, safety short-circuits, closed market handling, wide spread warnings, and resolution rule risk. No contradictions with annotations.

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

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

The description is quite long (several paragraphs) but well-structured with clear sections. It is front-loaded with the main purpose, though some details could be condensed 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?

Despite having no output schema, the description comprehensively covers all input parameters, return fields, edge cases (low confidence, closed markets, wide spreads), and error states (fallback, cancellation rules). No gaps identified.

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

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

Schema coverage is 100%, and the description adds meaningful context: explains depth enum values, market input variations, and include_raw default with rationale. This adds value beyond the schema alone.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, with specific examples of inputs and outputs. It is a specific verb-resource pair, but does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, though the purpose is distinct.

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

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

Explicitly states 'Use for...' with three concrete scenarios (should I bet, what does data say, is there edge). Does not mention when not to use or alternatives, but the provided contexts are clear and helpful.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). No contradiction with annotations; description enriches 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?

Description is relatively long but front-loaded with example queries that immediately convey use cases. Every sentence adds value, though it could be slightly more concise. The structure is effective for an AI agent.

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

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

No output schema, but description briefly states returns 'paired data + pipeworx:// citation URIs per entity'. It covers main behaviors for both types and sorting. For a tool with simple parameters and no nested objects, this is adequate but could elaborate more on output structure.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond schema: explains what data each type ('company' vs 'drug') retrieves, gives concrete examples of values (tickers/CIKs for company, drug names), and clarifies constraints (2-5 items, max 5). This makes parameters much more usable.

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 does 'side-by-side comparison of 2–5 companies or drugs' with specific data sources (SEC EDGAR for companies, FAERS for drugs). It provides example queries and distinguishes itself from sequential single-pack lookups, making the purpose highly specific and distinct from siblings.

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

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

Description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups' and gives concrete example queries. While it doesn't list specific sibling tool names to avoid, it clearly indicates when to use (comparing entities) and implies when not to use (when not comparing). The guidance is strong but lacks explicit exclusions.

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

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

Discloses account requirements, parallelism, expected timing (15-60s, thorough up to ~90s), depth behaviors (gap recovery, contradictions, lead chasing), citation format, and excerpting. Annotations (readOnlyHint, etc.) 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?

Very detailed and informative but somewhat verbose. Front-loaded with critical info (account required, alternative). Every sentence adds value, but could be slightly more 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?

Covers all necessary context: account requirements, alternatives, scope, parallelism, return packet, gap handling, best use cases, depth behaviors, timeouts, contradictions, excerpting. No output schema, but description compensates thoroughly.

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?

Description adds substantial context beyond the schema: explains depth enum values with detailed effects (quick=3 facets, standard adds gap recovery+contradictions, thorough adds iterative hop+contradictions) and that question is natural language. Schema coverage is 100% but description enriches it.

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 performs grounded multi-source research across 1318 structured data sources, distinguishes from ask_pipeworx and other siblings. Verb 'research' and resource 'structured data sources' are specific.

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

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

Explicitly tells when to use (broad/multi-part questions over structured data) and when not (single lookup use ask_pipeworx, breaking news prefer ask_pipeworx). Also mentions account requirements and depth tiers.

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, destructiveHint=false. Description adds that results are 'ready to call directly, no second schema lookup needed,' which is useful 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?

The description is concise and front-loaded with the core purpose. However, it lists many example domains which could be more concise. Every sentence adds value, but slightly verbose.

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

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

Given no output schema, the description explains what is returned: 'names, descriptions, and full input schemas (with curated examples).' This is sufficient 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 descriptions for each parameter. The description mentions the query parameter and examples but does not add significant 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 clearly states 'Find tools by describing the data or task.' It specifies the action (browse, search, look up, discover) and the resource (tools). It distinguishes this tool from siblings by being the 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 'Call this FIRST when you have many tools available and want to see the option set.' Provides clear context for use, but no explicit when-not-to-use or alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it fans out across multiple sources in parallel, returns specific fields (cik, recent_filings with URIs, fundamentals sorted, patents, news, LEI), and notes that the USPTO PatentsView API sunset May 2025 causes soft-failure. No contradictions with annotations.

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

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

The description is lengthy but every sentence adds value. It is front-loaded with example queries and an imperative usage guideline ('ALWAYS PREFER'). While it could be slightly more concise, it efficiently packs critical information about sources, return structure, and caveats.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description is exceptionally complete. It enumerates return fields (cik, recent_filings with sample URI format, fundamentals sorted by period_end, patents, news, LEI), notes the patent sunset, and specifies input constraints. No significant 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%, but the description adds meaning beyond the enum and string types. It clarifies that 'value' must be a ticker (e.g., 'AAPL') or zero-padded CIK (e.g., '0000320193'), and that 'type' currently only supports 'company'. This provides formatting guidance not present in the schema.

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

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

The description clearly states the tool creates a cross-source profile of US public companies, provides example queries ('Tell me about X'), and distinguishes from sibling tools by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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?

It explicitly states when to use (when user asks for a holistic view) and when not to (if only name, use resolve_entity first). The description also names alternatives ('chaining single-pack SEC/XBRL/news lookups') and provides clear criteria for input (ticker or zero-padded CIK).

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about deleting 'previously stored' memories and clearing sensitive data, aligning well with annotations.

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

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

Two sentences, front-loaded with action. Every sentence adds value: purpose, usage guidance, and relationship to sibling tools. No fluff.

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

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

Given the tool's simplicity (1 required param, no output schema, annotations present), the description covers what it does, when to use it, and how it relates to other tools. Could mention what happens on success/failure, but not necessary for this context.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add extra information about the 'key' parameter beyond what schema describes ('Memory key to delete').

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 action 'Delete' and resource 'previously stored memory by key'. It distinguishes from sibling tools 'remember' and 'recall' by mentioning them, implying different purposes.

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 gives three usage scenarios: stale context, task done, clearing sensitive data. Lacks explicit 'when not to use', but 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?

Describes the process (fetches, extracts, emits) and output format (single text blob, standard markdown), which adds value beyond the annotations (readOnly, idempotent) and is consistent with 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?

Few sentences, front-loaded with main action, no unnecessary words. Every sentence earns its place.

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

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

Given no output schema, description fully explains output format and process. Parameters are clear. Complete for a simple 2-param tool.

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

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

Schema coverage is 100%, so baseline is 3. Description repeats schema info (e.g., 'Full URL', 'Maximum number of link entries') without adding new meaning, so no extra value.

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

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

Description starts with a clear verb 'Generate' and resource 'llms.txt file' for any URL, distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence which have different purposes.

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

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

Explicitly lists three use cases (getting a client's site indexed, drafting for own project, auditing competitor), providing clear guidance on when to use, though no explicit when-not-to-use or 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 provide readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds minimal extra info (default active subscriptions) but does not contradict or significantly extend behavioral disclosure.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. Efficient, front-loaded, and no unnecessary words.

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

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

For a simple list tool with one optional param and no output schema, the description fully covers purpose, usage, and return fields. Annotations further complete the context.

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

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

Schema has 100% coverage for the single boolean parameter. The description implies default behavior (active only), adding meaning beyond schema. A clear improvement over baseline 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?

Clearly states it lists the caller's active subscriptions and enumerates return fields. Contextually distinguishes from sibling 'subscribe' and 'unsubscribe' by mentioning use for finding an id to cancel.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This directly links to sibling tools and gives clear context.

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

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

The description adds significant behavioral context beyond annotations: it reveals rate limits (5 per identifier per day), that it's free and doesn't count against tool-call quota, and implies it is a one-way submission (non-destructive, non-read-only). No contradictions with annotations.

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

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

The description is concise and well-structured, with front-loaded purpose and efficient sentences that maximize information without waste. Every sentence adds value.

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

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

The description fully covers the tool's usage, including input guidance, constraints, and expected behavior. Given the complexity of three parameters (including nested objects) and no output schema, the description is comprehensive and leaves no ambiguity for an AI agent.

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

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

Despite 100% schema description coverage, the description enriches parameter understanding by explaining enum values in detail, summarizing the context object, and providing formatting guidance for the message field (e.g., be specific, 1-2 sentences, 2000 chars max).

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

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

The description clearly defines the tool's purpose: sending feedback to the Pipeworx team about bugs, feature requests, data gaps, or praise. It distinguishes itself from siblings by specifying its unique feedback role, with no overlap with other tools.

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

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

The description explicitly states when to use the tool for each feedback type (bug, feature/data_gap, praise) and provides instructions to describe issues in terms of Pipeworx tools/packs, avoiding end-user prompts. It also notes rate limits and quota-free status.

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. The description adds valuable behavioral context: 'derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' 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 highly concise: one opening sentence defining functionality, three bullet use cases, and a brief technical note. 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?

For a simple read-only tool with one parameter, the description covers return values (top tools, packs, total call volume), caching, PII absence, and window semantics. No output schema is needed; the description is sufficiently complete.

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

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

Schema coverage is 100% for the single parameter 'window' with enum. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose appropriately.

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 the top tools, top packs, and total call volume over a recent window.' The verb is specific ('Returns') and the resource is well-defined. It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by emphasizing it's an aggregated trend signal.

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

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

Three explicit use cases are listed (hot data sources, confirming canonical tool, aligning use case). It explains window selection: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' No explicit exclusion or alternatives mentioned, but the context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true; description adds deep behavioral context: details of monotonicity checks, partition_sum, Jaccard similarity threshold, placeholder filtering, fill check with 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?

The description is dense and informative, front-loading purpose. However, it is somewhat verbose, especially in explaining SEMANTIC ANCHOR and PARTITION FILTER; could be more structured. Still, every sentence adds value.

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

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

No output schema, so description fully explains response format (opportunities[], partition_check, fill check results). Covers all aspects of usage, including edge cases (placeholder slugs, realizable edge ≤ 0). References sibling tool for custom sizing. Very complete for a complex tool.

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

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

Schema description coverage is 100% with brief descriptions. The tool description adds substantial meaning: explains behavioral differences between event and topic modes, gives examples of slugs and seed questions, and details inner workings (walks child markets, computes partition_check, flattens markets).

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_fill_risk and polymarket_edges.

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

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

Explicit guidance: 'Call with NO args for a trending_scan', 'pass event for a specific market', 'pass topic for cross-event scanning.' Recommends event mode for specific markets. Also explains when not to trade (realizable_edge_pp ≤ 0) and references a sibling tool for custom sizing.

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 label the tool as readOnly, openWorld, idempotent, and non-destructive. The description goes far beyond this by detailing the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), their internal logic (e.g., partition_overround with per-sport α, concentrated_longshot gate conditions), response structure (by_segment, diagnostics), caching behavior, and caveats (Fed bets excluded due to unreliable signal). No contradictions with annotations.

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

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

The description is long but well-structured, with clear sections (purpose, model families, response, knobs). It is front-loaded with the main purpose. While verbose, every sentence adds value for an AI agent needing to understand the tool's behavior and parameters. Could be trimmed slightly, but the detail 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 (9 parameters, three model families, nested response with diagnostics, caching, and Fed bet exclusion), the description is comprehensive. It covers response structure (by_segment, fed_candidates, _diagnostics), cache duration (1h keyed on knobs), and explains edge_pp_net, kelly fractions, and slippage. The absence of an output schema is compensated by detailed description of 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining how parameters interact (e.g., min_kelly does not filter partition overround opportunities, min_partition_leg_kelly is the correct knob for that) and providing context on when to adjust defaults (e.g., slippage_pp notes Polymarket has zero fees but spread takes 20-50bp). This extra semantic guidance justifies a score above baseline.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This specific verb-resource combination distinguishes it from sibling tools like polymarket_arbitrage, which likely focuses on pure arbitrage rather than Pipeworx-based edges. The emphasis on 'what should I bet on today' further clarifies its discovery-oriented role.

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: for discovering betting opportunities without paging through hundreds of markets. It also mentions tradeable-edge knobs and filters, implying usage scenarios. However, it does not explicitly mention when not to use it or compare directly to alternatives like polymarket_edge_tracker or polymarket_fill_risk, which are listed as siblings.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint=false. The description adds rich behavioral context: limits (60-day TTL, decay numbers from daily closes), response structure (tracked[], expired[], snapshot_dates[]), and field semantics (edge_pp_net signed by trade direction). 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 front-loaded with the core purpose, followed by detailed response fields. It is moderately concise; each sentence adds value, though the response structure explanation is somewhat verbose. Could be slightly trimmed but overall well-organized.

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

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

No output schema is provided, so the description fully explains the response shape (tracked[], expired[], snapshot_dates[]) with field details. It also covers limitations and data sources. For a complex time-series telemetry tool, this is highly complete.

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

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

Schema description coverage is 100%, with clear descriptions for both parameters. The description enhances by adding defaults (days: 14, window: '1wk'), clamping range (2-30 days), and explaining the 'snapshot family' concept (window parameter). This adds meaning beyond the bare 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It distinguishes from siblings like 'polymarket_edges' by focusing on historical persistence and decay, using specific verbs ('answers how long has this edge existed and is it shrinking?').

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

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

The description implies usage context by stating that 'a fresh wide edge and a 3-week-old wide edge are different trades,' guiding when to use this tool for historical analysis. However, it does not explicitly mention when not to use it or list alternative tools like 'polymarket_edges' for current data.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds substantial behavioral detail: walks the order book ladder, returns specific metrics (slippage, fill rate, verdict), and warns about forced directional risk. No contradiction with annotations; the description complements 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 long but well-structured with bold section headers (SINGLE-MARKET, BASKET) and bullet-like output lists. It front-loads the key purpose and constraints. Every sentence adds value, though some detail could be condensed. Still highly effective for a complex tool.

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

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

Given the tool's complexity (two modes, multiple outputs, risk aspects) and lack of output schema, the description is thorough. It covers prerequisites, numerical thresholds, return fields for both modes, error conditions (thin legs, forced directional risk), and references sibling tools for context. No gaps.

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

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

With 100% schema coverage, baseline is 3. The description adds meaning beyond schema: explains mode selection (market vs event), default behaviors (side auto-detect for basket, size default 1000 with clamp), and different size interpretations in single vs basket mode. This goes 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly lists outputs for each, making it distinct from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (partial fills cause directional risk) and implies when not to use (small trades, after execution). This is highly actionable.

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

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

The description discloses extensive behavioral details beyond annotations: it explains the two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields, and conditions for meaningless spreads (non-equivalent bet shapes, temporal misalignment). No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is verbose (over 250 words) with extensive details that could be condensed or moved to external documentation. However, it is well-structured with clear sections and front-loaded purpose, so it remains usable despite wordiness.

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

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

Given the complexity of cross-venue spread analysis and the absence of an output schema, the description covers all necessary aspects: modes, response fields, safety checks, compatibility warnings, temporal alignment, and skipped comparisons. It provides a complete understanding for correct usage.

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 value by explaining the two modes, listing the 10 pre-mapped shortcuts, and providing example tickers for explicit parameters. This enriches the semantic understanding beyond the schema's basic descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like 'polymarket_arbitrage' by specifying cross-venue comparison and provides two operational modes (topic shortcuts and explicit tickers), making the purpose unambiguous.

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

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

The description explicitly explains when to use each mode, includes safety fields with detailed warnings (compatibility_warning, temporal_alignment, skipped comparisons), and cautions that pre-mapped topics often yield compatibility warnings. This provides clear guidance on appropriate use and 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, idempotentHint, destructiveHint. Description adds useful context: scoping by identifier, the two operational modes (retrieve vs list), and the pairing with remember/forget. These details go beyond annotations without contradiction.

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

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

Two efficient sentences that front-load the core purpose, followed by use-case context and scoping. No superfluous words or redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all necessary aspects: both modes of operation, scoping, and relationship to sibling tools. It is fully adequate for an agent to use this tool correctly.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description essentially restates that schema information (retrieve or list), but adds no new semantic detail about the parameter itself beyond the scoping context which is more behavioral. 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 the tool retrieves a value by key or lists all keys when omitted. It identifies the verb 'Retrieve' and the resource 'saved memory', and distinguishes from siblings 'remember' and 'forget' by name.

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

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

Explicitly states when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch'. Provides context about scoping (anonymous IP, BYO key hash, account ID) and pairs with 'remember' and 'forget' as complementary 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 declare readOnlyHint, idempotentHint, and destructiveHint, which are consistent with the description. The description adds behavioral details: mark_read flag to acknowledge events, and that each alert carries specific fields. This goes beyond annotations and provides useful operational context.

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

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

The description is four sentences, each concise and informative. It front-loads the main purpose, then adds details on fields, filtering, mark_read behavior, and an alternative access method. No fluff or repetition.

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

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

The tool has five optional parameters and no output schema. The description covers the return fields (source, citation_uri, raw event payload) and key behaviors like filtering and mark_read. While it doesn't mention pagination or empty results, the limit parameter and polling suggestion are covered. It's adequately complete for an AI agent.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by giving concrete examples (e.g., type 'sec_8k'), clarifying that since uses ISO timestamps, and explaining the effect of mark_read on subsequent calls. This enriches the parameter meaning beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifies the return fields (source, citation_uri, raw event payload), and explains filtering options. It distinguishes itself from sibling tools like list_subscriptions, which likely list subscriptions, not events.

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 that polling works fine and notes an alternative HTTP endpoint for scripts/dashboards, giving some usage guidance. However, it could be more explicit about when to use this tool versus others in the sibling list, such as suggesting it for chat-based retrieval vs. direct API access.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds rich behavioral details: parallel fan-out to multiple sources, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail, structured return with citations.

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 moderately long but well-structured: starts with example queries, then function definition, then alternative tool. Each sentence adds value; could be slightly tighter but still 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?

Despite lacking output schema, the description compensates by detailing return structure (changes grouped by source, total_changes, URIs), sources, fallback, error handling, and parameter formats. Complete for a tool with 3 required params.

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 coverage, the description still adds value: explains `since` format (ISO or relative with examples), restricts `type` to company, and clarifies `value` accepts ticker or CIK. Suggests typical monitoring window.

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

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

The description clearly states the tool is a change feed for a company over a time window, listing specific sources (SEC, GDELT, GNews, USPTO) and explicitly distinguishes from entity_profile 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 to use this for dynamic changes vs entity_profile for static profiles. Also suggests typical 'since' values ("30d" or "1m") 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?

Description adds behavioral context beyond annotations: scoping by identifier, persistence differences between authenticated and anonymous sessions. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Concise 4-sentence description that front-loads purpose. Every sentence contributes meaningful information without redundancy.

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

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

For a simple 2-parameter tool with annotations, description is complete: explains purpose, usage context, persistence behavior, and related tools.

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

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

Schema coverage is 100% with descriptions for each parameter. Description adds context by framing key-value as 'memory' and mentioning pairing with recall/forget, but does not elaborate on parameter values 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 clearly states the tool saves data for later reuse, uses specific verb 'save' and resource 'data as key-value pair'. Explicitly differentiates from siblings recall and forget.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides context for persistence and mentions complementary tools (recall, forget) for further actions.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: it cascades through several lookup endpoints internally, replacing multiple manual steps, and describes the specific return data for each entity type (e.g., ticker, CIK, citation URI for companies; RxCUI, ingredient, brand for drugs). No contradictions with annotations.

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

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

The description is front-loaded with attention-grabbing examples, then states the core purpose, usage guidance, and detailed type breakdowns. Every sentence adds unique value, and the structure is logical. It could be slightly more concise (e.g., reducing repeated examples), but overall it is well-organized and 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 the tool's moderate complexity (2 parameters, enum, no output schema), the description covers input formats, resolution process, and return values for each type, including important details like citation URIs. It does not explicitly mention error behavior, but for a lookup tool this is acceptable. The description is complete enough for an agent to use the tool correctly.

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

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

Both parameters are fully described in the schema (100% coverage). The description enriches the 'value' parameter by providing concrete examples for each type (e.g., 'AAPL', '0000320193', 'ozempic'), clarifying accepted formats for company and drug entities. It also explains the 'type' parameter's role in selecting the resolution path. This goes beyond the basic 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: resolving a user-spoken name to a canonical/official identifier. It provides concrete examples ('ticker for...', 'CIK for...', 'RxCUI for...') and distinguishes itself from siblings by emphasizing it should be used first when needing an ID. The supported types and their specific outputs are enumerated.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear context for when to invoke this tool. It also notes that using resolve_entity replaces 2-3 manual lookups. While it does not list explicit alternatives or when-not-to-use scenarios, the instruction to use it first implicitly guides the agent away from other tools until an ID is obtained.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: it ranks by score, surfaces most/least recognized, returns score/confidence/signal density, and internally uses ai_visibility_check. 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 three sentences, front-loaded with the core action. Every sentence is meaningful: purpose, method, example use, and output specification. 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?

With no output schema, the description explains what is returned (ranked list with score, confidence, signal density). Parameters are fully covered in schema and description adds context (default model, subject role). The tool's behavior and output are well-specified.

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

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

Schema description coverage is 100%, each parameter has a description. The description adds further meaning: models default to 'workers-ai', first entity in the array is treated as 'subject' for narrative, context disambiguates common names. This extra context raises it above baseline 3.

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

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

The description uses specific verbs ('compare', 'probes', 'ranks', 'surfaces') and clearly states the tool compares AI visibility across multiple entities using ai_visibility_check, with a ranked output. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description explicitly states it is useful for competitive AI-marketing audits and gives an example question. However, it does not provide explicit when-not-to-use guidance or list alternatives beyond implying it uses ai_visibility_check.

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 and idempotent. The description adds that it fans out to multiple services, returns a structured summary, warns that bundlephobia's first measurement can take 5-30s, and explains graceful partial failure with sources_failed.

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 thorough and front-loaded with purpose, but is somewhat long. However, every sentence adds value and the structure is logical, covering purpose, usage, return fields, and limitations.

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 details all return fields (summary block, per-advisory detail, links, alternative versions) and mentions partial failure behavior. It is fully comprehensive for the agent.

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

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

Schema coverage is 100%, so the description adds minimal additional meaning. It restates that package is npm package name and version defaults to latest, which is already in the schema. Baseline is 3.

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

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

The description clearly specifies that the tool performs a composite check for npm packages across deps.dev and bundlephobia, answering questions about safety, popularity, and size. It distinguishes itself by stating NPM ecosystem only in v1 and mentioning fallback for other ecosystems.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', and provides a when-not by stating which ecosystems it does not cover and directing to deps.dev:version directly.

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 embedding model (BGE-base-en), similarity method (cosine), windowing (500-char overlapping), character limit (200K with truncation flag), and that returned passages include offsets for verification. No contradiction with annotations.

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

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

Description is 4 sentences, front-loaded with core purpose, then usage guidance, pairing, and technical details. No fluff, every sentence adds value.

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

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

Covers return format (top-N passages with offsets and scores), truncation behavior, pairing with sibling tool, and technical details. No output schema needed due to thorough 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?

Schema coverage is 100% and already provides clear parameter descriptions. The tool description adds contextual examples for the query parameter and clarifies the source of the text, slightly 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 performs semantic search inside a fetched record, differentiating from siblings by specifying it operates on already-pulled text. It uses specific verbs and resources, and pairs with ask_pipeworx_grounded.

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

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

Explicitly says to use when the record is too large for the prompt, and mentions pairing with ask_pipeworx_grounded for grounded answers. Provides clear when-to-use and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the output fields and the requirement for an API key. It does not disclose any additional behavioral traits beyond what annotations provide, but the example and field list are helpful 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?

Three sentences, front-loaded with purpose, and an illustrative example. Every sentence is essential and there is 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 search tool with 3 parameters and no output schema, the description is complete. It explains what the tool does, what it returns, and provides a usage example. No additional context is needed.

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

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

Schema coverage is 100%, so the description doesn't need to add much. The description provides an example call that demonstrates the parameters in use, which is helpful but doesn't add new semantics beyond the schema descriptions. Baseline is 3 for high coverage.

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

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

The description clearly states 'Search Google Jobs for <query>' and lists the returned fields (title, company, location, etc.). The name 'serpapi_google_jobs' plus the description effectively distinguish it from siblings like serpapi_google_maps or serpapi_google_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?

The description provides an example usage with parameters, showing when to use it. While it doesn't explicitly state when not to use it or mention alternatives, the sibling tools are clearly different, and the purpose is straightforward. A slight improvement would be to add a note about when to prefer this over other job search 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 the tool as readOnly, idempotent, and non-destructive. The description adds context by listing return fields (name, address, rating, etc.) and showing an example, which complements the annotations without contradicting them.

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

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

Two sentences plus an example. The purpose is front-loaded, and every part adds necessary information. 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?

Despite missing an output schema, the description lists the return fields. It covers input parameters thoroughly. For a simple query tool, it is largely complete, though additional context on pagination or result limits could enhance it.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by providing the exact format for the 'll' parameter (latitude,longitude,zoom) and a concrete example, clarifying usage beyond the schema descriptions.

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

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

The description clearly states it finds local businesses on Google Maps, specifying the resource and action. It distinguishes from sibling tools like serpapi_google_jobs or serpapi_google_news by focusing on maps and business data.

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 local business queries but does not explicitly state when to use this tool over alternatives like general search tools. No when-not-to-use guidance is 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 and idempotentHint, so the description's behavioral additions are minimal. It adds the output fields and an example, but no extra details like rate limits or error handling.

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

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

The description is two sentences plus an example, with no wasted words. It is front-loaded with the core purpose and includes a practical example.

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 lists the fields returned (headline, source, link, date, snippet). It also states the required and optional parameters, making it fully informative for a simple search tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds value by showing an example usage with parameters, reinforcing their purpose and 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?

The description clearly states it searches Google News and returns specific fields (headline, source, link, date, snippet). It includes an example and is distinguishable from sibling tools like serpapi_google_jobs.

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 does not provide guidance on when to use this tool versus other search tools like serpapi_google_jobs or serpapi_google_maps. No explicit context for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not need to repeat these. It adds value by describing the return data (title, link, snippet, etc.) and the API call pattern, providing 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 extremely concise: two sentences plus an example. It is front-loaded with the purpose, and every sentence provides useful information without fluff.

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

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

Given the rich annotations and full schema coverage, the description is complete. It explains what the tool does, what parameters are needed with an example, and what results to expect. No output schema is needed for this simple search tool.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description compensates by providing a concrete example call (e.g., q: 'graph neural networks', as_ylo: 2020, num: 10) and clarifying that _apiKey is required, adding practical semantics beyond the schema.

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

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

The description clearly states the tool searches Google Scholar for academic papers on a topic, specifying what is returned (title, link, snippet, publication info, citation count). It uniquely identifies its resource (Google Scholar) contrasting with sibling tools like serpapi_google_jobs.

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 a clear usage context (searching academic papers) and includes an example call. However, it does not explicitly mention when not to use or list alternatives among the many sibling search tools, but its purpose is self-evident.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by indicating it's a search operation. Additionally, it lists the return fields (title, price, etc.), adding behavioral transparency without contradicting annotations.

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

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

The description is a single sentence with a clear structure: purpose followed by an example. It is front-loaded with the main action and includes all essential information without any unnecessary text.

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

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

Given the lack of an output schema, the description compensates by listing the returned fields (title, price, source, rating, reviews, product ID, link). Parameters are fully described in the schema, and annotations cover safety. The description is complete for an agent to invoke the tool correctly.

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

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

The input schema has 100% coverage for parameters, so the description naturally does not need to add much. However, the example provides a concrete usage pattern that demonstrates how parameters are combined, which adds value beyond the schema.

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

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

The description clearly states it searches Google Shopping for a query and returns specific product details. The verb 'Search' and resource 'Google Shopping' are specific and distinguish it from sibling tools like serpapi_google_jobs or serpapi_google_maps.

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 an example and context for shopping searches, but does not explicitly state when not to use this tool or compare it to alternatives. Given the sibling list, the purpose is clear enough for an agent to infer 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the types of data returned (TIMESERIES, GEO_MAP, etc.) and the external API requirement (SerpApi key). It does not contradict annotations and provides useful behavioral context beyond what annotations cover.

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 concise: two sentences plus an example code snippet. Key information is front-loaded (verb, resource, what it returns). Every sentence provides value without unnecessary 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?

No output schema is provided, so the description should ideally outline the return format. While it says 'returns the requested trends block', it does not specify the structure (e.g., JSON shape with timelineData, etc.). Given the tool's complexity (external API, multiple data types), this is a gap. However, annotations and schema cover safety and parameters 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?

Schema description coverage is 100%, so each parameter is already documented. The description adds an example with concrete values, which helps illustrate usage, but does not add significant new 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 clearly states it gets Google Trends data and mentions the specific blocks it can return (interest over time, by region, related queries). The example reinforces the purpose. However, it does not explicitly distinguish from sibling SerpAPI tools, though the name and context make that clear.

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 an example of usage, implying when to use it (to get Google Trends data). It does not explicitly state when to use it versus alternatives or when not to use it. Among siblings, it's clear due to distinct service names, but explicit guidance would strengthen this dimension.

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

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

The description states 'Create a ... subscription', implying a non-idempotent operation, but the annotations declare idempotentHint=true. This contradiction undermines trust; the description does not disclose that repeated calls with the same parameters might create duplicate subscriptions. Additionally, the creation nature suggests destructive potential, yet destructiveHint=false.

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 well-structured, front-loading the core action and return value. Each sentence adds unique information: behavioral context, type examples, delivery options, prerequisites, and limitations. No fluff.

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

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

Given the tool's complexity (multiple event types, delivery channels, authentication, verification steps, rate limits, security), the description covers all essential aspects: what it does, what it returns, who can use it, how to configure each type, delivery options, and limitations. Despite lacking an output schema, the return value (subscription ID) is simple enough.

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

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

With 100% schema description coverage, the description still adds substantial value beyond the schema by providing detailed examples for each type (e.g., sec_8k items mapping to officer changes), delivery channel nuances (SMS verification, webhook HMAC signing, rate caps), and required account setup. This goes far beyond the schema's terse 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It uses a specific verb ('Create') and resource ('subscription'), distinguishing it from siblings like 'list_subscriptions', 'recent_alerts', and 'unsubscribe'.

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

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

The description provides context on when to use (setting up live monitoring), prerequisites (Pipeworx OAuth, verified phone for SMS), and type-specific parameters with examples. It lacks explicit exclusions or alternatives but the sibling list and context clarify 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?

Beyond annotations (readOnly, openWorld, idempotent), the description reveals that returns a structured set of example questions drawn from a live catalog, and that calling with no arguments gives a full spread while a topic parameter focuses the results. This adds meaningful 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?

The description is comprehensive yet efficient, using multiple colloquial phrasings to match user intent, then clearly stating behavior and usage. Every sentence contributes essential information without redundancy.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description fully covers its purpose, behavior, parameter usage, and situational context. It leaves no ambiguity for an AI agent to select and invoke the tool correctly.

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

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

The schema describes the optional 'topic' parameter with allowed values, but the description adds practical usage guidance: omitting gives cross-category spread, passing a topic focuses results. This enhances understanding of parameter behavior beyond the schema.

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

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

The description clearly states the tool is the onboarding entry point for agents to learn what Pipeworx can do, returning category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings like 'discover_tools' by emphasizing its role as a first step for unfamiliar users.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear context for when this tool is appropriate, and implies alternatives for more specific queries.

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?

Explains beyond annotations: the row is deactivated (not deleted), preserving historical events accessible via recent_alerts. No contradiction with annotations (idempotentHint=true is consistent with soft-deactivation).

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, each essential: first states action and constraint, second provides behavioral nuance. 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?

For a simple tool with one parameter and no output schema, the description fully covers purpose, constraints, and side effects. Points to related tool (recent_alerts) for historical data.

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 (id) with schema description already covering its source ('returned by subscribe'). Description adds no further detail, but schema coverage is 100%.

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?

Clear verb and resource: 'Cancel a subscription by id.' Distinct from sibling tools like subscribe and 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?

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding on when to use and constraints. No explicit alternatives but context clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context: how claims are routed, the verdict categories, and the inclusion of verbatim evidence with citations. This goes beyond the annotations.

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

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

The description is a single paragraph but front-loads the purpose with trigger phrases. It is comprehensive but slightly verbose; could benefit from slight tightening. Still, every sentence adds value.

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

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

Given the tool's complexity and lack of output schema, the description covers main aspects: processing paths, verdict types, and replacement of multiple steps. It lacks error handling details but is otherwise 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?

Both parameters are fully described in the schema (100% coverage). The description adds extra meaning: tolerance_pct overrides the default, which is implied by wording and capped at 5. Examples clarify the 'claim' parameter.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific verb patterns and distinguishes it from general search by detailing the fast path for company-financial claims and fallback for others.

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 ('whenever the agent needs to check... something a user said is factually correct') and explains the two processing paths. However, it does not explicitly state when not to use it or provide alternatives to exclude.

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