Serpapi

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds value by explaining cost implications (free for default model, BYO key for Anthropic), pass-through of key to api.anthropic.com, and return structure (per-model and combined view). No contradictions.

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

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

Single paragraph, front-loaded with core action and output. Every sentence adds value: default model, optional key, return format, use cases. No fluff, efficient communication.

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

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

Despite no output schema, description fully specifies return values (score, confidence, signals, raw_response per model plus combined). Covers all parameters, use cases, and behavioral context. Complete for a tool with clear annotations and 4 parameters.

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% parameter description coverage. Description reinforces each parameter: entity (thing to ask about), models (which models, with default hint), _apiKey (required for Anthropic, passed straight through), context (disambiguation). Adds nuance like 'free default' and 'BYO key' 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 'probe LLMs for what they know about a business/brand/product/topic and score visibility (0-100) per model'. Specifies default model and optional Anthropic probing. Use cases given (AI-marketing audits, pre-launch brand checks, competitive monitoring) help distinguish from sibling tools like entity_profile or deep_research.

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

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

Description provides clear context for when to use (AI-marketing audits, brand checks) and implies when to probe multiple models with _apiKey. However, it does not explicitly state when not to use or directly compare to sibling tools, though the use cases serve as implicit guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: it routes questions automatically, returns citations, works on every tier, and makes one fast call. It does not contradict annotations and provides enough insight into the tool's operation.

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

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

The description is longer than average but well-structured: it front-loads the most critical guidance (prefer over web search), then covers domains, routing, alternatives, examples, and a clear starting-point directive. Every sentence adds value; no filler or tautology.

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 is complex with 6 parameters and no output schema, but the description compensates by explaining the result format (structured answer with citation URIs) and its scope (5,501 tools across 1,441 sources). It also covers use cases and limitations (when to step up to alternatives), making it reasonably complete for an agent.

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

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

Schema coverage is 100% with each parameter described (primarily the question field and its aliases). The description adds example questions but no deeper parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: answering factual questions by routing to 5,501 tools across 1,441 sources and returning structured answers with citations. It uses specific verbs like "routes" and "returns," and explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit guidance: "PREFER OVER WEB SEARCH" and "START HERE for most questions." It also provides clear alternative usage for ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part questions), as well as noting it handles breaking news and live updates.

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 operational context beyond annotations: it's a beta with live candidate routing, results are compared against the stable router, and 'falls back to nothing' clarifies it is a full working router. Annotations are readOnly/idempotent and consistent; no contradiction detected. The description enriches the safety profile with testing nuances.

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 and front-loads the key beta/experimental identification. While the specific retirement date (2026-07-26) is temporally fine-grained, each sentence contributes to usage or behavioral clarity, with minimal fluff.

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

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

The simple schema (one required parameter) and strong annotations reduce the need for deep explanation. The description covers the beta nature, current equivalence, and usage intent. It relies on the sibling ask_pipeworx for response shape details, which is acceptable given the 'same response shape' note.

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

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

Schema coverage is 100% with all 6 parameters (aliases for question) well-described. The description only notes 'same arguments' as ask_pipeworx, adding no extra semantic meaning. Baseline 3 is appropriate as the schema carries the full burden.

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

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

The description clearly identifies the tool as 'Beta version of ask_pipeworx' with an 'identical universal router' and specifically notes 'candidate routing improvements', distinguishing it from the stable ask_pipeworx and ask_pipeworx_grounded siblings. This provides a specific verb+resource and scopes the experimental nature.

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

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

It explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing', and clarifies the current state ('No candidate is active right now... currently matches ask_pipeworx exactly'). This gives clear context and an implicit alternative to the stable router.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the structured return format, explicit refusal reasons, the constraint of using only tool result content, and the extra LLM call cost. This adds substantial behavioral context not available from annotations.

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

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

The description is detailed and front-loaded with purpose, then mechanics, return format, and trade-offs. While not extremely terse, each sentence contributes unique value (e.g., refusal reasons, cost comparison). Slightly lengthy but well structured.

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?

In the absence of an output schema, the description thoroughly explains success and refusal response shapes, the routing mechanism, and the trade-off vs. the sibling tool. It covers all essential decision-making and invocation context for a high-stakes answer tool.

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

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

