Cbs Il

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds cost implications (BYO key for Anthropic) and return structure details (per-model and combined view). No contradictions; the extra behavioral context is valuable.

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

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

The description is four sentences, each serving a distinct purpose: function, model details, output, use cases. It is front-loaded and contains no fluff or repetition.

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

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

With no output schema, the description compensates by explaining per-model fields and combined view. It covers scoring range and model options, but lacks details on error handling or 'signals' specifics. Still generally 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?

The input schema already describes all four parameters with 100% coverage. The description adds minor context (default model, cost for _apiKey) but does not significantly surpass the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb (Probe), resource (LLMs), and output (visibility score 0-100), with specifics on default model and optional Anthropic. This unambiguously distinguishes it from sibling tools 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 lists three explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), providing solid context for when to use. However, it does not mention exclusions or compare to alternatives, preventing a perfect score.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the description only needs to add extra behavioral context. It does add useful detail: the tool routes across 5,798 tools and 1,517 sources, fills arguments, and returns structured answers with citation URIs. It does not disclose limitations, freshness guarantees, failure modes, or the full output format beyond the citation URI mention.

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

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

The description is front-loaded with the most important directive, 'PREFER OVER WEB SEARCH', and the domain list is useful. The examples earn their place. However, the dangling 'START HERE for most questions — except' ending is confusing and makes the description feel incomplete, which hurts its structural quality.

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 broad routing tool with no output schema, the description adequately explains what the tool is for, when to use it, and what kind of answer to expect: structured data with citations. It is missing explicit exclusions or limitations, details about answer freshness or reliability, and the content implied by the truncated 'except' clause. An agent can likely invoke it correctly, but some selection context is incomplete.

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 'question' parameter is already documented with aliases, so the baseline is 3. The description adds value through example natural-language queries that clarify expected input shape, such as 'What was Apple's revenue in 2024?' and 'Current price of bitcoin'. It does not reach 5 because it adds no parameter-specific syntax, constraints, or formatting rules.

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 question router that finds authoritative structured data and returns answers with stable pipeworx:// citation URIs. It lists concrete domains such as SEC filings, FDA data, economic statistics, and patents. However, it does not explicitly distinguish itself from sibling variants like ask_pipeworx_beta or 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 strongly signals when to use the tool: prefer over web search for factual, current, or historical data questions, and it lists trigger phrases like 'what is', 'look up', 'find', and 'get the latest'. It also gives six concrete examples. It lacks explicit when-not-to-use guidance, and the final 'except' clause is left incomplete.

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 read-only/idempotent annotations, the description adds valuable behavioral context: it is an experimental edge, no candidate is currently active, it currently matches ask_pipeworx exactly, it is a fully working router with no fallback, and results are compared against the stable router. This gives the agent an accurate picture of live behavior and risk.

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 composed of four purposeful sentences and front-loads the beta identity and current equivalence to ask_pipeworx. The retirement date and parenthetical about comparison are slightly detailed, but every sentence contributes meaningful operational 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?

For a universal router with a simple single-required-parameter schema, the description is complete: it states current behavior, equivalence to the stable tool, the experimental nature, the lack of fallback, and the evaluation purpose. No essential calling information is missing.

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

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

Schema description coverage is 100%, with all aliases documented in the input schema. The description adds only the general statement that arguments match ask_pipeworx, which is not needed since the schema already fully explains each 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 identifies this as the beta universal router version of ask_pipeworx, with the same 5,798 tools, same arguments, and same response shape. It also differentiates from the stable ask_pipeworx tool by explaining that candidate routing improvements are enabled live when under test.

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 says to use it exactly like ask_pipeworx when you want the newest routing, which gives a clear usage condition and names the primary alternative. It does not explicitly state when NOT to use it in favor of stable ask_pipeworx or ask_pipeworx_grounded, so it stops short of a 5.

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

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

The description goes far beyond the annotations by explaining that answers are extracted only from tool results, that refusals occur with specific reasons, and by enumerating the exact success and refusal return shapes. This adds significant behavioral context beyond readOnlyHint, openWorldHint, and idempotentHint, with no contradiction to 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 dense but every sentence earns its place: purpose, routing behavior, return contract, refusal reasons, usage guidance, and cost trade-off. Key differentiators are front-loaded, and there is no filler or repetition of schema content.

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

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

Given there is no output schema, the description fully compensates by documenting both success and refusal response structures. It also covers when to use the tool, when not to, and the cost implication, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, and the schema already explains the question parameter and its aliases. The tool description does not add parameter-level meaning beyond that, which matches the baseline for high schema coverage.

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

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

