Scb Se

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

The annotations already indicate safe, idempotent, non-destructive behavior. The description adds valuable context: default model, cost implications of _apiKey, and return structure (per-model {score, confidence, signals, raw_response} + combined view). No contradiction with annotations.

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

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

The description is four sentences, front-loaded with purpose, and each sentence adds distinct value (action, default behavior, return format, use cases). No redundancy or filler.

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

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

With 4 parameters and no output schema, the description covers the tool's behavior, parameter roles, return format, and use cases. It provides sufficient information for an AI agent to decide when and how 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?

Schema description coverage is 100%, but the description adds meaning: explains the default model for 'models', clarifies that _apiKey is optional and passed through to Anthropic, and provides examples for 'entity' and 'context'. This goes beyond the schema alone.

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

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

The description clearly states the action ('Probe one or more LLMs'), the resource ('what they know about a business / brand / product / topic'), and the output ('score visibility (0-100) per model'). It distinguishes from generic Q&A tools by focusing on visibility scoring, and the specific verb+resource combination differentiates it from siblings like 'scan_competitor_ai_presence'.

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

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

The description explicitly states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional _apiKey parameter. It lacks an explicit 'when not to use' statement or alternatives, but the use cases are clear enough to guide selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable behavior: routing across 5,529 tools, filling arguments, returning structured answers with stable pipeworx:// citation URIs, and being a single fast call. It doesn't contradict annotations, and the added context enriches the safety profile without overstepping.

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

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

The description is lengthy but well-structured: it front-loads the primary directive, lists supported domains, gives examples, then delineates alternatives. Every sentence contributes value, though some redundancy exists (e.g., repeating 'use whenever' phrasing). Slightly verbose but earns its length.

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

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

Given the tool's complexity and lack of output schema, the description covers all essential aspects: what it does, when to use it, examples, alternatives, return format (structured with citations), and operational notes (works on all tiers, one fast call). It is complete enough for an AI agent to confidently select and invoke the tool.

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

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

Schema coverage is 100% with all six parameters described as aliases for the natural-language question. The description provides example queries but does not add meaning beyond the schema's alias clarification. This meets the baseline for fully documented schema parameters.

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 answers factual questions by routing to 5,529 tools across 1,455 sources, and explicitly distinguishes it from siblings like ask_pipeworx_grounded and deep_research. The verb 'ask' plus the resource and specific capabilities make the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when-not/alternatives ('use ask_pipeworx_grounded for hallucination-resistant single answer; deep_research for broad/multi-part'). It also gives concrete examples and covers breaking-news use cases.

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

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

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds valuable behavioral context: it is an experimental edge that, whenever a candidate is under test, routes queries differently and compares results against the stable router. It also clarifies that it is a full working router and does not fall back to anything. No contradictions with annotations.

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

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

The description is concise at three sentences and front-loads the core purpose. Some redundancy exists (e.g., 'Falls back to nothing — this IS a full working router' could be trimmed), but each sentence contributes essential context about the beta nature, current state, and usage.

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

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

For a complex router with no output schema, the description provides key context: identical to ask_pipeworx, same response shape, and current experimental status. It does not detail the response format, but references to ask_pipeworx and 'same response shape' give sufficient pointer for agents familiar with the sibling. A slight gap remains for agents without prior knowledge of ask_pipeworx.

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

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

The input schema covers 100% of parameters, with the question parameter description already listing all aliases. The tool description mentions 'same arguments' as ask_pipeworx but adds no additional meaning beyond the schema; the baseline of 3 applies because schema provides the necessary detail.

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 beta version of ask_pipeworx, a universal router with 5,529 tools, and explicitly distinguishes it from the stable counterpart by noting it carries experimental routing improvements. It uses a specific verb/resource structure ('Ask Pipeworx Beta') and differentiates from siblings like ask_pipeworx and ask_pipeworx_grounded.

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

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

The description explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts this with the stable router ('results are compared against the stable router to decide what merges') and provides context that no candidate is currently active, so behavior matches ask_pipeworx exactly. This gives clear when-to-use guidance and implies the 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?

While annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds valuable context: it costs an extra LLM call, returns verbatim evidence and confidence, and provides structured refusal reasons. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose, but it is somewhat dense. Each sentence contributes necessary details about routing, extraction, return format, usage, and cost, so it remains justified.

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

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

With no output schema, the description fully specifies the return object (answer, evidence, confidence, etc.) and refusal reasons, making the tool's output predictable. It also covers cost trade-offs and usage boundaries, which is comprehensive.

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

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