The schema already provides 100% coverage: the 'question' parameter is described with aliases. The description adds no further parameter-level detail. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and explains its unique behavior (routing, fetching, extracting from tool result only). It explicitly contrasts with sibling ask_pipeworx, distinguishing it as the grounded variant.

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 whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also names the alternative and describes the cost trade-off, making it clear when to choose 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are complemented by extensive behavioral detail: fan-out mechanisms, response shapes, resolver contract with match confidence, parent event extraction, news fallback handling, safety short-circuits for low-confidence/resolved/illiquid markets, and resolution-rule risk analysis. Description adds substantial value 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 lengthy but front-loaded with the core purpose. It packs significant detail about edge cases and behavior, which is justified given complexity. Some sections (e.g., fan-out examples) could be more terse, but overall each sentence adds value.

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

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

Given the tool's complexity (multiple fan-out patterns, resolver logic, parent events, news fallback, safety checks, cancellation rules) and no output schema, the description comprehensively covers all relevant aspects. It explains return shapes, failure modes, and caveats 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?

Schema coverage is 100% with descriptions for each parameter. The description adds semantic context: for 'market' it explains slug/URL/question text, for 'depth' it defines 'quick' vs 'thorough', and for 'include_raw' it clarifies when to use true/false. This provides meaning beyond schema alone.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + comparison). The verb 'research' distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on specific aspects.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides category-specific fan-out examples. While it doesn't explicitly exclude scenarios, the context makes appropriate usage clear. Lacks direct comparison with sibling tools but offers ample guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds details: parallel call, data sources (SEC EDGAR/XBRL, FAERS), citation URIs, and fiscal year handling. No contradiction.

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

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

Description is information-dense but front-loaded with purpose. Every sentence adds value, though it could be slightly more concise. No wasted words, but slightly longer than minimal.

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 covers return format (paired data + citation URIs), sorting, data sources, and fiscal year handling. Sufficient for an agent to understand tool behavior and expected outputs.

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

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

Schema coverage is 100% but description adds examples and context: company expects tickers/CIKs, drug expects names, and explains what each type pulls. This goes beyond basic schema and helps correct parameter usage.

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

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

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with examples like 'Compare X and Y' and 'X vs Y'. It distinguishes from sequential lookups, making 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', guiding when to use. Explains parameter differences for company vs drug, and results sorted by primary metric, which aids selection.

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

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

The description far exceeds the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). It discloses the output packet structure (verbatim evidence, confidence, source, fetched_at, citations, gaps[]), the never-invented policy, second-hop recovery behavior, contradiction detection for standard/thorough depths, citation_uri fetchability rules, semantic excerpting, and latency ranges. No contradiction with annotations.

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

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

The description is long, but every sentence contributes critical operational information (auth, tiers, alternatives, output, latency, edge cases). It is front-loaded with the account requirement and core purpose. The density is high; a slight trim would improve scanability, but it is appropriately sized for a tool of this 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?

There is no output schema, so the description fully carries the responsibility of explaining return values, which it does thoroughly: findings packet with per-finding fields, gaps[], contradictions[], hop field, and citation_uri. It also covers failure behavior (gaps when not in structured catalog) and performance expectations (15-60s, up to 90s). The tool is completely specified for an agent to decide on and invoke correctly.

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

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

Schema already lists the two parameters with descriptions, but the tool description adds crucial behavioral nuance: depth is explained with exact facet counts and hop behaviors ('quick=3... standard=5... thorough=8'), and question is noted to support broad/multi-part queries. This meaningfully supplements the schema, not just restates 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?

The description opens with a clear verb+resource: 'Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources' and explicitly contrasts itself with open-web search ('this is NOT open-web search'). It also distinguishes from sibling ask_pipeworx by describing the one-call multi-tool decomposition, making its unique role 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 gives explicit when-to-use vs alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also specifies tier/account constraints and what depth levels are appropriate ('depth:"thorough" needs a paid plan'). This is model-level guidance.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly', which gives rich 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 a single paragraph that front-loads the purpose and usage guidance. It is reasonably concise, though it lists many domains which could be trimmed. Still very clear and well-structured.

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

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

The description explains the return type (top-N tools with schemas and examples) despite no output schema. The tool is simple (no nested objects) and the description covers all essential aspects for an agent to invoke it correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. The description mentions the main parameter accepts natural language and lists aliases, but adds no additional semantic detail 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 the tool's verb ('Find') and resource ('tools by describing the data or task'), and lists specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that perform specific functions.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available', providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: fan-out across multiple sources, return fields with detailed descriptions (e.g., 'fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC)'), patent sunset note ('soft-fails until reactivated'), news fallback, and LEI. 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 lengthy but front-loaded with examples and the key recommendation. Every sentence adds value, though some minor tightening could be done. It is well-structured.

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

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