The description clearly identifies this as a hallucination-resistant grounded answer mode for high-stakes reads, and explicitly distinguishes it from ask_pipeworx while acknowledging shared routing. It states a specific verb, resource, and behavioral scope, making the tool's role easy to distinguish from siblings.

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

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

The description gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on, and facts must not be invented. It also names the alternative, ask_pipeworx, and provides a concrete trade-off: prefer it for casual lookups because this tool costs an extra LLM call.

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 numerous behavioral traits beyond annotations: fan-out logic, response shapes, resolver confidence levels, parent event extraction, news fallback handling, safety short-circuits for low confidence, closed markets, wide spreads, and resolution-rule risk. Annotations already mark it as read-only and idempotent, and the description adds extensive transparency.

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

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

The description is lengthy but well-structured with clear headings and logical sections. Every sentence adds value, covering input, processing, output, edge cases, and safety. However, it could be slightly more concise, but for a complex tool, the detail is 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?

Given the tool's complexity, the description is exceptionally complete. It covers input handling, classification, fan-out, output shapes (result.market, result.analysis, result.evidence), resolver contract, parent event extraction, news fallback, safety mechanisms, and resolution rules. No output schema exists, so the description fully informs the agent.

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

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

Schema coverage is 100%, so the schema fully documents parameters. The description adds value by clarifying the market parameter's accepted formats (slug, URL, question text), the depth enum's behavior (quick vs thorough), and include_raw's implications. This enhances understanding beyond the schema.

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

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

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

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides context on when to use the tool but does not explicitly exclude scenarios where sibling tools are better, though that is implied.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), description adds hierarchical behavior: returns top-level subjects with ids, drilling down yields leaf series paths with breadcrumb and name. No contradictions.

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

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

Two paragraphs, every sentence adds value. No fluff. Front-loaded with the main verb and resource.

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

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

No output schema, but description fully explains return structure: top-level subjects with path ids, leaf series with path breadcrumb and name. Covers all 3 parameters adequately.

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

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

With 100% schema coverage, baseline 3. Description adds significant value: explains subject_id as id from no-arg call with examples (8=Foreign Trade), page for paginated leaf lists, and lang for language.

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 browses a CBS time-series catalog, explains the hierarchical structure, and distinguishes from get_series_data. It uses specific verbs like 'browse' and 'discover what's available'.

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: 'before calling get_series_data' to discover what's available. Also implies when not to use (for data retrieval, use get_series_data).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: off-calendar fiscal year handling, results sorted by primary metric, and citation URIs per entity. This goes beyond what annotations provide.

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

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

The description is dense but front-loaded with common query formats. Every sentence adds value, though the length is justified by the complexity. Could be slightly more concise, but it is well-structured.

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

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

Given the tool has 2 parameters and no output schema, the description adequately covers type-specific data sources, constraints, sorting behavior, and return format (paired data + URIs). It is complete enough for an AI agent to use correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning by explaining what each type (company vs drug) pulls and giving concrete examples for the values parameter (tickers/CIKs for companies, drug names).

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 performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, using specific data sources (SEC EDGAR for companies, FAERS for drugs). It distinguishes itself from sequential single-pack lookups and provides many example query phrases.

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 'ALWAYS PREFER over sequential single-pack lookups' and gives clear usage examples. It does not mention when not to use, but the guidance is strong and context-rich.

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 substantial behavioral context beyond the annotations: account requirements, paid tier for thorough depth, parallel decomposition, explicit gaps[] with 'never invented' guarantees, resolvable citation_uri conditions, contradiction scanning for standard/thorough, semantic excerpting, and latency expectations. Annotations already mark the tool as read-only, open-world, and idempotent; the description complements rather than contradicts them.

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

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

The description is long, but every clause carries useful information and it is front-loaded with the account requirement and primary alternative. It uses a logical flow: auth prerequisites, core behavior, ideal use case, depth-specific behavior, output guarantees, and performance. While longer than minimal definitions, the complexity of the tool justifies the length without significant waste.

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 only two parameters, no output schema, and a complex research behavior, the description covers everything needed: auth, paid tiers, source scope, decomposition mechanics, return packet shape, gaps handling, citation resolvability, contradictions, excerpts, and expected latency. No critical behavior is left undefined.

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

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

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds value by expanding depth semantics with practical implications: 'standard' re-angles unanswered gaps, 'thorough' chases leads and costs more, and latency varies by depth. It also reinforces that the question parameter is meant for broad/multi-part natural language queries, which goes slightly beyond the schema's description.

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

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

