Data Kingcounty

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

The description adds behavioral details beyond annotations: default model is free, Anthropic probing requires BYO key, and returns per-model scores. Annotations already declare safe read-only behavior, so description complements 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 three sentences with clear structure: first defines action, second covers models and keys, third lists output and use cases. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description outlines the return format (per-model score, confidence, signals, raw_response + combined view). All parameters are explained. The tool's purpose and behavior are fully understandable.

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

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

Schema coverage is 100% but description adds meaningful context for each parameter: 'entity' is 'The thing to ask about', 'models' listing supported models, '_apiKey' explains requirement, 'context' aids disambiguation. This significantly aids an agent in filling parameters correctly.

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 probes LLMs for knowledge about a brand or topic and scores visibility. It uses specific verbs ('Probe', 'score') and resource ('LLMs for what they know'). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on brand visibility scoring.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default model and API key usage. It does not explicitly state when not to use, but the context is clear enough for an AI agent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavior beyond that: it reveals the tool orchestrates routing across 5,596 tools and 1,465 verified sources, fills arguments automatically, and returns stable citation URIs. This explains what actually happens on the other end of the call without repeating or contradicting 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 the most critical routing rule in caps ('PREFER OVER WEB SEARCH'), followed by scope, mechanics, trigger phrases, examples, and alternative routing. It is a long description with overlapping lists of domains and triggers, so a strictly leaner write would earn a 5. A still earns a 4 because every sentence has a distinct orienting function and the layout is scannable.

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 single-required-parameter, no-output-schema tool, the description covers the actionable behavior well: the question types supported, the delegation mechanics, the citation format, and the 'start here' default status. It gives the identification of alternative siblings for edge cases. Gaps are minor (e.g., no guidance on what happens if no source matches or how errors of response are returned), and the annotations carry the safety and open-world semantics.

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

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

The input schema has 100% description coverage and fully documents every parameter as an alias for the natural-language 'question'. With this baseline, the description adds value by example: it enumerates trigger phrases and sample queries ('current US unemployment rate', 'adverse events for ozempic', 'clinical trials for GLP-1'), which effectively defines what the single text parameter should contain. That guidance goes beyond the schema's generic 'your question in natural 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 states a specific verb+resource: "Routes the question to the right one of 5,596 tools across 1,465 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs." The scope is detailed with concrete domains (SEC filings, FDA drug data, FRED/BLS, patents, weather). It also distinguishes itself from plain web search and from the grounded/beta sibling tools, so an agent can tell them apart without opening their 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?

Usage guidance is explicit and prescriptive: "PREFACE over web search" and "Use it whenever the user asks 'what is', 'look up', 'find', 'get the latest', 'how much', 'current'..." It even covers the edge case where web search could also answer, saying Pipeworx should still be preferred. It names distinct alternatives ('use deep_research for broader multi-step synthesis', 'use ask_pipeworx_grounded for grounded answers with verbatim evidence'), which is exactly the when-to-use vs when-not-to-use signal an agent needs.

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 valuable context beyond the annotations: the beta tool may change live when a routing candidate is under test, it currently matches the stable router because the last candidate was retired, and it does not fall back to another tool. The annotation safety profile is consistent, and this behavioral detail is important for an agent invoking an experimental router.

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 what the tool is and how it differs, and every sentence contributes relevant operational context. It is slightly dense and contains a few repeated references to 'ask_pipeworx', but it remains concise and logically ordered.

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 annotations and schema, the description is complete for safe and correct invocation: it defines the beta relationship, current routing state, intended usage semantics, and confirms it is a fully functional router with the same response shape as ask_pipeworx. No output schema exists, but the description explicitly defers response details to the stable sibling.

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 each parameter documented as an alias for 'question'. The description adds 'same arguments' as reinforcement but no additional parameter-level meaning; since the schema already handles parameter semantics, the 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?

States a specific function: a beta universal router that behaves like ask_pipeworx and routes a natural-language question to the same set of tools with the same arguments and response shape. It clearly distinguishes itself from its stable sibling by focusing on candidate routing improvements currently 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?