Schema coverage is 100% and all six parameters are well-documented aliases for 'question'. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' with a specific purpose for high-stakes reads. It distinguishes itself from the sibling tool ask_pipeworx by emphasizing grounded extraction from tool results rather than free-form answering.

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 is given: use when answers will be quoted, cited, or acted on, and when no fact invention is allowed (financial, legal, medical, public statements). It also explicitly recommends preferring ask_pipeworx for casual lookups, naming the 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive behavioral context: low-confidence short-circuiting, closed market detection, wide spread warnings, resolution-rule risk parsing, and parent event extraction. No contradictions with annotations.

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

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

The description is long and dense but well-structured with clear section headings (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.). Front-loaded with core purpose. While verbose, it earns its length by covering essential details for safe and effective tool use; minor redundancy in examples could be trimmed.

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 thoroughly documents response shapes, match confidence levels, parent events, news fallback fields, and cancellation rules. Covers edge cases (low confidence, closed markets, wide spreads, resolution risk) and provides actionable instructions (e.g., ALWAYS inspect resolver contract fields).

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

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

Schema coverage is 100% with descriptions for all three parameters (market, depth, include_raw). The description adds examples (slug, URL, question text), default values, and recommendations (e.g., 'Default thorough', 'Default false (recommended)'), slightly enhancing clarity 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 researches a Polymarket bet by pulling Pipeworx data, including specific inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It distinguishes from sibling tools like polymarket_edges by stating use cases like 'should I bet on X' versus pure edge computation.

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

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

Provides explicit guidance on when to use ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and when not (low-confidence, closed markets, wide spreads). Includes warnings to inspect resolver contract fields and cancellation rules before trusting analysis, with detailed fallback behavior and market status handling.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. It does not contradict the annotations.

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

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

The description is moderately long but dense with useful information, starting with example triggers. Each sentence contributes to understanding, though it could be slightly more concise. Overall well-structured for an AI agent.

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

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

Given the absence of an output schema, the description adequately explains return values (paired data + citation URIs) and sorting. Combined with comprehensive annotations and schema, the description is near-complete for effective tool invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining what each enum value retrieves (company: revenue, net income, cash, debt; drug: FAERS counts, FDA approvals, trial counts) and the format for values (tickers/CIKs for companies, names for drugs). This enhances parameter understanding.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, using specific verbs like 'compare', 'versus', 'rank'. It distinguishes itself from sequential single-entity lookups, making the purpose unmistakable.

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

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

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger phrases like 'compare X and Y', 'which is bigger', 'rank these companies'. This gives strong guidance on when to use the tool.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavior: account and paid-tier requirements, latency expectations (15-90s), gap[] and contradictions[] fields, fetchable citation_uri guarantees, semantic excerpting rather than head-truncation, and the 'never invented' policy. It richly complements the annotations with no contradiction.

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

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

The description is long but exceptionally well-structured and front-loaded: it opens with the account requirement and the key 'NOT open-web search' caveat. Every sentence adds a unique behavioral, usage, or output-format detail, and the logical flow (what → when → how → output → latency) makes it easy to scan. 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, the description fully specifies the return packet: findings with verbatim evidence, confidence, source, fetched_at, citation_uri, hop field, gaps[], and contradictions[]. It covers prerequisites, limitations, latency, and edge cases (e.g., citations present only when resolvable). Given the tool's complexity, this is a complete and self-sufficient description.

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

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

Schema coverage is 100% and the schema already documents question and depth in detail. The description adds context beyond the schema: the paid plan requirement for 'thorough', that question can be broad/multi-part, and concrete examples of suitable questions. This is meaningful but slightly redundant with the schema's depth enum descriptions.

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

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

The description clearly states the tool performs 'grounded multi-source research' across 1,455 structured data sources, decomposing questions into facets and routing to 5,529 tools in parallel. It explicitly distinguishes itself from open-web search and from the ask_pipeworx sibling tools, making its unique purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, with direct 'use ask_pipeworx instead' instructions for single lookups, breaking news, and unsigned users. It also clarifies depth-level tradeoffs (quick/standard/thorough) and account/paid-tier prerequisites, leaving no ambiguity about alternatives.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by explaining that results come with full schemas and curated examples, and that the tool is non-destructive. No contradiction.

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

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

The description is somewhat long but every sentence adds value. It front-loads the purpose and usage, then provides examples and return format. Could be slightly more concise, but overall efficient.

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

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

Despite no output schema, the description fully explains the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also tells the agent to call these tools directly, completing the use case.

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 clarity by listing example queries and explaining that 'query' accepts aliases (task, q, description, search), which goes beyond the schema's individual 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 starts with 'Find tools by describing the data or task,' which is a clear verb+resource. It lists many specific domains (SEC filings, FDA drugs, etc.), distinguishing it from any sibling tool. No other sibling tool is about discovering tools.

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

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