Without an output schema, the description completely covers the return structure: cik, company_name, recent_filings with URIs, fundamentals sorted, patents with sunset, news via fallback, LEI. It explains quirks and sources, making the tool self-contained.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces accepted values (ticker or zero-padded CIK) and adds context that names are not supported, directing users to resolve_entity. This extra usage guidance justifies a 4.

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

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

The description starts with concrete example queries ('Tell me about X', 'research Acme', etc.), explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call', and lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It clearly distinguishes from chaining multiple single-pack 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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a when-not: 'names not supported (use resolve_entity first if you only have a name).' This gives clear guidance relative to sibling tools like resolve_entity.

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 destructiveHint and idempotentHint. The description confirms destruction and adds context about use cases (stale context, sensitive data), which is useful beyond annotations.

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

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

Two sentences, no wasted words. First sentence states the action, second provides usage guidance. Highly efficient.

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

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

For a simple tool with one parameter, the description covers purpose, usage, and pairing with siblings. Annotations provide safety profile. No missing information.

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

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

Schema coverage is 100%, and the description does not add additional meaning beyond the schema's 'Memory key to delete'. Baseline score of 3 is appropriate.

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

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

The description explicitly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from sibling tools like remember and recall, which are mentioned for pairing.

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 when to use ('context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with remember and recall, offering guidance on alternatives.

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

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

Discloses the fetching, extraction, and emission process, fully aligned with annotations (readOnlyHint, idempotentHint) 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?

Three concise, front-loaded sentences with no wasted words; every sentence adds value.

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

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

For a simple tool with 2 parameters and no output schema, the description sufficiently explains purpose, behavior, and output format; annotations cover safety and idempotence.

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

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

Schema already covers both parameters with descriptions; the description adds no additional semantic detail beyond the schema (e.g., no explanation of URL validation or max_links behavior).

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

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

Clearly states 'Generate a production-ready llms.txt file for any URL' with specific verb and resource, and distinguishes from sibling tools by describing the exact output format and use cases.

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

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

Explicitly lists three useful scenarios (clients, own project, competitor audit), but does not mention when not to use or provide direct alternatives among siblings, though sibling list lacks similar 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 readOnlyHint, idempotentHint, destructiveHint. The description adds the specific returned fields and the optional parameter for inactive subscriptions, enhancing transparency beyond annotations.

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

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

Two efficient sentences with no fluff, front-loaded with purpose and key details.

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

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

Despite no output schema, the description fully covers return fields, usage context, and parameter hint, making it complete for a simple read-only list tool.

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

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

Schema coverage is 100% and the parameter description is clear. The description adds minimal value beyond the schema, mentioning 'active' vs. inactive, but baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' and specifies the returned fields (id, type, params, etc.), distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use the tool versus alternatives.

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

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

Annotations are all false and carry no safety hints, so the description adds essential behavior. It discloses that filing without an account returns a claim_token and that passing that token later retrieves resolution status. It also notes 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' 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?

Though a single dense paragraph, every sentence earns its place: purpose, use triggers, exclusion, claim_token mechanics, team cadence, rate limit, and quota impact. It front-loads the primary action and follows a logical flow, though it could benefit from bullet points for even easier scanning.

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

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

With no output schema, the description compensates by explaining return behavior: 'Filing without an account returns a claim_token' and later retrieval gives 'the status and, once resolved, what actually changed.' It also covers both operation modes, rate limiting, quota, and team response time. A minor gap is not stating what happens if called with no arguments, but all parameters are optional per schema.

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

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

With 100% schema description coverage, the baseline is 3. The description adds practical semantics beyond the schema: 'don't paste the end-user's prompt' for message, the claim_token retrieval pattern with an example, and the context object's purpose for structuring feedback. This enriches parameter understanding beyond the field descriptions.

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

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

The description opens with a specific imperative: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates exact categories (bug, feature, data_gap, praise) and clarifies scope by stating 'ONLY for tools served by this Pipeworx connection,' which clearly distinguishes it from sibling tools like ask_pipeworx and any other MCP server tools.

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an explicit exclusion and alternative: 'if the tool came from a different MCP server... file it with that server instead.' This provides clear when/when-not guidance with a named alternative.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds valuable behavioral context: the data is derived from CF analytics-engine, no PII, just counts, and caching varies from 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 two sentences followed by a bulleted list of use cases. It is front-loaded with what the tool returns, then why to use it, then technical details. Every sentence adds value with no redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, use cases, data source, privacy, and caching. No gaps are apparent.

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

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

Schema description coverage is 100% for the single parameter 'window', but the description adds meaningful context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances understanding beyond the enum values.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window.' It specifies the action ('Returns') and the resource (trending data on Pipeworx), distinguishing it from siblings like discover_tools or ask_pipeworx.

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 lists three specific use cases for when to use the tool, such as discovering hot data sources or confirming a canonical tool. It also provides guidance on window selection ('shorter windows surface what's hot right now; longer windows show steady-state demand'). It does not explicitly state when not to use it, but the use cases are clear.

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

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

Annotations declare readonly, open world, idempotent, not destructive. The description adds extensive behavioral detail: specific checks (date-axis, threshold-axis, partition_check), filters (placeholders, similarity), and fill check logic, with 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 thorough but slightly verbose, repeating some concepts (e.g., partition check explanation twice). All content is relevant, but trimming redundant explanations would improve conciseness.

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

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

Given the complexity and absence of output schema, the description covers all essential aspects: modes, parameters, algorithmic details, filters, edge cases, return structure, and references to sibling tools. It leaves no significant gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning beyond schema, explaining each mode's expected input format (slug, URL, seed question) and how they affect the search behavior.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending scan, event, topic) with specific use cases, making the purpose well-defined 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?

Explicit guidance on when to use each parameter: no args for trending scan, event for single markets, topic for cross-event scanning. Also mentions fill check and directs to polymarket_fill_risk for custom sizing, providing clear alternatives and 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?

Beyond annotations (readOnlyHint, idempotentHint), the description discloses caching behavior (1h KV-level), model details (crypto_price, news_momentum, partition_overround, concentrated_longshot), the Fed candidates exclusion, and design nuances like partition arbs returning kelly_fraction_half=0 at parent level. No contradictions.

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

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

The description is well-structured with sections and bold terms, but is verbose with technical model details (e.g., 'lognormal barrier from 90d FRED log-returns') that could be trimmed. It front-loads the main purpose but becomes lengthy.

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 (9 parameters, no output schema), the description covers response structure, diagnostics, caching, model behaviors, and knob effects comprehensively. It provides enough detail for an agent to understand what the tool returns and how to use 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?

Schema coverage is 100% with parameter descriptions. The tool description adds significant value by explaining the purpose of tradeable-edge knobs (min_liquidity, max_spread_pp) and min_partition_leg_kelly, and how they filter opportunities. This goes beyond the schema.

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

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

The description explicitly states the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, with a clear use case 'what should I bet on today'. It details three distinct segments, distinguishing it from siblings like polymarket_arbitrage.

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 discovering betting opportunities and provides guidance on tradeable-edge knobs, but does not explicitly compare to sibling tools like polymarket_edge_tracker or polymarket_fill_risk. No explicit when-not or alternatives mentioned.

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 annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructive action. The description adds valuable behavioral details beyond annotations, such as the 60-day snapshot TTL bound, decay calculation method, and explanation of snapshot gaps.

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 a concise opening line and detailed breakdown of response fields. While slightly lengthy, each sentence adds value and the structure is clear.

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

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

Despite lacking an output schema, the description thoroughly explains all response fields (tracked[], expired[], snapshot_dates[]) with their meanings. It also covers limitations like history depth and decay calculation, making the tool fully understandable.

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

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

Schema description coverage is 100% for both parameters. The description adds context by explaining default values and purpose in the tool's logic (e.g., 'lookback' for days, 'snapshot family' for window), enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes itself from siblings like polymarket_edges by focusing on time-series analysis.

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

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

The description offers clear context on when to use the tool, including a motivating example (fresh vs. old wide edge). However, it does not explicitly state when not to use it or name alternative tools, relying on sibling context to differentiate.

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 significant behavioral context beyond annotations: partial fills risk, thin book issues, forced directional risk. Annotations (readOnlyHint, idempotentHint) are consistent and description expands on safety aspects.

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

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

Description is lengthy but well-structured: first lines define purpose, then REQUIRES, then mode details, then usage context. Front-loads key constraints. Slightly verbose but 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?

Without output schema, description comprehensively lists return fields for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, etc. for basket. Covers modes, parameters, and risk warnings.

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

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

Schema covers 100% of parameters with descriptions. Description adds meaning beyond schema: explains REQUIRES one of market/event, default side behavior, and basket size_usd interpretation as 'settlement notional S (shares per leg; each share pays $1)'.

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

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

Description clearly states it's a 'realizable-vs-theoretical edge check against live CLOB order-book depth', explains single-market and basket modes, and distinguishes from siblings polymarket_arbitrage and polymarket_edges by advising to use it before those tools for certain trades.

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: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns about risks of partial fills converting arb into unhedged directional position, providing clear context.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds rich behavioral context: it details safety fields (compatibility_warning, temporal_alignment, skipped counters) and explains conditions under which no arb exists, far exceeding bare annotation info.

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 but somewhat long. However, it is front-loaded with purpose and modes, and the structure is logical. Could be slightly trimmed but serves its purpose well.

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 fully covers input modes, response structure (leg-by-leg prices, top_spreads_pp), safety/compatibility warnings, and temporal alignment. Everything needed for correct usage is present.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by enumerating the 10 topic shortcuts and explaining that explicit tickers override topic-mapped sides.

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 precisely states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes from siblings like polymarket_arbitrage by specifying the cross-venue nature.

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

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

The description explicitly documents two modes (topic shortcuts and explicit tickers), warns that most shortcuts return compatibility_warning, and explains when spreads are meaningful vs not, guiding 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, destructiveHint=false, idempotentHint=true. Description adds scoping to identifier (anonymous IP, BYO key hash, or account ID) and mentions re-deriving from scratch, providing useful 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?

Two sentences with no wasted words. First sentence captures core function, second provides usage and context. All information is front-loaded and essential.

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

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

No output schema exists, but description does not specify return format (e.g., string value, list of keys). While scoping and pairing info is good, the missing return details reduce completeness for a read tool.

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

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

Schema coverage is 100% and already describes the key parameter. Description reinforces but does not add new semantic information beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if no key is provided. It gives concrete examples (ticker, address, notes) and distinguishes from siblings remember and forget.

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

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

The description says to use for looking up previously stored context and pairs with remember/forget. It doesn't explicitly state when not to use, but the context is clear given sibling tools.

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

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

Beyond annotations (readOnly, dopenWorld, idempotent, not destructive), description details return fields (source, citation_uri, raw payload), mark_read behavior, and polling suitability. Complements annotations well with 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 concise sentences: first states purpose, second details returns and filters, third explains mark_read and alternative access. Front-loaded and no wasted words.

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

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

Despite no output schema, description sufficiently covers return structure, filtering, state management (mark_read), and alternative access. All optional parameters are addressed; complete for a read 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 already describes all 5 parameters (100% coverage), but description adds contextual usage examples like 'Filter by type (e.g. "sec_8k")' and explains mark_read's effect, providing extra 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?

Starts with clear verb 'Pull fired events from your subscription feed', specifying both resource and action. Distinguishes from sibling tools like list_subscriptions and ask_pipeworx by focusing on reading alerts.

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

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

Explains filtering by type and since, effect of mark_read, and mentions polling works fine. Also notes alternative HTTP endpoint for scripts/dashboards, providing context on when to use this tool vs other access methods.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds value by detailing the multi-source fan-out, rate-limit fallback, and PatentsView API sunset, which are not in annotations.

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

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

Single paragraph with high information density. Well front-loaded with usage examples. Could be slightly more structured (e.g., bullet points) but remains 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?

Despite no output schema, description covers return structure (changes grouped by source, total_changes, citation URIs). All three parameters are well described. Complete within its scope.

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

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

Schema has 100% description coverage. Description supplements with useful context: ISO/relative shorthand for 'since', examples, and allowed values for 'type'. 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?

Explicitly defines the tool as a change feed for a company, with concrete examples ("What's new with X") and specific data sources (SEC, GDELT/GNews, USPTO). Clearly distinguishes from sibling entity_profile.

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

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

States when to use (for recent changes in a time window) and explicitly advises using entity_profile for static profiles. Also describes 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?

Adds behavioral context beyond annotations: memory persistence depends on authentication (persistent vs 24-hour), and scoping by identifier. 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?

Concise and well-structured: main purpose first, then usage, then behavioral details. 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?

Given the simple key-value nature, no output schema is needed. Description covers scope, persistence, and pairing with recall/forget, making it 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 has full coverage (100%) with descriptions, but description adds concrete key examples and value type, providing extra semantic clarity.

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 reuse across conversations/sessions as key-value pairs, and distinguishes from sibling tools 'recall' and 'forget'.

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

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

Explicitly advises using when discovering information worth carrying forward, and mentions pairing with recall/forget. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond annotations by explaining that each call cascades through several lookup endpoints internally and returns citation URIs, which helps the agent anticipate behavior and result format.

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

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

The description is front-loaded with user-phrase examples and the 'Use FIRST' directive. It is information-dense but every clause contributes (supported types, input forms, output details, internal cascade), with no fluff or repetition. The structure is clear despite being a single paragraph.

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 there is no output schema, the description thoroughly explains return values for both entity types, including ticker, CIK, company name, RxCUI, ingredient, brand, and citation URIs. It covers multiple input formats, disambiguation behavior, and internal cascading, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% and the schema already defines both parameters with descriptions. The description adds value by providing concrete examples (e.g., 'AAPL', 'ozempic') and clarifies auto-disambiguation for company inputs, as well as describing the output identifiers returned, which helps an agent choose appropriate parameter values.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers required by other tools, with specific verbs like 'resolve' and resource types ('company', 'drug'). It distinguishes from siblings like entity_profile and compare_entities by focusing on ID lookup rather than profiles or comparisons.

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 phrase 'Use FIRST whenever you have a name but need an ID' gives explicit guidance on when to use the tool. It also explains that the tool replaces 2-3 manual lookups, making the use case clear, though it doesn't explicitly mention when not to use it or name alternative tools for different purposes.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the main action, and every sentence adds value with no wasted words.

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

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

For a tool with 4 parameters (1 required) and no output schema, the description fully explains the purpose, behavior, and output format (ranked list with score/confidence/signal density), making it complete for an agent.

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

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

Schema coverage is 100% and the description provides minimal additional value beyond the schema (e.g., noting that first entity is treated as subject), but it does not add significant meaning beyond what the parameter descriptions already convey.

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 the specific verb 'Compare' and resource 'AI visibility across multiple entities side-by-side', clearly distinguishing it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and implies that for single entity checks one should use ai_visibility_check, but does not explicitly state when not to use this tool or name alternatives beyond the sibling mention.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond annotations: composite fan-out, partial failure handling with sources_failed, and the 5-30s first measurement latency for bundlephobia.

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 and provides detailed, valuable information in a structured way. While somewhat dense, every sentence contributes meaning 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 complexity (composite with external APIs), the description is complete: it explains the composite nature, return structure (summary, advisories, links, alternatives), edge cases (partial failures, timeouts), and ecosystem limitations.

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 parameter descriptions. The description adds meaning by explaining the composite behavior and the return structure (summary block, per-advisory detail, links, alternative versions), which helps users understand how parameters affect the results.

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: a composite check for npm packages combining deps.dev and bundlephobia data. It specifies the verb 'scan' and resource 'dependency', and distinguishes from siblings by explaining its unique composite nature.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also clarifies ecosystem scope ('NPM ecosystem only in v1') and directs alternatives for other ecosystems, providing clear when-to-use and when-not-to.

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, idempotent, non-destructive behavior. The description adds valuable technical details: truncation at 200K chars with flag, BGE-base-en embeddings, cosine similarity, 500-char windows, and character offsets. This goes beyond annotations to fully inform the agent.

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 well-structured paragraphs, first sentence delivers purpose immediately. At about 100 words, it's concise yet comprehensive. 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?

No output schema exists, but the description covers return structure (top-N passages with offsets and similarity scores), pairing guidance, and technical constraints (char limit, embedding model). This fully compensates for missing output schema and matches tool 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%, so baseline is 3. The description adds value by explaining each parameter's role in context (e.g., 'the document text to search inside', 'natural-language query') and provides concrete query examples, going beyond mere 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?

Description clearly states it performs semantic search inside a fetched record, using specific verb 'Search Within' and resource 'a fetched record'. It distinguishes from siblings by naming ask_pipeworx_grounded and explaining the pairing pattern, leaving no ambiguity about its unique 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?

Explicitly states 'Use when the record is too big to cram into the prompt' and describes pairing with ask_pipeworx_grounded. While it doesn't list exclusions, the context is clear enough to guide appropriate use.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint, openWorldHint. The description adds that it requires an API key and returns specific fields. No contradictions.

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

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

Two concise sentences plus an example. No wasted words; the information is front-loaded.

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

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

No output schema, but the description lists return fields. Lacks mention of pagination or errors, but for a simple search tool this is acceptable.

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 parameters are already documented. The description provides an example with parameters, but adds no extra semantic 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 searches Google Jobs for a query and returns specific fields (title, company, location, etc.). It distinguishes from sibling tools like serpapi_google_maps by focusing on 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 includes an example but does not explicitly state when to use this tool versus alternatives like serpapi_google_maps or when not to use it. The guidelines are implicit from context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns specific fields but does not contradict annotations. No additional behavioral context beyond what annotations provide.

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

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

Single sentence plus an example. Purpose is front-loaded, no wasted words. Highly efficient for a tool with 3 parameters.

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 good annotations and no output schema, the description covers return fields and provides an example. Missing details on pagination or rate limits, but completeness is adequate for common use.

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

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

Schema coverage is 100%, so baseline is 3. Description includes an example with parameter values, but the schema already describes parameters thoroughly. Minimal extra meaning added 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?

Clear verb+resource: 'Find local businesses on Google Maps'. Distinguishes from sibling tools like serpapi_google_jobs, serpapi_google_news, etc. by focusing on local business search and specifying return fields.

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 an example but no explicit guidance on when to use vs alternatives or when not to use. The context is implied (search local businesses), but lacks exclusions or comparison to other 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 (readOnlyHint=true, destructiveHint=false) already cover safety. Description adds that it returns headline, source, link, date, snippet, which is useful context. No contradictions.

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

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

Two concise sentences: first states purpose and return value, second shows an example. No wasted words, front-loaded.

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

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

Given simple 4-parameter tool with good annotations, the description adequately covers return fields and shows an example. Could mention pagination or result count, but it's sufficient for a search tool.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description includes an example, which adds marginal value but doesn't provide new semantic details 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?

Description clearly states the tool searches Google News and returns specific fields (headline, source, link, date, snippet). The verb 'Search' and resource 'Google News' are explicit, and it distinguishes 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?

Description indicates when to use (search Google News) but doesn't explicitly state when not to use or mention alternatives. However, sibling names provide clear context, and the tool is self-explanatory for its domain.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that it uses an external service (SerpApi) and lists the return fields indicating a read operation. No contradictions with annotations. However, it does not mention potential rate limits or costs of the external API, which would add further 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?

The description is a single sentence with an example, no unnecessary words. It front-loads the action and purpose. Every part earns its place—very concise and structured.

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 return fields. It covers the main parameters via example. It does not discuss edge cases like empty results or pagination limits beyond the num max. Overall, it is adequately complete for a tool with full schema coverage and clear annotations.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds an example with parameter usage and mentions the topic placeholder, but it does not significantly enhance the meaning of individual parameters beyond what the schema already provides. The output field list is useful but not strictly parameter semantics.

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

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

The description clearly states the action 'Search Google Scholar for academic papers' and specifies the resource (Google Scholar) and the return fields (title, link, snippet, publication info, citation count). It distinguishes from sibling tools like serpapi_google_jobs or deep_research by focusing on academic paper search.

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 explicitly provide when or when not to use this tool versus alternatives. The example implies typical usage, but there is no guidance on when to prefer this over other research tools like deep_research or other serpapi tools. Context of academic paper search is clear, but comparative guidance is missing.

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. The description adds that it returns specific fields but does not discuss rate limits, pagination, or error behavior. It provides some extra context but not substantial behavioral details.

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 front-loads the core purpose and output, making it quick to parse.

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

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

Given no output schema, the description lists return fields adequately. However, it does not describe the response structure (e.g., array vs. object). With full parameter coverage and good annotations, completeness is high but could be improved with output format hints.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds value by providing a concrete example showing parameter usage and listing output fields, which helps the agent understand what to expect.

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

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

The description clearly states the verb 'Search' and the resource 'Google Shopping', and lists specific returned fields (title, price, source, etc.). It distinguishes itself from sibling tools like serpapi_google_jobs or serpapi_google_maps by explicitly targeting shopping results.

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

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

No guidance on when to use this tool versus alternatives (e.g., general web search vs. shopping-specific). The description does not mention when not to use it or compare to sibling tools.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it calls an external API (SerpApi) and requires an API key, which is useful context. However, it does not mention potential rate limits, error handling, or response delays.

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?

One concise sentence describing purpose and output, plus a clear example. No redundant or unnecessary information.

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

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

No output schema is present, and the description only vaguely states it returns 'the requested trends block'. For a tool with no output schema, the description should provide more detail on the return structure (e.g., fields, format). This gap reduces completeness.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description provides an example but does not add new semantic 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 retrieves Google Trends interest-over-time data for specified terms, and distinguishes itself from sibling tools (e.g., serpapi_google_news, serpapi_google_jobs) by specifying 'Google Trends' and describing the data blocks returned.

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

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

No explicit guidance on when to use this tool over alternatives (e.g., other SerpApi tools). The example shows usage but does not provide decision criteria, scope, or prerequisites beyond having an API key.

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

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

The description adds significant behavioral context beyond annotations: it explains that subscriptions require OAuth, details each type's parameters, delivery channels (feed always on, email/SMS/webhook with specific constraints like SMS cap and webhook auto-disable), and that a subscription id is returned. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, 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 relatively long but efficiently packs all necessary information. It front-loads the main purpose and then systematically covers types and delivery. A more structured layout could improve readability, but it is not wasteful.

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 output schema, the description fully covers the return value (subscription id). It explains all supported types, parameters, delivery options with constraints, and prerequisites. No critical gaps remain 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 description adds substantial meaning beyond the schema: it provides concrete examples for each type (e.g., sec_8k items, polymarket_edge topic, fred_series series_id), explains param structure, and for delivery gives detailed info on webhook signing, SMS verification, and email validation. Schema coverage is 100% and description enriches it greatly.

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

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

The description clearly states the tool's action ('Create a proactive monitoring subscription to a live-data event stream') and its return value ('Returns the new subscription id'). It lists supported types and delivery channels, and distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides explicit guidance on prerequisites (Pipeworx OAuth account, anonymous/BYO cannot persist), supported subscription types with examples, and delivery channel options. It does not explicitly specify when not to use this tool versus alternatives, but the context is clear enough for most cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it returns category-bucketed example questions with exact tool+argument shapes drawn from a live catalog, and specifies that no arguments give full spread vs. topic filtering. 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 moderately long but front-loads key aliases and purpose. Every sentence adds useful detail, though it could be slightly more concise. It is well-structured and readable.

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 purpose as an onboarding aid, the description adequately explains the return format (category-bucketed example questions with tool+argument shape). Although there is no output schema, the description compensates well. It could optionally mention if results are limited or paginated, but this is minor.

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

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

Schema coverage is 100% for the single optional topic parameter. The description adds value by listing possible focus areas (finance, pharma, etc.) and explaining the effect of omitting the parameter (cross-category spread), enhancing the schema definition.

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

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

The description explicitly states the tool is the onboarding entry point for new agents, addressing questions like 'what can I ask?' and 'what data do you have?'. It clearly distinguishes itself from sibling tools like ask_pipeworx and discover_tools by being the first step for initial exploration.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides guidance on optional topic filtering and contrasts with other tools implicitly.

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

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

Annotations indicate a non-readonly, non-destructive, idempotent action. The description adds crucial context: ownership enforcement, soft deactivation (not deletion), and preservation of historical events. No contradictions.

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

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

Two sentences with no waste: main action first, then ownership, then behavioral effect. Front-loaded 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?

For a simple tool with one parameter and no output schema, the description fully covers the essential behavioral aspects, including ownership, soft deletion, and historical data handling.

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

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

Schema coverage is 100% and the description does not add extra meaning beyond the schema's description of the 'id' parameter. Baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription by id'), clearly distinguishing it 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?

It explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use it. It also notes the non-destructive behavior, but does not compare to 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 readOnly, openWorld, idempotent. The description adds value by explaining the two pipeline paths, exact percent-delta math for financial claims, and the return verdict types with citations and reasoning. It discloses behavioral traits 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 and front-loaded with example phrases, then use case, then processing details, and finally return format. Every sentence adds value without unnecessary fluff. Length is appropriate for the complexity.

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

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

Given no output schema, the description comprehensively explains the return value (verdict, actual value with citation, reasoning). It covers the two processing paths and tolerance behavior. No gaps are apparent for a verification 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%, baseline 3. The description adds meaning by providing example natural-language claims for the 'claim' parameter and explaining how 'tolerance_pct' overrides defaults or is used for hallucination detection, making it more helpful than schema alone.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific example phrases and distinguishes two processing paths (structured SEC EDGAR for financial claims, grounded pipeline for others), setting it apart from sibling tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It implies when to use the tool but does not directly compare to sibling tools or state when not to use it.

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