Explicitly tells the agent when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that candidates are transient and that no candidate is currently active, so it currently matches ask_pipeworx; this gives practical context for deciding between the beta and stable variants.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false. On top of that, the description adds the critical behavioral contract: the success return shape {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, the explicit refusal shape with five enumerated reasons, the grounding constraint (only extracts from what the tool result contains), and the extra cost. This is substantive behavior disclosure that annotations cannot capture.

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

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

The description is dense and front-loaded with the core purpose ('Hallucination-resistant answer mode'), then covers routing, grounding, output shape, refusal reasons, and usage rules in three efficient sentences. The enumerated refusal-reason list and the illustrative high-stakes context inject the parenthetical list, though every sentence is narrowly functional—making it tight but not maximally 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?

This is a complex tool and there is no output schema, yet the description fully specifies the success return object, refusal-reason enum, grounding semantics, and usage policy plus cost impact. An agent has everything needed to decide whether to invoke it and to interpret any response it receives.

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

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

Schema description coverage is 100%, so the input schema already documents all six parameters and the question aliases (q, query, prompt, text, input). The description adds the routing context ('fills arguments') but gives no per-parameter format or value details, so the baseline of 3 is appropriate.

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

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

States a specific mode with a clear verb and scope: 'Hallucination-resistant answer mode for high-stakes reads', then specifies the mechanism ('picks the right tool from 5,596 across 1465 sources, fills arguments, fetches the data — then EXTRACTS the answer using ONLY what the tool result contains'). It clearly distinguishes this grounded mode from the sibling ask_pipeworx, so an agent can tell them apart.

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 when to use this tool ('Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not it ('prefer ask_pipeworx for casual lookups'), naming the alternative tool and the cost trade-off (one extra LLM call). This is a complete dispatch rule.

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 (readOnlyHint, etc.) by detailing resolution logic, fan-out examples, safety mechanisms (low-confidence short-circuit, closed markets, wide-spread handling), and resolution-rule risk. It provides comprehensive behavioral 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 very long and dense, covering many details with sections (classifiers, fan-outs, response shapes, etc.). While well-structured and front-loaded with purpose, it could be more concise; some details are extensive for typical agents.

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

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

Given the tool's complexity and lack of output schema, the description is exceptionally complete. It covers inputs, outputs, edge cases (low confidence, closed markets, wide spreads), resolution rules, and safety mechanisms, leaving no critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful information: it explains that 'market' can be slug, URL, or question text; 'depth' has quick/thorough options; 'include_raw' has a recommended default and scenarios to use true. This adds value beyond the schema.

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

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

The description explicitly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + comparison). This clearly differentiates it from sibling tools like polymarket_arbitrage or 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?

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It offers extensive examples and guidance on handling resolution confidence. However, it does not explicitly state when to use alternative 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?

Adds extensive behavioral context beyond annotations: explanation of data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and efficiency claim (replaces 8–15 lookups). 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 front-loaded trigger phrases and clear organization. Each sentence adds value, though slightly lengthy; could be tighter but still concise.

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

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

No output schema, but description explains return format: 'paired data + pipeworx:// citation URIs'. Also covers efficiency, sorting, and data sources. Complete for a well-annotated 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 meaning: explains what each type pulls, provides examples for values (tickers/CIKs for companies, drug names), and reinforces constraints (2–5 items).

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

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

Description clearly states verb+resource: 'side-by-side comparison of 2–5 companies or drugs'. Distinguishes from sequential lookups with specific trigger phrases like 'compare X and Y', 'X vs Y'.

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

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

Explicit instruction: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides clear context for usage, though no explicit when-not-to-use conditions.

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 context about the return fields (resource_id, name, description, category, update date) and the intended next action, which is valuable beyond annotations.

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

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

The description is two sentences long, front-loading the purpose and key outputs, with zero wasted words. It is appropriately 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?

For a simple search tool with full schema coverage and rich annotations, the description is complete. It could mention the default limit or pagination behavior (already in schema examples), but this is not essential.

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

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

Schema description coverage is 100%, so the schema already documents parameters well. The description does not add additional parameter-specific semantics beyond what the schema provides, placing it at baseline level.

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: searching a specific catalog by keyword, with a specific verb ('search') and resource ('King County Open Data catalog'). It distinguishes itself from siblings which focus on Pipeworx, polymarket, or other domains.

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 explains when to use it (search by keyword) and hints at the next step (pass resource_id to query/metadata), but does not explicitly state when not to use it or mention alternative tools. Usage context is clear but lacks 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?

The description goes well beyond the annotations: it details decomposition into facets, parallel execution, return packet contents (evidence/confidence/source/fetched_at/stable citation), the 'gaps[]' behavior with a no-invention promise, the contradictions[] scan at standard/thorough depths, semantics of non-head-truncated excerpting, and expected latency including that thorough can take ~90s. These are non-obvious implementation behaviors with significant call impact.

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 x description (somewhat long but) earns the space: it covers auth, alternatives, what it is not, what it returns, and timing caveats. It is front-loaded with the most critical gating information (account requirement and the 'not signed in' fallback). It is slightly repetitive about the structured-vs-open-web point and could be tightened, but no sentence is pure filler.

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

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

The tool is relatively complex (2 params, no output schema, sophisticated multi-tool parallel behavior), and the description covers the necessary operational context: authentication prerequisites, parameter semantics, output shape, source provenance, contradiction/gap behavior, citation fetchability, and latency. An agent given this description can choose, call, and interpret this tool correctly without needing additional 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 description coverage is 100%, so the schema itself already fully documents both parameters, including what 'depth' levels mean and how 'question' is interpreted. The tool description reinforces that broad/multi-part questions are fine and adds example phrasings, but it does not materially extend the schema's parameter guidance. 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 states a specific verb, resource, and scope: it 'researches' Pipeworx's 1,465 structured data sources in one call, explicitly for broad/multi-part questions. It also distinguishes itself from siblings by saying 'this is NOT open-web search' and naming ask_pipeworx for single lookups. This leaves no ambiguity about what the tool does or how it differs from its 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?

It gives explicit sign-on requirements and directs users to ask_pipeworx if not signed in. It states when to use it ('best for broad/multi-part questions over structured data') and when not to ('for a single lookup use ask_pipeworx instead'). These are specific, actionable routing conditions.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, which is consistent with a discovery tool. The description adds valuable context beyond annotations: it explains the tool returns top-N tools with schemas and curated examples, ready to call directly without a second lookup. It does not contradict annotations.

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

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

The description is concise yet thorough, front-loaded with the primary action. Each sentence serves a purpose: first sentence states purpose, second lists domains, third explains return format, fourth gives when-to-call guidance. No redundant or filler 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 no output schema, the description compensates well by stating what is returned (names, descriptions, full input schemas with examples). It covers the necessary context for a discovery tool with 6 parameters (mostly aliases) and 100% schema coverage. Slightly more detail on return format could elevate, but it is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by listing all aliases for the query parameter (task, q, description, search), specifying default and max for limit, and providing example usage ('look up FDA drug approvals', 'analyze housing market trends'). This enriches 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 uses a specific verb-resource combination: 'Find tools by describing the data or task.' It lists numerous domains (SEC filings, financials, etc.) and explains that the tool returns top-N relevant tools with full schemas, ready to call. It distinguishes itself from sibling tools by explicitly stating 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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 clearly states when to use: 'Call this FIRST when you have many tools available and want to see the option set.' It implies not to use when needing a single answer, as other tools are for that. While it doesn't explicitly list alternatives, the context is clear and the 'FIRST' guidance effectively sets usage boundaries.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds significant behavioral context: it fans out across multiple sources in a parallel call, soft-fails for patents (USPTO sunset), and provides fallback via GDELT→GNews. 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 fairly long but efficiently structured with a clear intro (example queries), a usage guideline, and a detailed list of returned data. Every sentence adds value; it could be slightly tighter but remains well-organized and front-loaded.

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

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

While there is no output schema, the description thoroughly lists the returned fields (cik, recent_filings with URIs, fundamentals with specific metrics, patents status, news fallback, LEI). It covers most of the complexity, though minor gaps exist (e.g., news count limit). Overall, highly complete for a cross-source profile 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 both parameters described. The description adds further meaning: explains that type is enum with only 'company' currently, and value examples (ticker or CIK). It also clarifies that names are not supported, 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 provides a full cross-source profile of a US public company, with examples like 'Tell me about X' and 'company profile for Microsoft'. It lists specific data sources (SEC, XBRL, USPTO, news, GLEIF) and output fields (cik, company_name, recent_filings, fundamentals, etc.), distinguishing it from siblings like resolve_entity.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides when-not-to-use: 'names not supported (use resolve_entity first if you only have a name).' This gives clear contextual guidance and alternative tool referrals.

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 destructive hint and idempotent hint. Description adds context about clearing sensitive data and confirms deletion behavior, but doesn't contradict annotations.

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

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

Two concise sentences with no redundant information. The action verb is placed at the beginning for quick comprehension.

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

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

For a simple one-parameter tool with good annotations, the description covers all necessary context including use cases and pairing.

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

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

Schema coverage is 100% with clear description for the 'key' parameter. The description adds minimal extra meaning beyond 'Memory key to delete', so baseline 3 is appropriate.

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

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

The description clearly states the action ('Delete a previously stored memory by key') and distinguishes the tool from siblings by mentioning 'remember' and 'recall' as paired tools.

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

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

Explicitly says when to use this tool: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with related 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 indicate read-only, idempotent, non-destructive. Description adds context about fetching an external URL and producing a markdown file. Does not contradict annotations, and adds behavioral details beyond annotations.

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

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

Two paragraphs, first sentence immediately states purpose. Subsequent sentences add detail without unnecessary fluff. Well-structured and front-loaded.

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

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

With 2 parameters, no output schema, and appropriate annotations, the description explains the input, process, and output format. Could mention error handling for invalid URLs, but overall sufficient.

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

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

Schema coverage is 100% with descriptions for url and max_links. Description adds minimal extra: example URL format and default/max for max_links, but these are already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, specifying the process (fetches page, extracts title/description/key links, emits markdown). It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning.

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 use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' Does not explicitly mention when not to use, but examples are clear and relevant.

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, indicating safe reads. The description adds that it returns specific fields and that by default only active subscriptions are returned, with an optional include_inactive parameter for cancelled ones.

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

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

Two sentences: first covers purpose and return fields, second provides usage guidance. No superfluous text, front-loaded with essential 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 simple list tool with one optional parameter and no output schema, the description covers return fields, parameter semantics, and usage context. No gaps for an agent to understand 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% for the one parameter (include_inactive), so baseline applies. The description adds context that subscriptions are 'active' vs 'cancelled', but this is already inferable from the schema description.

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

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

The description clearly states 'List the caller's active subscriptions' and specifies return fields. It distinguishes from siblings like 'subscribe' and 'unsubscribe' by noting its use for reviewing existing 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?

Description explicitly says to use it to review subscriptions before adding more or to find an id to cancel, providing clear context for use. It does not mention when not to use, but the guidance is sufficiently clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds value by specifying the exact output fields (columns, types, etc.), which goes beyond the annotations. It does not mention potential errors or rate limits, but the tool is simple and read-only.

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, front-loaded sentence that efficiently conveys the tool's purpose, input, and output. No unnecessary words.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete: it specifies the data source, input, and output contents. It does not cover edge cases like invalid resource_id, but that is minor for a straightforward metadata retrieval tool.

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

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

Schema coverage is 100%, but the description adds an example resource_id ('j56h-zgnm') and explains that the tool returns schema + metadata, providing context beyond what the schema description ('Dataset id, e.g. "j56h-zgnm".') offers.

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 schema and metadata for a King County Open Data dataset by resource_id, listing specific fields (columns, types, row count, category, last-updated). It is a specific verb+resource combination and distinguishes from siblings like 'datasets' which lists datasets.

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

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

The description provides clear context for when to use the tool (to get metadata for a specific dataset). It does not explicitly state when not to use it or mention alternatives, but the context signals and sibling tools imply 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?

Despite annotations being all false, the description adds significant behavioral context: rate limiting ('Rate-limited to 5 per identifier per day'), quota accounting ('Free; doesn't count against your tool-call quota'), and the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'). These details go well beyond the structured 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?

While longer than typical, every sentence carries distinct information: purpose, triggers, exclusions, token behavior, rate limits, and roadmap impact. The structure flows logically from what → when → how, with 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?

With no output schema, the description covers return value behavior (claim_token, later status check). It addresses scope (only Pipeworx tools), rate limits, and resolution workflow. Given the tool's complexity (nested context, optional params), this is fully sufficient for an 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%, so baseline is 3. The description adds value by providing a concrete usage example for claim_token ('pipeworx_feedback({claim_token:"pwfb_…"})') and elaborating on type semantics ('bug = something broke or returned wrong data'). It doesn't heavily enhance every parameter but meaningfully supplements 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 a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates from sibling research/query tools by framing this as feedback about the Pipeworx connection itself, not data retrieval.

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

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

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

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, etc.), the description adds value by disclosing caching behavior ('Cached 5min-1h depending on window'), data source ('CF analytics-engine'), and absence of PII. This provides behavioral context 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?