The description uses a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' and clarifies this is 'NOT open-web search.' It explicitly states the tool's scope (broad/multi-part questions over structured data) and distinguishes itself from ask_pipeworx, which handles single lookups. Clear enough for an agent to differentiate without inspecting sibling schemas.

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 provides when to use this tool ('Best for broad/multi-part questions over structured data') and when not to use it ('For a single lookup use ask_pipeworx instead'). It also names the alternative and the prerequisite: 'If you are not signed in, use ask_pipeworx instead.' This leaves no ambiguity about routing.

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 and idempotent behavior. The description adds that results include full input schemas with curated examples, ready to call directly. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and usage instruction. It lists many example domains, which is helpful but slightly verbose. Overall well-structured and clear.

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

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

Given no output schema, the description adequately explains what is returned (top-N relevant tools with names, descriptions, and schemas). For a discovery tool with simple behavior, this is complete and sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add additional semantics beyond the schema for parameters, but it does explain the overall purpose of the query parameter. The aliases are noted but add minimal 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 explicitly states the tool discovers tools based on a natural language description of data or task, listing many domains. It clearly distinguishes from siblings like catalog_browse or search_within by focusing on tool discovery rather than data search.

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

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

The description advises using this tool when browsing or discovering tools and explicitly says 'Call this FIRST when you have many tools available.' It provides clear context but does not mention when to use alternatives 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?

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds rich behavioral context beyond those hints: it fans out across SEC, XBRL, USPTO, USAspending, FDA, DOL, news, and GLEIF; empty sections mean real absence of data; USPTO sunset soft-fails until reactivated; and FDA section absence is expected for small-molecule-only companies. This substantially prevents misinterpreting results.

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 almost every clause earns its place because it encodes return sections, soft-fail behavior, expected empty results, and parameter semantics. It is front-loaded with trigger examples and the core purpose. It could be slightly improved with bullet-point formatting, but it is not padded or 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 complex tool with no output schema, this description is unusually complete. It enumerates every returned section, explains `sources_used` / `sources_failed`, warns about expected empty sections, covers private-company behavior, and defines accepted value shapes. An agent has enough context to invoke the tool correctly and interpret its results without additional lookups.

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

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

Schema coverage is 100%, but the description adds meaningful clarification: `type` accepts 'company' or 'ticker' interchangeably and both accept ticker, CIK, or company name. It also explains name resolution via SEC EDGAR and gives concrete examples like 'AAPL', '0000320193', and 'Moderna', which removes ambiguity 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 uses specific verbs and resources: it is a 'full cross-source profile of a US public company in ONE parallel call' triggered by phrases like 'tell me about X' and 'brief me on Tesla.' It clearly distinguishes itself from single-pack SEC/XBRL/news lookups and from sibling research tools by emphasizing one-call holistic coverage.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also describes fallback and failure behavior, such as private companies returning resolved:false with a notes line instead of a bare failure, helping the agent decide when this tool is appropriate.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description confirms deletion but adds no new behavioral context beyond what annotations and schema 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 two sentences long, directly states the purpose and usage, and is front-loaded with the core action. No unnecessary words.

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

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

For a simple tool with one required parameter and no output schema, the description adequately covers purpose, usage, and context. It pairs with siblings and provides complete guidance.

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 'key' is fully described in the schema ('Memory key to delete'). Schema coverage is 100%, so the description adds no additional semantic value beyond the schema.

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

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

The description clearly states the action (delete) and the resource (a previously stored memory by key). It distinguishes from sibling tools like remember and recall by specifying deletion.

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

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

Explicitly lists use cases (stale context, task done, clear sensitive data) and recommends pairing with siblings (remember, recall), providing clear when-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds specific process details ('Fetches the page, extracts title/description/key links') and output format, providing transparency 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 succinct sentences: first states purpose and output, second explains process, third lists use cases. It is front-loaded, every sentence adds value, and there is no redundancy.

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

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

For a tool with two simple parameters, no output schema, and safe annotations, the description covers all necessary aspects: what it produces, how it works, and when to use it. The return format is described as 'single text blob' in standard markdown, which is sufficient given the tool's simplicity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description echoes the schema with examples and default/max values, adding some clarity but not significant new meaning beyond what the schema already provides.

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

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

The description clearly states the action ('Generate'), the resource ('a production-ready llms.txt file'), and the target audience ('AI crawlers'). It distinguishes itself from siblings by specifying the output format and use cases, making the tool's unique purpose unambiguous.

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

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

The description explicitly lists three use cases: indexing a client's site, drafting for one's own project, and auditing a competitor. However, it does not mention when to avoid using this tool or suggest sibling alternatives, leaving room for clearer differentiation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the output shape (per-month entries with specific fields) and the parameter format (YYYY-MM or YYYY), going beyond the annotations. No contradictions.

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

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

Two sentences with zero waste. The first sentence states purpose and required parameter; the second details output and optional filters. 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?