The description explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use this tool vs. alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: fans out across multiple sources, soft-fails on patents API sunset, returns specific fields like recent_filings with URIs.

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

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

Dense single paragraph with example queries upfront, then detailed output. Very efficient but could benefit from slight structuring (e.g., bullet for return items).

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

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

No output schema, but description fully covers all return components (CIK, filings, fundamentals, patents, news, LEI) and notes limitations like USPTO sunset. Complete for a complex multi-source 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 100% and description adds meaning: type is only 'company', value must be ticker or zero-padded CIK, explicitly says names not supported.

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 provides a 'full cross-source profile of a US public company' with example queries like 'Tell me about X' and lists specific outputs. It distinguishes from siblings like resolve_entity by specifying that names are not supported here.

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: 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' Also states when not to use (if only name, use resolve_entity first) and gives alternatives.

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

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

Description aligns with annotations (destructiveHint=true, readOnlyHint=false) but adds no new behavioral details beyond stating 'delete'. Annotations already convey the destructive nature.

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

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

Two concise sentences with no waste. First sentence states action, second provides usage guidance. 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 delete tool with one parameter and no output schema, the description covers purpose, usage context, and sibling relationships. Nothing missing.

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

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

Schema coverage is 100% with parameter description 'Memory key to delete'. Tool description adds no extra meaning beyond what the schema provides, meeting the baseline.

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

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

Description clearly states 'Delete a previously stored memory by key' with specific verb and resource, and distinguishes from siblings 'remember' and 'recall'.

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 provides scenarios for use (stale context, task done, clear sensitive data) and mentions pairing with related tools, but lacks explicit when-not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read-only operation. The description adds behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also states the output is a single text blob. However, it doesn't disclose potential failure modes or rate limits, which are not critical given the safe annotations.

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

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

The description is concise: two sentences plus a bulleted use-case list. The primary action is in the first sentence, and the output details are in the second. The list adds clarity without excessive length. Slightly more compact could be achieved by merging the list into a sentence, but it's well-structured overall.

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 moderate complexity (2 simple parameters, full schema coverage, annotations present, no output schema), the description is adequately complete. It explains the tool's operation, output format, and use cases. It does not cover edge cases like invalid URLs, but for a straightforward generation 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 the schema already documents both parameters. The description does not add new information beyond what the schema provides (e.g., default and max for max_links are already in schema description). Thus, the description adds marginal value for parameter semantics, warranting a baseline score of 3.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for a URL. It uses specific verbs ('Generate', 'Fetches', 'extracts', 'emits') and identifies the resource (llms.txt file). The tool is distinct from sibling tools like 'scan_competitor_ai_presence' or 'ai_visibility_check' which focus on analysis rather than file generation.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting own llms.txt, or auditing competitor visibility. While it doesn't specify when not to use this tool or mention alternatives, the use cases are clear and sufficient for most scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about default active-only and optional include_inactive.

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

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

Two sentences, front-loaded with purpose, 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?

Simple tool, return fields listed, usage guidance given, no gaps given lack of output schema.

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

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

Schema coverage is 100% and the description does not add meaning beyond schema for the single parameter.

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

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

Description clearly states 'List the caller's active subscriptions' and enumerates return fields. Distinct from siblings like subscribe/unsubscribe.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.'

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?

Despite annotations only providing false hints (readOnly, idempotent, destructive), the description adds substantial behavioral context: rate limiting (5 per identifier per day), free usage that doesn't count against tool-call quota, and the claim_token mechanism for retrieving resolution status. It also notes the team reads digests daily, setting expectations for response time.

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 typical, but every sentence provides valuable guidance: purpose, usage triggers, exclusions, token flow, rate limits, and quota. It is front-loaded with the core purpose and structured logically. A slight reduction in length could improve readability, but no information is redundant.

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

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

For a feedback tool with 4 parameters and no output schema, the description covers all essential context: what to report, what not to report, how to frame issues, the claim_token lifecycle, rate limits, and next steps. It fully equips the agent to use the tool appropriately even without an output schema.

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

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

Schema covers all parameters with descriptions, so baseline is 3. The description adds meaningful semantics beyond schema: explains how to use claim_token (pass alone, no other args), instructs users to describe issues in terms of Pipeworx tools/packs (not end-user prompts), and clarifies that context is optional structured metadata. This enrichment justifies above baseline.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about something broken, missing, or worth praising. It explicitly lists feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx by framing it as reporting rather than asking.

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 scenarios for each feedback type and provides a clear exclusion: do not report issues for tools from other MCP servers, with specific instruction to file with that server instead. It also explains the claim_token follow-up flow, which is actionable 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. Description adds caching duration (5min-1h), privacy (no PII), and derivation from CF analytics-engine. 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?