Description is relatively concise but includes a list of use cases which is helpful. Slightly longer than necessary but every sentence adds value. Could be more structured with bullet points for readability.

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

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

Despite lacking output schema, the description adequately explains what the tool returns (top tools, top packs, total call volume) and provides context on caching and data source. It covers all essential aspects for a read-only, trending data tool.

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

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

Schema coverage is 100% and the description adds meaning to the 'window' parameter by explaining the trade-off between shorter and longer windows, which is not evident from the schema alone.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over a window. It uses a specific verb ('Returns') and resource ('what other AI agents are calling'), distinguishing it from siblings like 'discover_tools' which likely has a different focus.

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 use cases (1,2,3) explaining when to use the tool: discovering hot data sources, confirming canonical choice, aligning use case. Also explains window selection (shorter vs longer). However, it does not explicitly mention when NOT to use or provide direct 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 indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral context: the monotonicity and partition-check logic, semantic anchor for cross-event, partition filter for placeholders, and fill check against live CLOB depth with realizable edge constraints. This fully informs the agent of internal processes and limitations.

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

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

The description is detailed but well-organized, with each mode and concept clearly demarcated. It is slightly verbose due to technical explanations, but every sentence serves a purpose and the structure is logical, earning a high score.

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 (three modes, internal checks, fill risk), no output schema, and multiple edge cases, the description covers all necessary aspects: return structure (opportunities array, partition_check object), fill check logic, and constraints. It is fully self-contained for an 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 basic descriptions, but the description substantially enriches both parameters: explains accepted formats (slug or URL for event, seed question for topic), internal processing (Jaccard similarity, partition filter), and mode-specific behavior. This goes well beyond the schema, adding high semantic 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, and distinguishes three distinct modes (no args, event, topic) with clear resource targets (trending scan, specific event, cross-event scan). This makes the purpose highly specific and distinct from sibling tools.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also warns against trading when realizable_edge_pp ≤ 0 and references polymarket_fill_risk for custom sizing, effectively managing expectations and alternatives.

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

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