Given the tool's simplicity (4 parameters, rich annotations, no output schema), the description covers purpose, parameter format, output fields, and source reference. It could be improved by explicitly stating the return type (array of entries) or handling of the lang parameter, but overall is adequate.

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 meaningful context beyond schema: it explains the date format for start_period/end_period, clarifies the example code (120010 = CPI General), and describes the computed fields (percent, percentYear) that the parameters don't directly cover.

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 fetches monthly values for a CBS price index, specifying the required numeric code from index_catalog and the returned fields (index value, percent change, year-over-year change). It distinguishes itself by referencing index_catalog as a prerequisite and mentioning 'Israeli inflation', which differentiates it from generic index 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 usage context (fetching from CBS, using code from index_catalog, optional period filtering) but does not explicitly compare with siblings like get_series_data or state when to avoid this tool. The guidance is implied but lacks direct alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds useful behavioral context: returns metadata (subject path, unit, prices, last update) and observations array with TimePeriod and Value, plus coverage of Israeli statistics. No contradictions.

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

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

Two sentences that are front-loaded with main purpose and return structure, followed by context and optional filters. Every word earns its place with no redundancy.

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

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

Despite no output schema, the description thoroughly explains return value (metadata + array of observations with fields). It covers all 4 parameters, the source domain (Israeli statistics), and optional filtering. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema: explains series_id as 'leaf id found via catalog_browse', provides format for periods, and clarifies lang default. This enriches 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 'Fetch the actual time-series observations for a CBS series by its numeric series id', which is specific and distinguishes from sibling like catalog_browse (used to find the leaf id).

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

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

The description specifies that the series id is obtained via catalog_browse, implying a prerequisite usage pattern. It also mentions optional start_period/end_period filters, but does not explicitly state when not to use or alternatives beyond catalog_browse.

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

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

The description adds value beyond the annotations by detailing the output structure (chapters, codes, numeric codeId) and linking to get_index_data. It discloses that the tool returns a tree, which is not captured in annotations.

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

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

The description is three sentences, front-loaded with the main purpose, and each sentence adds necessary information without redundancy. It is concise 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 tool with one optional parameter and no output schema, the description provides sufficient context about the return value (catalog tree with chapters and codes) and practical use (finding codeId for get_index_data). No gaps are evident.

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 already covers the single parameter (lang) with full description and enum. The tool description does not add parameter-specific semantics, but the schema is sufficient, meeting the baseline score.

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 lists the official CBS price-index catalog tree, including chapters and codes, and explicitly connects to the sibling tool get_index_data by explaining the codes' usage. It is specific about what is listed and the resource.

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

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

The description provides clear context on when to use the tool (to find the index code) and gives an example, but does not explicitly mention when not to use it or compare to alternatives beyond get_index_data.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, establishing the tool as safe. The description adds beyond this by detailing the return fields and default behavior (only active subscriptions), which is valuable context without contradicting annotations.

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

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

The description is concise, consisting of three sentences. It front-loads the action and return fields, uses imperative voice, and contains no extraneous information. Every sentence adds value.

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

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

For a simple list tool with one optional parameter and no output schema, the description adequately covers the return structure, scope (caller's subscriptions), and usage. It does not mention pagination or limits, but for this tool, the description is sufficiently complete given the annotations and simple nature.

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

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

The input schema has 100% coverage for the single boolean parameter include_inactive. The description does not add new meaning beyond the schema, as it only implies the default by saying 'active subscriptions'. Baseline of 3 is appropriate since schema covers the parameter.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count), and provides use cases (review before adding or find id to cancel). This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly states when to use the tool: to review subscriptions before adding more or to get an id to cancel. While it does not explicitly list when not to use it or mention alternatives, the context is clear and sufficient for an agent to decide.

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

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

The description goes far beyond the annotations (all false) by disclosing rate limits (5 per identifier per day), the claim_token return flow for anonymous reporters, how to later check status via claim_token, and that feedback is read daily and affects roadmap. This adds rich behavioral context not present in 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 front-loaded with purpose, then usage rules, then exclusions, then operational details. Every sentence earns its place—even the roadmap and quota notes are actionable context. Despite length, it is tightly structured with no redundancy.

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

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

Given the tool's modest complexity (4 optional params, no output schema), the description covers all essential aspects: what counts as feedback, scope restrictions, the claim_token read-back mechanism, rate limits, and cost. It leaves no significant ambiguity about invocation or expected outcomes.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the claim_token workflow ('Filing without an account returns a claim_token; pass it back later as pipeworx_feedback(...)') and by instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts. This enriches parameter meaning beyond schema descriptions.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates feedback types (bug, feature/data_gap, praise) and distinguishes this tool from siblings by being the sole feedback channel for Pipeworx 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?