Front-loaded with core functionality. Second sentence lists use cases. Slightly wordy but every sentence serves purpose (caching, privacy, window guidance). Could be trimmed but acceptable.

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 single optional param, no output schema, and low complexity, description fully covers purpose, behavioral traits, parameter guidance, and use cases. No gaps.

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

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

Schema covers the parameter fully (enum, description). Description adds semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds value beyond schema.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a chosen window. Distinct from siblings like 'discover_tools' or 'subjects' by focusing on trending usage data.

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

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

Lists three specific use cases (discovering hot data sources, confirming canonical tool, aligning use case) and explains window trade-offs. Lacks explicit when-not-to-use or alternatives, but 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 already declare readOnlyHint and idempotentHint; the description adds rich behavioral context: internal monotonicity checks, partition checks, Jaccard similarity filter, placeholder filter, fill check against live CLOB depth. No contradictions with annotations. Description adds significant value beyond structured fields.

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

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

The description is lengthy but front-loaded with the core purpose. Each section adds value for a complex tool. Some redundancy exists (e.g., partition check details repeated), but overall efficient for the detail provided.

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

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

No output schema, so description must explain response format. It does: 'Response: opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' plus partition_check details and fill check. Covers edge cases like placeholders and low similarity. References related tool for custom sizing. Complete given complexity.

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

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

Schema description coverage is 100%, and the description goes further with examples of event slugs and seed questions, explaining mode-specific behavior (e.g., event mode walks child markets, topic mode searches related events). Adds substantial meaning beyond the schema definitions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between four modes (no args, event, topic) and explains what each does. It effectively differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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: 'Call with NO args for a trending_scan... pass `event` for strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also advises when not to trade based on fill check results and references polymarket_fill_risk for custom sizing, covering both when-to-use and alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds significant behavioral context: caching (cached 1h), diagnostics for empty segments, edge calculation details, slippage assumptions, and data limitations (Fed signal unreliable). 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: purpose first, then segments, edge components, knobs, response structure. It is verbose (500+ words) but the complexity of the tool justifies the length. Minor conciseness improvements possible.

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 thoroughly explains the response structure (by_segment, diagnostics, fed_candidates) and caching behavior, making the tool's behavior fully understandable for an AI agent.

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

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

Schema coverage is 100% with good descriptions. The description further enriches understanding by explaining the role of knobs like min_liquidity, max_spread_pp, and min_partition_leg_kelly in the context of tradeable-edge filtering, adding value beyond the schema.

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

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

The description states a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage by focusing on Pipeworx data and discovery use case.

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

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

The description explicitly frames the tool for 'what should I bet on today' and 'agents discover opportunities without paging hundreds of markets.' It provides context on when to use and mentions limitations (e.g., Fed bets excluded from ranking), but does not explicitly name alternatives or provide when-not guidance relative to siblings.

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

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

The description details behavior: returns tracked[] with time-series, trend, decay; expired[] with lifespan; snapshot dates. It also discloses limits (60-day TTL, start of snapshotting, daily closes). Annotations already mark readOnly, idempotent, and non-destructive, so the description adds valuable context beyond that.

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

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

The description is dense but well-structured: starts with purpose, then response fields, then limits. However, it is a single long paragraph that could be broken into sections for readability. Every sentence adds value, but structure could be improved.

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

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

Given the tool has 2 optional parameters, no required fields, and no output schema, the description comprehensively explains the return structure (tracked, expired, snapshot_dates) and limitations. It covers what the agent needs to understand the tool's output without additional 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?

Input schema covers both parameters with descriptions. The description adds default values and clamps (days: default 14, max 30; window: default '1wk'), which is helpful but not extensive. With 100% schema coverage, baseline is 3; description provides minor added context.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from historical snapshots. It answers a specific question about edge longevity and distinguishes itself from sibling tools like polymarket_edges (current edges).

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

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

Usage is implied by the description (historical context for edges), but there is no explicit guidance on when to use this tool versus alternatives like polymarket_edges or what scenarios to avoid. The sibling list includes relevant tools but no contrast.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond annotations: it walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and forced_directional_risk. It does not contradict annotations. Minor deduction for not explicitly stating it does not modify state, but annotations cover that.

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

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

The description is verbose but well-structured. It starts with the core purpose, then details single-market and basket modes in separated paragraphs. Every sentence adds unique information. A slight reduction from 5 due to length; it could be more concise while retaining the same information.

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

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