Annotations indicate read-only and idempotent behavior. The description adds substantial behavioral detail: caching at KV level (1h), how edge is computed (net of slippage, with 24h-move warning), and the internal filter logic (placeholder-slug filter, partition skipping). 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 excessively long (5 paragraphs) and includes fine-grained model details that may overwhelm an agent. While front-loaded with purpose, it lacks conciseness and could be streamlined to essential information for tool selection.

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 explains response structure (by_segment, fed_candidates, _diagnostics) and caching behavior. It covers all aspects needed for an agent to understand the tool's output and behavior, making it complete for its complexity.

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

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

Schema coverage is 100% with detailed descriptions, but the description adds value by explaining interactions, e.g., min_partition_leg_kelly vs min_kelly, and the purpose of tradeable-edge knobs. It provides context beyond the schema, justifying a score above baseline 3.

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

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

The description clearly states the tool scans Polymarket markets and returns edge opportunities, with specific verb 'scan' and resource 'Polymarket markets'. It distinguishes from siblings by detailing unique model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and response structure, making its purpose unambiguous.

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

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

The description provides explicit usage guidance, including tradeable-edge knobs (min_liquidity, max_spread_pp) and when to apply them. It notes Fed bets are excluded from ranking, giving context for when not to rely on the tool. However, it does not directly mention alternatives like polymarket_arbitrage or polymarket_edge_tracker, relying on sibling context.

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

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