It provides explicit when-to-use conditions ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well') and an explicit when-not-to-use exclusion (other MCP servers' tools), even naming where to file those instead. This is model 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining the data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). No contradictions.

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

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

The description is front-loaded with the core behavior and then expands on use cases and technical details. While slightly verbose, every sentence contributes meaningful information. Could be tightened slightly, but overall 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?

Given the tool's simplicity (one optional parameter, no output schema, rich annotations), the description provides sufficient context. It explains the return value, use cases, data source, privacy, and caching. No gaps remain for an agent to invoke the tool correctly.

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

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

The sole parameter 'window' is fully described in the schema with an enum. The description adds semantic value by explaining the effect of different window lengths ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which goes beyond the schema's enum listing.

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 specifies exactly what the tool returns (top tools, top packs, total call volume) and distinguishes it from siblings by focusing on aggregate usage patterns from other AI agents. The verb 'returns' and resource 'Pipeworx trending data' are clear.

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

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

The description lists three specific use cases (discovering hot data sources, confirming canonical choice, seeing alignment). While it does not explicitly state when not to use, it provides clear context for appropriate usage. It could mention alternatives among siblings, but the listed use cases suffice.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description goes beyond by detailing search mechanics, semantic anchor (Jaccard similarity), partition filter (placeholder elimination), and fill check logic. No contradictions.

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

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

The description is dense but necessary for the tool's complexity. It is front-loaded with purpose. Some minor repetition (e.g., 'partition_check' explained twice), 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?

No output schema, but the description fully explains the response shape (opportunities[], partition_check in event mode, fill check) and references sibling tool for custom sizing. Covers all behavioral aspects needed for correct invocation.

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

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

Schema coverage is 100% with descriptions, but the tool description adds rich context: explains what 'event' slug looks like, what 'topic' seed question entails, and how they affect scanning behavior. This vastly improves understanding beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific use cases. The verb 'find arbitrage opportunities' is specific and differentiates from siblings like polymarket_edges.

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

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