Given the tool's complexity (two modes, no output schema), the description is remarkably complete. It explains all return fields for both modes, including edge cases like thin_legs, max_clean_notional_usd, and forced_directional_risk. It also provides practical usage context. Without an output schema, the description carries a heavy burden, and it succeeds fully.

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 significant value beyond the schema: it explains the mutual exclusivity of market/event, the default side behavior (auto for basket), and the interpretation of size_usd for buys vs sells. These semantics are not obvious from the schema alone, so score 4.

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

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

The description clearly states the tool's purpose: a realizable-vs-theoretical edge check against live order-book depth. It distinguishes between single-market and basket modes, and the verb 'check' and resource 'edge' make the action and object explicit. Siblings like polymarket_arbitrage and polymarket_edges are different in scope, so this tool is well-differentiated.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about partial basket fills converting arb into directional position, providing clear when-to-use and the risks of not using it. This is exemplary usage guidance.

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

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

Beyond the annotations (readOnly, idempotent), the description extensively discloses behaviors: compatibility_warning conditions, temporal alignment, skipped cross types, and limitations. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose. While lengthy, every sentence adds value. Minor conciseness could be improved but overall 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?

For a tool with no output schema, the description provides an extensive breakdown of the response structure, including raw probabilities, spread, safety fields, and counters. It covers usage, modes, and pitfalls comprehensively.

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

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

Schema coverage is 100% with basic descriptions. The description adds extra context: the list of topic values, the override behavior of explicit tickers, and examples in the schema examples field. This adds meaningful value beyond the schema.

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

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

The description precisely states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes two modes (topic shortcuts and explicit tickers) and is unique among sibling tools.

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

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

The description provides explicit guidance on when to use each mode, including the list of pre-mapped topics. It also warns that real spreads are rarer than shortcuts suggest and explains safety fields that indicate when output is meaningful.

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 minimal behavioral context (just 'pull data' and the query object format). It does not explain output format, error handling, or any side effects beyond what annotations imply.

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

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

The description is concise at two sentences with no redundant words. It efficiently communicates the core action and the nature of the body parameter.

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

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

Despite having an output schema, the description does not mention the return format or provide enough context for a domain-specific tool (PxWeb). The minimal description leaves the agent with insufficient information to form a complete mental model.

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 meaning by stating the body is a 'PxWeb query object', which contextualizes the nested schema. However, with schema coverage at 50%, it does not describe the 'path' parameter, leaving some ambiguity.

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

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

The description clearly states the tool pulls data from a table and mentions the body is a PxWeb query object, providing a specific verb and resource. However, it does not differentiate from the sibling tool 'table_meta', which likely retrieves metadata instead of data.

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

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

No guidance is provided on when to use this tool versus alternatives like 'table_meta' or other search tools. The description lacks context on appropriate use cases or when not to use it.

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

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

Adds important behavioral context beyond annotations: scoping to user identifier and the behavior of listing all keys when key omitted. No contradiction with readOnly/idempotent/destructive hints.

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 with no waste. The purpose is stated first, then usage examples and scope, finally pairing with related tools.

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

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

For a simple retrieval tool with no output schema, the description fully covers return behavior, scope, and integration with other tools. No gaps.

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

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

Schema coverage is 100% with a clear description. The description reinforces the 'omit to list all keys' behavior, adding slight value over 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 retrieves a saved value or lists all keys, using specific verbs 'retrieve' and 'list'. It distinguishes from siblings by naming 'remember' and 'forget' directly.

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

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

Provides clear examples of when to use (e.g., look up ticker, address, notes) and scoping info. Mentions pairing with 'remember' and 'forget' but does not explicitly contrast with search-based siblings.

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

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

Annotations indicate read-only, idempotent, not destructive. The description adds that it returns most recent alerts with specific fields, explains mark_read and unread_only behavior, and mentions polling suitability. No contradictions.

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

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

Four sentences conveying essential information without redundancy. Front-loaded with main purpose, then details. Every sentence adds value.

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

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

No output schema, so description compensates by listing returned fields (source, citation_uri, raw event payload) and explaining filter/mark_read behavior. Also notes polling and alternative access method. Completes the picture for a 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% with clear descriptions. The description adds semantic value for type (example) and mark_read (effect on subsequent calls). Limit and unread_only are explained in schema, so additional benefit is moderate.

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

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

The description clearly states it pulls 'fired events from your subscription feed' and specifies the returned data (source, citation_uri, raw payload). This distinguishes it from sibling tools like list_subscriptions which list subscriptions, not events.

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

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