The description adds extensive behavioral context beyond annotations: it uses daily snapshots, has a 60-day TTL, decay computed from daily closes (not intraday), and explains gaps due to cache-miss. This is consistent with readOnlyHint and idempotentHint.

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 densely packed and well-structured with clear sections for tracked, expired, and snapshot_dates. It is slightly verbose but every sentence adds necessary detail.

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

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

Given the complexity of the output and no output schema, the description fully explains the return fields (tracked, expired, snapshot_dates), their contents, and interpretation. It also covers limitations like TTL and non-intraday data.

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

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

Schema coverage is 100%, but the description enriches both parameters with default values, clamp ranges for days, and window family options. It also explains how the returned data relates to these parameters.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge age and shrinkage. It distinctly differs from sibling tools like polymarket_edges (current edges) by focusing on historical persistence.

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 explains when to use it: to differentiate between fresh and old edges. While it doesn't explicitly list alternatives, the context implies that for current edges one would use polymarket_edges. Still, it's clear enough for an agent.

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

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

Adds rich behavioral context beyond annotations: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, etc.), and warns about forced_directional_risk. No contradiction with readOnlyHint or idempotentHint.

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 and formatting, but somewhat verbose with redundancy. Could be tightened without losing key 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?

Provides detailed return fields for both modes and rationale for usage. Lacks error case handling, but overall comprehensive for a risk-check tool with 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%, but description adds significant meaning: explains single-market vs basket modes, default values, interpretation of size_usd, and side behavior beyond enum descriptions.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes, with specific use cases and sibling differentiation.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains why partial fills create directional risk.

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 extensive behavioral details: compatibility_warning conditions, temporal alignment, skipped cross types, and the fact that pre-mapped ≠ tradeable. No contradiction.

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

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

Description is long but necessary for the complex tool. Front-loaded with purpose and modes; details follow logically. Could be slightly more concise but acceptable for the given 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?

No output schema, but description explains response structure (leg-by-leg prices, spread array, compatibility fields, temporal alignment, skipped counters). Covers most expectations, though lack of error handling mention is a minor gap.

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

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