Explicitly describes when to use each mode: no args for trending scan, 'event' for a specific market, 'topic' for cross-event scanning. Also warns when not to trade (realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing. No ambiguity.

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

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

The description reveals extensive behavioral details: model families, response segments, caching at KV level for 1 hour, carrying edge_pp_net, Kelly fractions, and diagnostics. Annotations already indicate readOnly and idempotent, and the description adds more context without contradiction.

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

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

The description is verbose and packed with details. It is front-loaded with purpose but includes many technical specifics (e.g., model parameters, diagnostic details) that could be streamlined. While comprehensive, it sacrifices conciseness.

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

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

Given no output schema, the description adequately explains the response structure, including by_segment, diagnostics, and a Fed note. It covers all important aspects: edge calculation, knobs, caching, and why segments might be empty. The agent is well-informed.

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

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

Schema coverage is 100%, so parameters are individually described. The description adds value by explaining how knobs like min_liquidity and max_spread_pp serve as tradeable-edge filters and clarifying special cases (e.g., min_partition_leg_kelly for partition arbs). This enriches understanding beyond schema.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It differentiates from siblings by focusing on edge detection and not requiring paging through hundreds of markets.

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 it is 'built for what should I bet on today' and mentions agents discover opportunities without paging. It provides tradeable-edge knobs for filtering but does not explicitly contrast with alternative tools, leaving some ambiguity about when to use it versus siblings.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds significant behavioral context: history bounded by 60-day TTL, snapshots written on cache-miss, decay computed from daily closes (not intraday), and specific details about the response fields like first_seen, trend, and decay_pp_per_day. 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 information-dense but well-structured: purpose, arguments, response fields, and limits. It front-loads the key question. Minor redundancy (e.g., repeating default values), but every sentence earns its place.

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

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

Given no output schema, the description fully defines the response with tracked, expired, and snapshot_dates arrays, including fields like first_seen, trend, decay_pp_per_day, and lifespan_days. It covers parameter constraints and data source limits (TTL, snapshot timing). 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 descriptions for both parameters. The description provides context by stating defaults (days=14, window='1wk') and clamps (max 30 days), which mostly mirrors the schema. It adds value by explaining the window as a 'snapshot family' and clarifying the response includes time-series data.

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

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

The description explicitly states the tool analyzes edge persistence and decay from polymarket_edges snapshots. It answers a specific question about differentiating fresh vs. old wide edges, and the response structure clearly defines its resource (opportunities). It distinguishes itself from the sibling `polymarket_edges` by focusing on time-series trends and decay.

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 clear context for when to use: to check how long an edge has existed and if it's shrinking. It includes a comparison between a fresh and a three-week-old edge. However, it does not explicitly state when not to use it or mention alternative tools (e.g., `polymarket_edges` for raw snapshot data).

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: walks order book ladder, returns specific fields like vwap_fill_price, slippage_pp, verdicts, and warns about forced directional risk and partial fill dangers. 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 a dense paragraph with much information. While every sentence adds value, it lacks bullet points or clear structural separation for the two modes, making it harder to parse quickly.

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 comprehensive. It lists all return fields, explains verdicts, details per-leg fill detail, thin_legs, max_clean_notional, and forced directional risk. No gaps 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?

Though schema coverage is 100%, the description adds crucial context: explains market vs event for modes, side defaults and auto-detection for baskets, size_usd interpretation (max spend vs target proceeds vs settlement notional). This goes beyond the schema.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by focusing on 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?

Explicitly says when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains why (theoretical overround not capturable, partial baskets convert arb to directional position).

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, and idempotentHint, so the description has less safety burden. Yet it goes far beyond annotations by disclosing compatibility_warning codes, non-equivalent bet shapes, temporal alignment uncertainties, fee treatment, skipped-comparison counters, and the standing pairing_unverified caveat. There is 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 and dense, but clearly labeled and organized into modes, response shape, safety fields, and caveats. Each sentence carries meaningful guidance; the only cost is length, so it falls just short of a 5.

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

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

There is no output schema, so the description carries the full burden of explaining return values and edge cases. It documents leg-by-leg prices, top_spreads_pp, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, and fees_note, making the tool fully usable without additional schema documentation.

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 baseline is 3. The description adds real semantic value by explaining that topic auto-fetches matching events, explicit ticker/slug overrides the topic-mapped side, and both modes produce the same matching logic and safety disclosures.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' The two-mode explanation further distinguishes the tool's exact operation from within-venue tools like polymarket_arbitrage or polymarket_edges, even without naming them explicitly.

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 clearly explains two invocation modes — the topic shortcuts and the explicit ticker/slug pairing — and states that both run the identical matcher with identical disclosures. It also warns that pre-mapped topics are not necessarily tradeable. It does not explicitly compare against sibling tools, but the mode guidance is strong enough for an agent to decide when to call it.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping to identifier and behavior when key is omitted (list all keys), providing additional transparency.

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

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

Three sentences with no wasted words. Front-loaded with main action, then usage context, then scoping and pairing. Every sentence serves a purpose.

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

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

Covers usage, scoping, and pairing well. However, does not describe the return format (e.g., value or list structure) or error handling, which would be helpful 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% with a clear description of the key parameter. Description adds that omitting key lists all keys, and provides examples of typical key values, enhancing meaning.

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

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

The description clearly states the tool retrieves a value by key or lists all keys, with specific examples like user's target ticker or research notes. It distinguishes from sibling tools remember and forget.

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

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

Explicitly states when to use: to look up previously stored context without re-deriving. Mentions scoping and pairing with remember/forget for save/delete, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by explaining the effect of mark_read on future calls, the return fields, and that polls are acceptable, which aligns with the annotations.

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

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

The description is a single paragraph with four sentences, front-loading the purpose and providing essential details without unnecessary words. Every sentence contributes useful information.

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

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

No output schema, but description names returned fields. Parameters are fully explained. The tool is simple and read-only, so only minor omissions (e.g., no mention of authentication) exist, but annotations cover safety. Context is sufficient 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%, baseline 3. The description enriches parameter meaning with examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains behavioral flags like mark_read and unread_only, 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 states the tool retrieves fired events from a subscription feed, specifying the returned fields (source, citation_uri, raw payload). It distinguishes itself from sibling tools by focusing on alerts from the feed, with no overlap with other tools like subscribe or 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 context that polling works fine and mentions an alternative direct URL for scripts and dashboards, implying when to use each. It does not explicitly state when not to use the tool or list exclusions, but the context is clear.

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

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

The description explains the tool's behavior in detail: fans out to multiple sources, fallback logic (GDELT→GNews), and known limitations (USPTO soft-fail). Annotations already indicate readOnly, idempotent, and non-destructive, which align.

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

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

The description is concise but dense; it efficiently conveys all necessary information. Could be slightly more structured (e.g., bullet points) but no extraneous content.

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

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

Given the tool's complexity (multiple data sources, fallback, output format), the description covers all key aspects. It mentions limitations and provides a clear alternative tool. No output schema, but the description explains the output structure sufficiently.

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

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

Schema coverage is 100%, and the description adds further meaning: explains 'since' with examples (ISO date and relative shorthand), 'value' as ticker or CIK, and 'type' constraint. Goes beyond schema.

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

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

The description clearly states the tool's purpose as a change feed for a company over a time window, with specific example queries. It distinguishes from the sibling tool 'entity_profile' by advising when to use each.

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

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

Explicitly provides usage context: when to use this tool (changes over time) and when to use entity_profile (static profile). Includes examples for the 'since' parameter and explains the response format.

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 context beyond annotations: data is scoped by identifier, authenticated users get persistent memory, anonymous 24h retention. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Single paragraph with clear flow: purpose, when to use, how it works, pairing. Every sentence adds value; no redundancy.

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

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

For a simple key-value write tool, the description covers purpose, usage, and behavioral traits. Missing return value info (e.g., confirmation), but negligible given simplicity.

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 intrinsic descriptions. The description adds meaningful context with naming conventions (e.g., 'subject_property') and usage patterns, slightly exceeding the baseline of 3.

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

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

The description clearly states 'Save data the agent will need to reuse later' with concrete examples (ticker, address, preference). It distinguishes from sibling tools 'recall' and 'forget' by naming them explicitly.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. It pairs with recall/forget, and clarifies persistence differences between authenticated and anonymous sessions.

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

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

The description goes far beyond the annotations by disclosing cascading internal lookups, graceful degradation when LEI/FIGI sources are unavailable, explicit 'unresolved' reporting, source-labeling of identifiers, and the candidate-returning behavior for ambiguous names. These are genuinely useful behavioral traits that the agent cannot infer from readOnlyHint/openWorldHint/idempotentHint alone.

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 nearly every sentence adds operational value. It is front-loaded with usage examples then proceeds through supported types, edge-case behavior, and failure modes. A slight organizational simplification would make it more scannable, but the verbosity is justified given the tool's complexity.

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

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

For a tool with no output schema and two parameters, the description covers the full invocation contract: input formats per type, edge cases like ambiguous bonds, unresolved identifiers, source attribution, degradation behavior, and the fact that it replaces multiple manual lookups. An agent has enough information to call it correctly and interpret its results.

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

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

Although schema description coverage is 100%, the description adds substantial parameter-level meaning: it clarifies that `value` must be the entity name only, provides examples for both company and drug types, and warns against including trailing security-class words for bond issuers. This is precisely the kind of guidance that prevents invocation errors, so it earns more than the baseline 3.

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

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

The description uses a specific verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), and immediately distinguishes the tool's role as the provider of IDs that other tools require. It enumerates supported entity types and what identifiers are returned for each, making its purpose unmistakable and differentiating it from sibling tools like entity_profile or compare_entities.

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 clear usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also gives example phrasings and explains when the tool intentionally returns candidates rather than asserting a single answer. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Describes internal behavior (probes each entity with ai_visibility_check, ranks by score) and output fields (score, confidence, signal density). Annotations already indicate read-only, idempotent, open-world; description adds process detail.

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

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