Provides guidance on filtering by type and since, and the effect of mark_read. Mentions polling is fine and points to an alternative URL for scripts/dashboards. Does not explicitly state 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: fallback from GDELT to GNews on rate limits/5xx, soft-fail for USPTO due to API sunset, and return of citation URIs. No contradiction.

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

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

The description is comprehensive yet efficient, front-loading with natural language examples, covering all key aspects (sources, fallback behavior, parameter details, output structure) without redundancy.

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

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

Despite no output schema, the description explains return values (structured changes grouped by source, total_changes count, pipeworx:// URIs). It also covers edge cases like fallback and soft-fail, making it complete for effective use.

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

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

Schema coverage is 100%, providing good descriptions for all parameters. The description adds extra usage advice like 'Use "30d" or "1m" for typical monitoring' for the since parameter, adding value beyond the schema.

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

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

The description clearly defines the tool as a change feed for a company, listing example queries and distinguishing it from entity_profile for static profiles. It specifies the data sources (SEC EDGAR, GDELT/GNews, USPTO) and the result format.

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 this tool (recent changes over a window) and when to use the sibling entity_profile instead (static profile regardless of window). Provides direct 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 behavioral traits beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. Contains no contradictions with annotations (idempotentHint=true, destructiveHint=false, readOnlyHint=false).

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

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

Four sentences, each earning its place: purpose, usage trigger, technical details, and companion tools. Front-loaded with the most important information. No wasted words.

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

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

Despite lacking output schema, the tool is simple enough that the description covers all necessary context: what it stores, when to use, scoping, retention, and related tools. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description provides example key names but doesn't add semantic value beyond what the schema already conveys for key and value.

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

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

The description clearly states the tool saves data for reuse later, with specific verb ('Save data') and resource ('key-value pair'). It distinguishes from siblings like recall and forget, making its 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 when to use ('when you discover something worth carrying forward'), provides context on scoping and session persistence, and mentions companion tools (recall, forget). This gives clear guidance on 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 readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral context beyond these: graceful degradation (EDGAR identifiers return even if GLEIF/OpenFIGI fail), unresolved identifiers are explicitly listed rather than omitted, every identifier is labeled with its source, and the internal cascade across endpoints is disclosed. 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 front-loaded with query examples to anchor the user. Every sentence carries useful information, including supported types, enrichment behavior, fallback, and return-value semantics. A slight redundancy exists in repeating the type list, but overall it is well-structured and purposeful.

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 structure: source-labeled identifiers, explicit unresolved list, RxCUI citation for drugs, and graceful degradation behavior. It covers caveats and use cases comprehensively for a tool with 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?

The input schema covers both parameters thoroughly (enum for type, description for value with examples). The description reinforces this by giving concrete examples ('AAPL', '0000320193', 'ozempic') and clarifying which input forms apply to each entity type, adding some value beyond the schema.

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

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

The description opens with concrete natural-language query examples ('What's the ticker for…', 'find the CIK for…') and states the core mission: resolve a user-spoken NAME to canonical identifiers required by other tools. It clearly distinguishes itself from sibling tools like entity_profile by focusing on identifier resolution, and the supported types (company, drug) are explicitly listed.

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 direction: 'Use FIRST whenever you have a name but need an ID.' This is strong situational guidance. It also notes that one call replaces 2-3 manual lookups. However, it does not mention specific alternative tools or when not to use it, so it lacks full exclusion guidance.

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

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

The description adds behavioral context beyond annotations by stating it 'probes each entity with ai_visibility_check' and returns a ranked list with score, confidence, signal density. No contradictions with annotations.

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

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

Two sentences plus an example question; front-loaded with purpose. Every sentence adds value without extraneous wording.

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 adequately explains the return format (ranked list with score, confidence, signal density). It also clarifies the internal call to ai_visibility_check. Could mention limits or error handling, but overall complete.

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

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

Schema coverage is 100%, but description adds value by noting that the first entity is treated as the 'subject' for narrative and providing guidance on models omission. This extra context improves parameter understanding.

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

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

The description states the specific verb 'compare' and resource 'AI visibility' across multiple entities. It distinguishes from siblings by mentioning it probes with ai_visibility_check and ranks results. The purpose is concrete and differentiated.

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?

Usage is clarified with an example ('does Claude know about us as well as our competitors?') and context ('competitive AI-marketing audits'). However, it does not explicitly state when not to use or list alternatives.

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

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

Description adds significant behavioral detail beyond annotations: partial graceful degradation, 5-30s initial measurement for new versions, listing sources_failed on timeout. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, and description does not contradict them.

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

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

Description is a single dense paragraph that front-loads the core purpose and provides all necessary details. Though it could be slightly more structured (e.g., bullet points for return fields), it is efficient and well-written.

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 enumerates the return values (summary block, per-advisory detail, links, alternative versions). It also explains edge cases like partial failures and timing. This makes the tool fully understandable for an AI agent.

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

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

Input schema has 100% coverage, but description adds extra context: scoped packages are accepted for the 'package' field, and 'version' defaults to latest when omitted. This enriches the schema information.

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

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

Description clearly states the tool performs a composite check for npm package suitability, covering license, advisories, bundle size, and more. It uses specific verbs and resource, and clearly distinguishes from other tools by focusing on npm packages and combining multiple sources.

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

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

Explicitly states when to use: when agent asks about safety, popularity, size, or cost of adding a package. Also mentions that other ecosystems are covered by a different tool, providing clear usage boundaries and alternatives.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. Description adds behavioral details: embedding model (BGE-base-en), windowing (500-char overlapping windows), character cap (200K chars, truncated and flagged), and return format (character offsets, similarity scores). No contradictions.

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

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

The description is fairly long but well-structured with bold key terms and front-loaded purpose. Each sentence adds value, explaining usage, pairing, and technical details. Slightly verbose but justified by the need to cover embedding, windowing, and limits.

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 effectively explains return values (passages with offsets and scores) and limitations (200K cap, truncation). It also covers pairing and technical details, making the tool's behavior fully understandable 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 descriptions for all parameters. The description adds extra value by clarifying the truncation behavior ('longer inputs are truncated and flagged'), which is not in the schema. However, the schema already provides good baseline meaning, so this is a slight improvement.

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: semantic search inside a fetched record. It specifies inputs (already-fetched text + natural-language query) and outputs (top-N passages with offsets and scores). It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Provides pairing guidance with ask_pipeworx_grounded, indicating alternatives and complementary 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 indicate the tool is read-only and non-destructive. The description adds valuable context by stating the listing carries no observations and no time period, making clear it cannot answer time-bound questions. This is a useful behavioral boundary beyond the annotation hints.

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

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

The description is concise, front-loaded with the core purpose, and each sentence earns its place: purpose, usage, limitation, and geography-specific alternatives. No redundant information or filler.

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

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

For a low-complexity tool with one optional parameter and an output schema, the description fully covers the decision-relevant context: when to use it, what it returns, what it doesn't return, and which sibling tools to use instead for different intents. 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?

The single parameter 'path' is fully described in the input schema (sub-path under /ssd/, default empty = root). The description does not add much beyond what the schema provides, but the schema coverage is 100%, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool is a catalogue of Statistics Sweden's published subjects, returning a browsable list of subjects and table paths. It distinguishes itself from siblings by positioning itself as the discovery step before reading actual figures.

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 it ('which Swedish statistics exist or where a table lives'), directs to table_meta and query_table for reading figures, and names sweden_latest_figure for direct figure answers. It also lists what it cannot answer (month/year queries) and provides alternatives for other countries.

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

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

The description discloses key behaviors: OAuth requirement, delivery channels (feed, email, SMS, webhook), SMS caps, webhook auto-disable after 10 failures, and HMAC signing. However, it does not address the idempotentHint annotation (whether duplicate subscriptions are prevented), which is a minor gap.

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

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

The description is well-structured with clear front-loading of purpose and logical grouping of type and delivery details. While somewhat lengthy, every sentence adds useful information; minor redundancy with schema descriptions could be trimmed.

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 is comprehensive for a complex tool with nested objects, multiple types, and delivery options. It covers prerequisites, type-specific parameters, delivery channels with constraints, and return value (subscription ID), leaving 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?

Despite 100% schema coverage, the description adds significant value by explaining each type with concrete examples (e.g., sec_8k with items, polymarket_edge with topic), detailing delivery sub-options and constraints (e.g., phone verification, webhook signing), which goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool creates a 'proactive monitoring subscription to a live-data event stream' and returns the subscription ID. It uses a specific verb and resource, and distinguishes itself from siblings like unsubscribe 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?

The description provides clear context for when to use the tool (proactive monitoring) and lists prerequisites (Pipeworx OAuth account). It explains supported types with examples but does not explicitly state when not to use it or compare with alternatives like polling via recent_alerts.

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 that it is the onboarding entry point, returns example questions drawn from the live catalog, and that results vary by topic. It does not contradict annotations and adds useful behavioral context, though it could mention that the examples are generated from the tool catalog (which is implied).

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 clear purpose at the start, followed by what it returns and how to use it. It is slightly long due to listing topics and alternatives, but every sentence adds value. The front-loading of example queries makes it effective.

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

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

Given the tool's simplicity (1 optional parameter, no output schema, low complexity), the description fully covers its purpose, usage, return behavior, and relationship to other tools. It provides enough context for an agent to decide when and how to invoke 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% (only 'topic' parameter described). The description adds meaning beyond the schema by explaining the effect of omitting vs. providing topic, listing specific values (finance, pharma, etc.), and stating that calling without arguments gives a full spread. This enriches the schema information.

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 an onboarding entry point that returns category-bucketed example questions. It lists specific queries users might type and explains it guides the agent on what is worth asking. It distinguishes from siblings like ask_pipeworx and discover_tools by focusing on generating example questions with tool+argument shapes.

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

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

The description explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also lists alternative tools (ask_pipeworx, entity_profile, compare_entities) and provides context for when the agent just connected.

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 read-only, idempotent, and non-destructive. The description adds useful context about returned fields (figure, unit, month, SCB table) and scope, but does not mention error or edge-case behavior beyond what the schema covers.

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?

Front-loaded and mostly concise, but example phrases are repeated twice with slight variation, making it a bit redundant. Still, all content is relevant 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?

For a simple two-parameter tool with strong annotations and full schema coverage, the description is complete: purpose, usage context, return contents, and scope are all covered. No output schema exists, but the description enumerates return fields.

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 fully describes the indicator and period parameters, including common phrasings. The description does not add significant new parameter semantics beyond what is in the schema.

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

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

The description clearly states the tool returns a numeric Swedish headline statistic (inflation or CPI index) for the latest or a specified month, with examples. It explicitly distinguishes itself from the subjects tool by contrasting number questions with existence questions.

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 when the question asks for a number, and use the subjects tool when the question asks what statistics exist. Also clarifies one-call behavior and the optional month parameter.

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 already declare read-only, idempotent, and non-destructive behavior, lowering the bar. The description adds that this is a prerequisite and provides metadata for querying, offering useful context beyond the annotations without contradicting them.

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

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

The description is three sentences, each serving a distinct purpose: defining the tool, stating its prerequisite role, and directing how to find the path. No wasted words.

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

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

With one parameter, an output schema, and strong annotations, the description fully covers the tool's role in the workflow. It explains why to use it and how it relates to other tools, 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% for the single 'path' parameter, which already includes a description and example. The description reinforces the path format with an example and adds the dependency context, slightly enhancing the schema's 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 tool provides dimension definitions and valid filter values for a specific Statistics Sweden table, with an example path. This makes its purpose distinct from sibling tools like query_table (data retrieval) and subjects (path discovery).

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

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

It explicitly instructs to use this tool before scb_se_query_table and after scb_se_subjects, establishing a clear sequence and naming the alternative tools. This is excellent guidance on when and how to use the tool.

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

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

Adds significant behavioral info beyond annotations: ownership enforcement, deactivation (not deletion), and relation to 'recent_alerts'. Annotations already indicate idempotency and non-destructiveness but description adds context.

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

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

Two sentences, no filler. All sentences provide essential information. Efficient and front-loaded.

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

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

Complete for a simple tool with one parameter. Explains ownership, behavior, and historical data access. Sufficient given no output schema.

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

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

Schema coverage is 100% and the description doesn't add beyond what the schema says for 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 clearly states 'Cancel a subscription by id', with a specific verb and resource. It distinguishes 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?

Provides clear context: ownership enforcement and deactivation behavior. However, it doesn't explicitly state when to use this over alternatives like 'list_subscriptions' or explicitly mention non-usage scenarios.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower, but the description adds rich behavioral context: the dual pipeline (SEC EDGAR fast path vs grounded pipeline), exact percent-delta math, verdict categories, citation behavior, and a critical warning about could_not_verify being neutral. This exceeds what annotations provide.

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

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

The description is longer than minimal, but every section earns its place: trigger phrases, main purpose, use case, pipeline breakdown, return values, and an important error-semantics warning. It is well-structured, front-loaded with the core purpose, and contains no fluff.

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

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

With no output schema, the description fully explains return values (verdict set, actual value with citation, reasoning) and error semantics (could_not_verify vs unsupported). It covers the key behaviors and caveats a caller needs, making the tool's behavior predictable.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds no parameter-specific details beyond mentioning 'exact percent-delta math,' which indirectly relates to tolerance_pct but doesn't explain the parameter syntactically. 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 identifies the tool as natural-language claim verification with specific trigger phrases, a specific verb ('validate claim'), and a clear resource ('against authoritative sources'). It distinguishes itself from siblings by noting it replaces 4–6 sequential calls and handles both structured financial claims and arbitrary factual claims.

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

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

The description gives explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' This is clear context for when to use, but it does not explicitly state when not to use or name alternative sibling tools. Lacks the when-not/alternatives nuance for a 5.

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