Schema covers 100% of parameters with descriptions. Description adds examples and mode explanation but does not provide additional semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' and distinguishes two modes (topic and explicit). It differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Provides clear context for when to use (to check spread) and includes warnings about compatibility and non-tradeability. However, it does not explicitly mention alternatives among sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds context about SoQL clauses and return format (JSON), but does not disclose additional behavioral details such as rate limits or pagination behavior. It does not contradict annotations.

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

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

The description consists of two concise sentences with the main action front-loaded. Every sentence provides essential information without redundancy or fluff.

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

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

The description covers the key aspects: type of query, dataset identifier, filtering options, and return format (JSON). It does not mention error handling or rate limits, but given the simplicity of the tool and richness of annotations/schema, it is fairly complete.

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

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

Schema description coverage is 100% with examples and descriptions for all 7 parameters. The description adds value by specifying that SoQL clauses should be written without the leading $, which is not in the schema. This compensates slightly beyond the schema baseline.

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

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

The description clearly states the tool runs a SoQL query against a King County Open Data dataset using a resource_id, with specific filtering options. It is a specific verb plus resource and distinguishes from sibling tools through its unique Socrata query functionality.

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 explains what the tool does and returns JSON, but does not provide explicit guidance on when to use it versus alternative tools like 'datasets' or 'search_within'. Usage is implied but lacks exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds scope details (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, providing helpful context beyond annotations.

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

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

Three sentences, efficient and front-loaded with the core action. No redundant phrasing, but could be slightly more compact.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and integration with siblings. Complete and self-contained.

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

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

Schema coverage is 100%, so baseline 3 is appropriate. The description reiterates the key parameter's behavior (omit to list all keys) but adds little beyond the schema's own description.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys, with concrete examples of use cases (ticker, address, 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 says when to use: 'look up context the agent stored earlier... without re-deriving it from scratch.' Mentions scoping and pairing with remember/forget, but doesn't list when not to use or alternatives beyond its counterparts.

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 safety (readOnlyHint, idempotentHint). The description adds behavioral details like the effect of mark_read on subsequent calls, the included fields (source, citation_uri, raw payload), and an alternative GET endpoint. No contradictions.

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

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

Four sentences, front-loaded with the core purpose. Each sentence adds distinct information (purpose, return fields, filtering options, mark_read effect, alternative access). No redundancy or fluff.

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

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

Given no output schema, the description covers return fields (source, citation_uri, raw event payload) and key behaviors (polling, mark_read effect, alternative URL). It is complete for a read-only feed retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context for 'type', 'since', and 'mark_read' (e.g., 'Flag the returned events read so the next call only shows newer ones'). It provides less additional value for 'limit' and 'unread_only', but overall enhances clarity.

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

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

The description states a specific action ('Pull fired events from your subscription feed') and identifies the resource (subscription feed). It distinguishes from sibling tools like list_subscriptions by focusing on retrieving fired events with payloads.

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 clearly indicates when to use the tool (pulling recent alerts with optional filters). It also suggests an alternative access method for scripts/dashboards. However, it does not explicitly exclude cases or compare to other sibling tools for similar purposes.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds key behavioral details: parallel fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail (PatentsView sunset), and output structure (changes grouped by source, total_changes count, citation URIs).

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

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

The description is a single dense paragraph that front-loads purpose and examples. It is concise but could benefit from minor structuring (e.g., bullet points for sources/parameters). Every sentence adds value.

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

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

Given the tool's complexity (multi-source, fallback, soft-fail), the description covers return values, edge cases, and provides sufficient guidance for agent invocation. No output schema exists so return format is adequately summarized.

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

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

Schema coverage is 100% with descriptions. The description adds meaning beyond schema: explains `since` format (ISO or relative with examples like '7d', '30d'), suggests '30d' for typical monitoring, clarifies `value` as ticker or CIK, and notes `type` only supports 'company'.

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

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

The description clearly states the tool provides a change feed for a company over a time window, using examples like 'What's new with X'. It lists sources (SEC, GDELT/GNews, USPTO) and explicitly distinguishes from sibling entity_profile, which focuses on static data.

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

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

The description includes explicit usage context: when to use (for recent changes), alternative tool (entity_profile for static profile), and explains fallback behavior (GDELT preferred, GNews on rate limit/5xx).

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

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

The description adds significant behavioral context beyond annotations: it explains scope (by identifier), persistence differences (authenticated vs anonymous), and retention (24 hours for anonymous). Annotations already signal idempotency and non-destructiveness, and the description aligns with these 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 three sentences: purpose, usage, and behavioral traits. It is front-loaded with the core action, includes examples, and pairs with sibling tools. No redundant or extraneous 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?

The description covers purpose, usage, behavioral traits, and pairing with recall/forget. While there is no output schema, for a write tool this is adequate. It could mention return behavior but is otherwise complete 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?

The input schema already provides descriptions for both parameters (key and value). The description mentions 'key-value pair' and gives example keys but does not add substantial new meaning beyond the schema. Schema coverage is 100%, so baseline of 3 is appropriate.

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

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

The description clearly states that the tool saves data for reuse across conversations/sessions. It uses the verb 'save' and specifies the resource as data with key-value pairs. It explicitly distinguishes from sibling tools recall and forget by mentioning them, establishing clear boundaries.

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

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

The description provides explicit guidance on when to use the tool: 'when you discover something worth carrying forward' and gives concrete examples. It also pairs with recall/forget, implying context for use. However, it does not explicitly state when not to use it or mention alternatives beyond the paired tools.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. The description adds substantial behavioral context: identifiers are labelled with their source, unresolved identifiers are explicitly stated, LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple internal endpoints. This goes far beyond the annotations and gives the agent a realistic model of the tool's behavior.

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

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

The description is long but information-dense. It is front-loaded with query examples, then systematically covers supported types, fallback behavior, and internal logic. Every sentence adds meaningful detail; no fluff. The length is justified by the tool's complexity, but it could be slightly trimmed without losing value.

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

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

Given there is no output schema, the description carries the burden of explaining what the agent will receive. It thoroughly covers both entity types, input formats, ownership data, graceful degradation, and the explicit handling of unresolved identifiers. This is a complete picture for a tool that otherwise lacks structured output 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 valuable semantic enrichment beyond the schema by providing concrete examples (AAPL, 0000320193, CH0038863350, ozempic) and clarifying edge cases like ISIN-to-LEI resolution for non-US issuers. This helps the agent understand both the input format and the intended meaning of the parameters.

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

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

The description opens with concrete query examples and a precise statement: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This clearly identifies the verb (resolve), resource (names to IDs), and scope (official identifiers), and it distinguishes the tool from siblings by positioning it as the prerequisite lookup step for other tools.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is a clear when-to-use directive. It also notes that it 'replaces 2-3 manual lookups,' implying alternatives. However, it doesn't explicitly name sibling tools or say when not to use it, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral context: it probes each entity, ranks results, and surfaces most/least recognized. It also specifies return fields (score, confidence, signal density), which is valuable beyond annotations.

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

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

Three sentences: function, process, usage example. No redundancy, front-loaded, 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?

With no output schema, the description explains the return value (ranked list with score, confidence, signal density). It covers input constraints (entities 2-8) and references the underlying tool. It could mention error scenarios, but for a batch comparison tool this is sufficiently complete.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description mentions 'entities' and 'context' but does not add new semantic details beyond reinforcing that entities are compared and context is shared. Therefore, baseline 3 is appropriate.

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

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

The description clearly states it compares AI visibility across multiple entities, uses ai_visibility_check, ranks by score, and returns a ranked list. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (non-AI focus) by emphasizing competitive AI-marketing audits.

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

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

The description provides a concrete use case: 'does Claude know about us as well as our competitors?' and implies it's for multi-entity comparisons. However, it does not explicitly state when not to use this tool or suggest alternatives such as ai_visibility_check for single-entity checks.

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 confirm readOnly, openWorld, idempotent, not destructive. Description adds core behavioral traits: composite, fans out sources, partial failures degrade gracefully, bundlephobia first-measure delay (5-30s), and sources_failed list on timeout.

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

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

Dense but efficient; no fluff. Front-loaded with core function, then usage context, ecosystem limits, and failure behavior. Every sentence adds value.

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

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

No output schema, so description fully explains return values: summary block (fields listed), per-advisory detail, links, alternative versions. Also covers partial failure behavior.

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 3. Description adds value: 'package' accepts scoped names like @types/node, 'version' defaults to latest when omitted. Provides context beyond raw schema.

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

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

The description clearly states it is a composite check for adding an npm package, aggregating data from deps.dev and bundlephobia. It distinguishes from siblings by specifying npm-only scope and listing return fields.

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

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

Explicitly tells when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also says not for other ecosystems, directing to deps.dev:version directly.

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

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

Adds significant behavioral details beyond annotations: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char cap with truncation, and offset verification. No contradiction with annotations.

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

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

Concise single paragraph, front-loaded with core action, every sentence adds value. No fluff.

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

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

Despite no output schema, description explains return value (passages with offsets and similarity scores) and embedding details. Covers truncation behavior. Adequately complete for agent 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 covers all 3 parameters (100% coverage), but description adds practical context: 'text you already pulled', natural-language query examples, and max length. Slightly above baseline.

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

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

Description uses specific verb+resource: 'semantic search INSIDE a fetched record'. Distinguishes from siblings by emphasizing searching within a single record, not whole documents. Explicitly mentions returning passages with offsets and similarity scores.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for grounding. Could be more explicit about when not to use, but provides clear context and alternative.

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

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

Annotations indicate mutation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds significant behavioral context: returns subscription id, OAuth requirement, type-specific parameters, delivery constraints (phone verification, 10/day SMS cap, webhook auto-disable), and always-on feed. 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 thorough but not overly verbose. It front-loads the core action and prerequisites, then systematically covers types and delivery. Every sentence adds value. Could be slightly more concise, but given complexity, length 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 (multiple subscription types, delivery options, constraints, no output schema), the description covers all essential aspects: prerequisites, type-specific parameters, delivery details, and failure handling (webhook auto-disable). No gaps identified.

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

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

Schema coverage is 100%, and the description enriches parameters with concrete examples and constraints. For 'type', it lists enums and adds guidance. For 'params', it provides type-specific structures. For 'delivery', it details sub-properties, verification steps, and error handling, far exceeding the schema's brief 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 uses the specific verb 'Create' and identifies the resource as 'proactive monitoring subscription to a live-data event stream'. The title 'Subscribe to Alerts' reinforces this. It clearly distinguishes from sibling tools like 'list_subscriptions' (listing) and 'unsubscribe' (removal).

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 prerequisites ('Requires a Pipeworx OAuth account; anonymous + BYO cannot persist subscriptions') and enumerates supported types and delivery channels. It does not explicitly state when not to use this tool or suggest alternative tools, but the context is sufficient for an agent to decide usage.

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

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

Annotations declare safe read-only behavior; description adds detail about returning exact tool+argument shapes and behavior with/without topic parameter.

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

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

Front-loaded with alternative phrasings; clear but slightly verbose for a simple tool.

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

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

Complete for the tool's simplicity; describes return format and usage scenarios thoroughly.

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

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

Schema coverage 100%; description adds context for topic values and explains behavior when omitted.

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 states it is the onboarding entry point, returns category-bucketed example questions, and distinguishes from siblings like discover_tools.

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

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

Explicitly says to use this when the agent doesn't know what Pipeworx can do, and discusses alternatives like meta-tools and how to pass optional topic.

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 readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds that the row is deactivated, not deleted, which goes beyond annotations. However, it does not detail return behavior or potential errors.

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

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

Two sentences with no wasted words. The action is front-loaded, and every sentence provides essential 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?

With one simple parameter, no output schema, and clear annotations, the description covers ownership, deactivation, and historical availability. It could mention the return value or success indication, but overall it's sufficient.

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

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

Schema coverage is 100% with a clear description for 'id'. The description only references 'by id' without adding new meaning, so baseline 3 applies.

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

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

The description clearly states 'Cancel a subscription by id' which is a specific verb+resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions') and explains the effect ('the row is deactivated, not deleted'), providing clear when-to-use and what-happens 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 claim readOnly/openWorld/idempotent, but the description adds substantial behavioral context: the two routing paths, the exact verdict list, the pipeworx:// citation format, and the nuanced meaning of 'unsupported' vs 'could_not_verify' with verification_error. No contradiction with annotations.

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

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

The description is long but front-loaded with trigger examples and purpose. Each subsequent section (paths, verdicts, warning, replacement value) earns its place. The use of 'IMPORTANT for callers' highlights critical caveats. 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?

Despite having no output schema, the description fully specifies the return contract: verdict enum, grounded actual value with citation, reasoning, and error semantics. It also explains edge cases ('could_not_verify' vs 'unsupported') and the composite nature. For a tool with this complexity, the description is complete.

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

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

Schema coverage is 100% (both 'claim' and 'tolerance_pct' have detailed descriptions). The description mentions tolerance math and default cap, but these are largely restatements already present in the schema. It does not add significantly new semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with natural-language trigger phrases and clearly identifies the tool as claim verification against authoritative sources. It distinguishes itself from siblings by explicitly covering both structured financial claims (SEC EDGAR/XBRL fast path) and other factual claims (grounded pipeline), and 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?

Provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between financial vs. non-financial claim handling and gives critical caller instruction regarding the 'could_not_verify' verdict (not evidence for/against), which is a clear 'when to use / how to interpret' guardrail.

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