Two sentences, no wasted words. Purpose is front-loaded and immediately understandable.

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

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

Despite no output schema, description specifies return format. All parameters are covered, and annotations provide behavioral guarantees. No gaps for an agent to misuse 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%, but description adds value: notes first entity is 'subject' for narrative, context disambiguates common names. This clarifies parameter roles beyond 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 it compares AI visibility across multiple entities, ranks them, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic).

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 a use case (competitive AI-marketing audits) and example question. Implicitly suggests ai_visibility_check for single entities, but does not explicitly state when not to use this tool.

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

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

Provides behavioral details beyond annotations, such as graceful partial degradation, bundlephobia first measurement latency, and the `sources_failed` key. No contradiction with readOnlyHint, openWorldHint, etc.

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

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

Single dense paragraph that front-loads the main purpose and breaks down return data. Could benefit from structural elements like bullet points, but still efficient with no wasted words.

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

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

Fully describes what the tool returns (summary block, per-advisory detail, links, alternative versions), ecosystem limitation, and partial failure behavior. No output schema needed as description covers it adequately.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new meaning beyond the schema descriptions for 'package' and 'version', though it reinforces the default version behavior.

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

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

Clearly states the tool performs a composite check for npm packages, covering licenses, advisories, and bundle size. Distinguishes from siblings by specifying NPM ecosystem only and directing other ecosystems to an alternative.

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 ('is X safe / popular / small', 'what does adding lodash cost me') and when not to use (other ecosystems). Also mentions partial failures and latency for first measurement.

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, idempotentHint, and destructiveHint. Description adds details about embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K) with truncation flag, and return format (offsets and 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?

Description is appropriately sized and front-loaded with purpose. Every sentence adds value; could be slightly tighter but is 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?

No output schema, but description explains return values (passages with offsets and scores) and mentions truncation flag. Covers key aspects like limits and pairing with sibling tool.

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

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

Schema coverage is 100%, and description adds meaningful context: for 'text' mentions max length, for 'query' gives examples, for 'limit' specifies range and default. This significantly aids agent 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 'Semantic search INSIDE a fetched record' with specific verb and resource. It differentiates from siblings by mentioning pairing with ask_pipeworx_grounded and emphasizing the use case for large records.

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 the record is too big to cram into the prompt' and how it saves context. Mentions pairing with ask_pipeworx_grounded. No explicit exclusion of alternatives, 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?

Discloses behavioral traits beyond annotations: OAuth requirement, phone verification, SMS rate limit (10/day), webhook auto-disable after 10 failures, and that the feed is always on. No contradiction with annotations.

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

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

Well-structured with clear sections, but somewhat lengthy; could be slightly more concise without losing essential details.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description is comprehensive: covers prerequisites, return value, behavior, and delivery constraints, 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?

Input schema has 100% coverage, but the description adds rich context for each parameter, including type-specific examples, delivery channel details, and webhook signing secret handling, significantly enhancing 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 uses a specific verb 'create' and identifies the resource as a 'proactive monitoring subscription to a live-data event stream', clearly distinguishing it 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?

Provides explicit context for when to use (requires Pipeworx OAuth account) and details delivery channels with constraints, though it does not explicitly state 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, openWorldHint, idempotentHint, destructiveHint. The description adds useful behavioral context: returns category-bucketed example questions drawn from a live catalog, and explains how the topic parameter works. No contradictions.

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

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

The description is relatively long but well-organized, with front-loaded examples. Every sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description adequately explains the return format (category-bucketed example questions). For a simple one-parameter tool with clear purpose, it is complete and informative.

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 describes the parameter well. The description adds value by explaining when to omit topic for full spread and lists valid focus areas, beyond what the schema provides.

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

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

The description clearly states the tool returns example questions categorized by topic, and positions it as the onboarding entry point. It distinguishes from siblings by explicitly mentioning meta-tools like ask_pipeworx and when to use them.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides context for when to call it. It also mentions alternatives and meta-tools.

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

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

Annotations show readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds: 'Ownership is enforced', 'The row is deactivated (not deleted)', and 'historical events stay available via recent_alerts.' This provides useful behavioral context beyond 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?

Two sentences, zero waste. The first sentence states the action and key constraint, the second clarifies the behavioral effect. Every sentence serves a purpose.

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

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

The tool has a single parameter, no output schema, and annotations are present. The description covers purpose, constraints, and result behavior. It lacks details on error cases (e.g., invalid id) but is otherwise complete for a simple mutation 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 the 'id' parameter described as 'Subscription id (uuid) returned by subscribe.' The description mentions 'by id' but adds no additional meaning beyond what the schema already provides. 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.' The verb 'cancel' and resource 'subscription' are specific. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by indicating this is the reversal action. Ownership enforcement is mentioned, adding clarity.

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

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

The description provides a clear constraint: 'Ownership is enforced — you can only cancel your own subscriptions.' This implies when not to use it (to cancel others'). However, it does not explicitly mention alternatives or situations where this tool is inappropriate, but the context is strong enough for an agent to infer.

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

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

Annotations already mark the tool read-only and idempotent, but the description adds critical behavioral details: the full verdict vocabulary, the distinction between 'could_not_verify' (the check didn't happen and must not be used as evidence) and 'unsupported' (no source covers it), and the two execution pipelines with citations. This goes far beyond the annotations.

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

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

The description is front-loaded with trigger phrases and then packs routing logic, return values, caveats, and efficiency claims into a dense but efficient block. Every sentence earns its place; there is no filler or repetition.

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

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

Since there is no output schema, the description thoroughly covers the return format, the meaning of every verdict, error handling, and the exact routing logic. It also conveys caller responsibilities (e.g., never presenting 'could_not_verify' as evidence), making the tool safe and correctly invocable without additional lookups.

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

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

Schema coverage is 100%, but the description enriches both parameters: it explains how tolerance_pct overrides the implied tolerance, recommends 1–2 for hallucination detection, and gives concrete examples of well-formed claim values. This adds actionable semantics beyond the schema.

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

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

The description opens with explicit trigger phrases and states the specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself from sibling tools by defining its scope (checking whether something someone said is factually correct) and even notes it replaces 4–6 sequential calls.

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

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

It says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear usage context. It also delineates the two routing paths (company-financial vs. other claims) and explains when it supersedes multiple calls, but does not explicitly name alternative tools or give when-not-to-use exclusions.

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