Washington State Open Data

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that Anthropic calls require BYO key and user pays directly, and that it returns per-model score, confidence, signals, and raw_response. No contradictions.

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

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

Three sentences with zero waste. All information is front-loaded: first sentence states core function, second adds default and return format, third lists use cases. Every sentence earns its place.

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

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

The description covers all parameters, return format, and use cases. No output schema exists, but the description provides enough detail about the per-model response. It lacks information on limits or errors, but for a read-only probe it's 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 coverage is 100% with descriptions for all 4 parameters. The description adds context about the default model, the purpose of _apiKey (passed through to Anthropic), and how context helps disambiguate. This goes beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score, with specific verb+resource. It differentiates from siblings like 'scan_competitor_ai_presence' by focusing on scoring per model.

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 explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the default vs. with API key. However, it does not explicitly contrast with similar sibling tools like 'scan_competitor_ai_presence'.

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

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

Annotations already declare read-only, open-world, and idempotent. The description adds routing behavior, citation URIs, one-call speed, and verified source counts. No contradictions with annotations.

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

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

The description is long but well-structured: starts with the most important instruction, includes examples, and differentiates siblings. Every sentence adds unique value, though a slightly tighter edit could be made.

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 broad scope, many sibling tools, and absence of output schema, the description is remarkably complete. It covers purpose, usage triggers, alternatives, examples, and notes about news routing, providing everything an agent needs to select and invoke it correctly.

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

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

Schema coverage is 100% with all aliases documented, so baseline is 3. The description adds value beyond schema by providing natural-language examples, query phrase patterns ('what is', 'look up'), and intended usage, which enriches the question parameter semantics.

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

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

The description clearly states the tool routes questions to one of 5,529 tools across verified sources and returns structured answers with citation URIs. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit 'when to use vs alternatives' guidance: 'PREFER OVER WEB SEARCH', 'Use whenever...', and gives specific step-up scenarios for ask_pipeworx_grounded and deep_research. It also covers breaking-news cases, making the usage context unambiguous.

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

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

Beyond the annotations, the description discloses that candidate routing improvements are enabled live during tests, that the last candidate was retired on a specific date, and that the tool currently matches ask_pipeworx exactly. It also clarifies that it does not fallback to anything else and is a full working router, providing rich behavioral context.

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

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

The description is well-structured and front-loaded with the key fact that it is a beta version of ask_pipeworx. Each sentence adds unique information about current state, usage, and fallback behavior, though it is slightly verbose with four sentences. It avoids fluff and is easy to parse.

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

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

For a tool with a single required parameter, the description adequately explains what the tool is (beta router), how to use it (like ask_pipeworx), and its current state. It also references 'same response shape' to direct the agent to the stable tool's output, though no output schema is provided. This is sufficiently complete for the tool's complexity.

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

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

The input schema fully documents all parameters with descriptions for each alias and the main 'question' parameter, giving 100% coverage. The description's statement 'same arguments' adds no additional semantic value beyond what the schema already provides, so 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?

The description clearly identifies the tool as a 'Beta version of ask_pipeworx' and a 'universal router' with the same 5,529 tools, making its function explicit. It distinguishes itself from the stable ask_pipeworx and other siblings by highlighting its experimental nature and current equivalence to ask_pipeworx.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing', providing a direct usage scenario. It also clarifies that when no candidate is active it matches ask_pipeworx exactly, implying that for stability one should use the stable router. This is clear when-to-use guidance with alternative context.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses key behaviors: it routes across 5,529 tools, extracts only from fetched data, returns a structured evidence object, and explicitly refuses with specific refusal reasons when no answer is found. It also mentions the extra LLM call cost, adding transparency not present 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?

Despite being moderately long, every sentence and clause adds distinct value: what it does, how it routes, the return/refusal structure, and usage guidance. The use of dashes and bullet-like lists keeps it scannable. It is front-loaded with the core purpose, making it highly effective.

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

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

There is no output schema, so the description fully covers return values and failure modes with an explicit JSON example. It also explains the trade-off vs the sibling tool, the high-stakes use case, and the rejection behavior. For a tool with moderate complexity, the description is complete and self-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?

The schema already provides 100% coverage of the parameters (all aliases for 'question' with clear descriptions). The tool description adds no new parameter-level meaning beyond what the schema states, so the baseline score of 3 applies as schema handles the semantics.

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

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

The description clearly states this is a hallucination-resistant answer mode for high-stakes reads, explicitly distinguishing it from sibling ask_pipeworx by emphasizing that it extracts answers only from tool results and returns evidence. The verb 'EXTRACTS' plus the resource and purpose make the tool's function unambiguous.

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

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

The description explicitly says 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 to ('prefer ask_pipeworx for casual lookups'), also noting the extra cost. This provides clear guidance relative to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds extensive behavioral details: resolver contract, low-confidence short-circuit, closed market handling, wide-spread liquidity warnings, cancellation rule parsing, and safety mechanisms. No contradiction with annotations.

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

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

Description is comprehensive but lengthy; front-loaded with main purpose and structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Some redundancy (e.g., repeated 'low_confidence_match') could be trimmed, but the detail is justified given tool 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, so description must explain return values. It thoroughly covers all response fields (result.market, analysis, evidence, market_match_confidence, parent_event, news fields, safety mechanisms, and error/edge cases). Addresses agent needs for validation and usage.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). Description adds examples for market parameter (slug, URL, question text), explains depth options and include_raw purpose, and provides context beyond schema, such as typical response sizes.

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 researches a Polymarket bet by pulling Pipeworx data, with specific verb 'research', resource 'Polymarket bet', and action 'pull Pipeworx data'. It distinguishes from siblings by focusing on a single bet research vs. other tools like polymarket_edges or ask_pipeworx.

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

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

Explicitly provides three use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and warns agents to inspect market_match_confidence before trusting analysis, especially for medium/low matches.

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, openWorldHint, and destructiveHint. The description adds valuable behavioral details: results sorted by primary metric, returns citation URIs, and replaces multiple sequential lookups. 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 well-organized, starting with trigger phrases and followed by detailed behavior. Every sentence contributes useful information, though it could be slightly more concise 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?

With no output schema, the description explains the output format (sorted data, citation URIs) and the specific fields returned per entity type. This is sufficient for an agent to understand what to expect, though some details like pagination or limits are omitted.

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

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

Schema coverage is 100% with descriptions for both parameters. The narrative enriches these by providing concrete examples (e.g., tickers for company, drug names) and explaining what data is pulled for each enum value, adding meaning beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in a single call, using specific trigger phrases like 'compare X and Y' and 'head to head'. It distinguishes itself from sequential single-pack lookups, making the purpose unmistakable.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a strong directive on when to use this tool. It also explains the data sources for each type, helping the agent decide based on entity type.

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

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

Annotations already declare readOnly, idempotent, openWorld hints. Description adds context about return fields and linkage to query/metadata tool, enhancing understanding beyond annotations.

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

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

Two sentences, front-loaded with action and resource, every word 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?

Sufficient for an agent to understand the tool, its parameters, and how to use results (pass resource_id to query/metadata). No output schema needed given simplicity.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds overall purpose but does not augment individual parameter details beyond schema.

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

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

Clearly states verb 'Search', specific resource 'Washington State Open Data catalog', and lists return fields. Differentiates from siblings by specifying data source and result format.

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

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

Implicitly indicates when to use (searching Washington State datasets). Does not explicitly state when not to use or name alternatives among siblings, but context is clear.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, so the description's additional context is valuable: it details account requirements, paid-tier limitations, parallel decomposition, gap recovery, contradiction scanning, citation resolvability, excerpting strategy, and expected latency. This goes far beyond the annotations and sets accurate expectations for callers.

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, and every sentence contributes unique operational details. It is front-loaded with a critical prerequisite (account requirement) and quickly pivots to alternatives. It could benefit from bullet-style formatting, but the text remains coherent and scannable for such a complex tool.

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

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

Without an output schema, the description thoroughly explains the return format: a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, explicit gaps[], contradictions[], hop fields, and semantically excerpted records. It also covers timing, depth variants, and limitations, so an agent has a complete mental model of what to expect.

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 parameters are already well documented. The description adds meaningful context beyond the schema: it clarifies the paid plan requirement for depth:'thorough', default depth behavior, expected execution times, and how each depth setting affects gap recovery and contradiction scanning. This enriches the schema without redundancy.

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 and resource: grounded multi-source research across 1455 structured data sources in one call. It clearly distinguishes itself from open-web search and from ask_pipeworx, explicitly naming when each sibling is more appropriate.

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

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

The description gives explicit when-to-use guidance for broad/multi-part structured-data questions, and explicit when-not-to-use guidance: use ask_pipeworx for single lookups, breaking news, colloquial current topics, and when not signed in. It even names alternatives and explains why deep_research would return empty gaps in unsuitable cases.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that results include full schemas and examples, that tools are ready to call without second lookup. No contradictions. Some additional behavioral context beyond annotations.

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

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

Description is fairly long but dense with useful information. Front-loaded with purpose and usage. Could trim domain list slightly, but every sentence adds value.

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

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

Despite no output schema, description fully explains return format: top-N tools with names, descriptions, and full input schemas with curated examples. Explains readiness to call. Covers all necessary context for a discovery 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 descriptions for all 6 parameters. Description mentions aliases but schema already defines them. Examples are provided in schema schema. Description adds no new semantic meaning beyond what schema provides.

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

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

Description clearly states 'Find tools by describing the data or task' and lists dozens of domains. Differentiates from sibling tools by being a discovery/search tool. Returns ready-to-call results with schemas and examples.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. Tells when not appropriate (not just one answer). Clearly distinguishes from direct query 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, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: it fans out across multiple sources, notes patent source sunset (May 2025) and soft-fail behavior, and specifies fallback chains (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 well-structured and front-loaded with examples and guidance, but it is somewhat verbose. Each sentence adds value, making it effective overall.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers return fields (CIK, filings up to 5 with URIs, fundamentals, patents, news, LEI), limitations (patent soft-fail, name restriction), and fallback behavior, leaving minimal ambiguity for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates parameter info already in the schema (ticker or CIK, names not supported) without adding significant new meaning beyond what the schema provides.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company' with specific verbs like 'profile' and 'fans out across'. It provides example queries and lists output components (CIK, filings, fundamentals, etc.), effectively 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', and provides clear instructions to use ticker or zero-padded CIK, with a specific alternative ('use resolve_entity first if you only have a name').

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and pairing, but doesn't detail side effects or reversibility. With annotations present, the added value is moderate.

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 efficient sentences: first states the action, second provides usage guidance. It is front-loaded with no wasted words.

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

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

For a simple delete tool with one required parameter and no output schema, the description is fairly complete. It covers purpose, usage, and pairing with sibling tools, leaving little ambiguity.

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

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

Schema coverage is 100% and the parameter 'key' is described as 'Memory key to delete' in the schema. The description does not add further details beyond 'by key', 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 verb 'Delete' and resource 'previously stored memory'. It explicitly distinguishes itself from sibling tools 'remember' and 'recall' by pairing with them.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, implying alternatives, though it does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: it fetches the external page, extracts content, and outputs a markdown blob. It does not discuss rate limits or error handling, but this is adequate for a read-only, idempotent tool.

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

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

The description is a single paragraph with no fluff. Every sentence is informative: it states the action, the process, the output format, and practical use cases. It is well-front-loaded with the core 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?

Given the tool has only two parameters, no output schema, and comprehensive annotations, the description covers all necessary aspects: what it does, how it works, what it produces, and when to use it. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with both parameters (url, max_links) described in the schema. The description adds context like 'clickable links' and 'default 25, max 50' for max_links, but this is improvement in context rather than new semantics. 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 a production-ready llms.txt file for any URL, detailing the process (fetches page, extracts title/description/links, emits standard markdown). This is specific and distinguishes it from siblings, which include diverse tools like bet_research, query, or subscribe.

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

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

The description lists three use cases (client indexing, own project drafting, competitor auditing), providing clear context for when to use. It does not explicitly state when not to use or name alternatives, but the sibling list contains no similar tool, so exclusions are not critical.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, ensuring safe read operation. Description adds value by specifying return fields and scope (caller's own subscriptions, active by default).

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

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

Two sentences, no wasted words. Front-loaded with core purpose, followed by usage guidance.

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

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

Complete for a simple read tool with one optional parameter and no output schema. Mentions return fields, usage context, and defaults. Annotations cover safety.

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

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

Schema has 100% coverage for the single parameter. Description adds meaning by implying default behavior (only active subscriptions) which aligns with the parameter 'include_inactive'.

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

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

Clearly states verb 'list', resource 'subscriptions', and scope 'caller's active subscriptions'. Distinguishes from siblings like subscribe/unsubscribe by specifying use case: 'review what you're monitoring before adding more or to find an id to cancel'.

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

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

Provides explicit when-to-use: before adding more subscriptions or to get an id for cancellation. Clear context but no explicit when-not-to-use.

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

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

The description adds value beyond the annotations by detailing the return content (columns, types, row count, category, last-updated). The annotations already indicate a safe, idempotent read operation, and the description complements this 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 a single, well-structured sentence that immediately states the tool's purpose and details. Every part of the description earns its place, with no wasted words.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description adequately covers what the tool does and returns. It could optionally mention if the metadata is always current or any limits, but it is sufficiently complete for an agent to understand its functionality.

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 for the only parameter, and the description merely repeats the example. No additional semantics or constraints are provided beyond what the schema already offers, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('Washington State Open Data dataset's schema + metadata'). It lists the exact fields returned (columns, types, row count, category, last-updated) and provides an example resource_id, making the purpose unmistakable 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 a clear example of the required parameter and implies when to use (retrieving dataset schema/metadata). However, it does not explicitly state when not to use or mention alternative tools for similar purposes, but the specificity of 'Washington State Open Data' narrows the context sufficiently.

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 include readOnlyHint:false, destructiveHint:false but nothing about idempotency or side effects. The description adds that filing without an account returns a claim_token (workflow implication), rate-limiting to 5/day, that reports are read daily and signal affects roadmap, and that it doesn't count against quota. This goes beyond annotations to convey process and side effects.

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

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

The description is long but every sentence earns its place: purpose, usage triggers, exclusions, workflow, constraints, and effects. It uses scannable punctuation (parentheticals, bullet-like semicolons) and focuses on actionable guidance.

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

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

For a feedback tool with no output schema, the description explains the return token mechanism, expected behavior (reads digests daily, signal affects roadmap), and rate limits. It lacks a verbatim output example but the claim_token explanation is detailed enough to complete the workflow.

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. Description adds some semantics: explains the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifies what 'context' is for ('Optional structured context: which tool, pack, or vertical this relates to'). But most parameter meaning (type enum, message constraints) is already in the schema.

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

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

The description clearly states the tool's purpose: to send feedback to the Pipeworx team about broken, missing, or needed tools. It specifies the verb ('Tell the Pipeworx team') and resource (feedback about Pipeworx tools), and distinguishes from siblings like ask_pipeworx by scoping it to feedback about the connection's 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?

Provides explicit when-to-use guidance: '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).' Excludes tools from other MCP servers, frames edge cases ('Not sure? Pipeworx tool names are the ones this connection lists.'), and gives a follow-up usage pattern (claim_token).

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: caching duration (5min-1h), data source (CF analytics-engine), and privacy (no PII). This goes beyond annotations and fully informs agent about 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 well-structured with bullet points and front-loaded information. It is somewhat lengthy but every sentence adds value. Slight room for tightening, but overall excellent.

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 no required parameters and no output schema, the description covers all necessary aspects: what is returned, use cases, caching, data source, and privacy. No gaps.

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

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

Schema coverage is 100%, but the description adds meaningful semantic guidance for the parameter: '24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agents choose the right value.

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

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

The description clearly states what the tool returns: 'top tools, top packs, and total call volume over a recent window.' It uses specific verbs and resources, and the listed use cases differentiate it from sibling tools 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?

The description explicitly provides three concrete use cases for when to use this tool, but does not mention when not to use it or discuss alternatives explicitly. The guidance is clear and helpful, though could be more comprehensive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond by detailing internal logic (semantic anchor, partition filter, fill check against CLOB depth) and explicitly warns when not to trade. This provides rich behavioral context that annotations alone do not convey.

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

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

The description is lengthy but well-structured with clear sections for each mode and additional details (semantic anchor, partition filter, fill check). Every sentence adds value, and the critical information is front-loaded. There is 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?

With no output schema, the description fully describes the return structure (opportunities array, partition_check fields, fill check results) and covers edge cases (unsafe trades, placeholders). It also cross-references another tool for custom sizing. The tool is complex, but the description leaves no gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds substantial meaning: it explains how each parameter changes the analysis scope, gives concrete examples (e.g., 'fed-decision-may-2026'), and describes the output structure. This far exceeds the schema's own descriptions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three invocation modes (no args, event, topic) with specific examples, which differentiates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly tells when to use each mode: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It also explains the benefits of cross-event mode and provides examples, offering clear guidance on selection.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint = false. The description adds extensive behavioral context: caching at KV level keyed on all knobs, response structure with segments and diagnostics, and details on model families. No contradictions.

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

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

The description is very long and dense, containing extensive technical details and model breakdowns. While organized into sections, it is not concise and may overwhelm an agent. Shorter, more scannable text would improve usability.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is very complete. It explains response structure (by_segment, fed_candidates, diagnostics), caching behavior, and reasons for empty segments. No gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning beyond schema for several parameters, e.g., explaining net slippage for min_edge_pp, slippage rationale, liquidity filtering purpose, and partition leg Kelly behavior. However, some parameter descriptions are already clear in schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, built for 'what should I bet on today'. It distinguishes from siblings by focusing on edge discovery without paging through hundreds of markets.

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

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

The description explicitly frames the use case for daily betting decisions and explains tradeable-edge knobs (min_liquidity, max_spread_pp). However, it does not explicitly state when not to use the tool or provide alternatives, though the context from sibling tools implies its niche.

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, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: explains the snapshot-based data source, return structure (tracked, expired, snapshot_dates), limitations (60-day TTL, daily closes), and caveats (decay from daily closes not intraday). This far exceeds the annotation baseline.

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

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

The description is front-loaded with the core purpose and example. It includes necessary details about response format and limitations without excessive verbosity. However, it could be slightly more concise by moving some details to a separate notes section.

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 decay telemetry and the lack of an output schema, the description adequately explains the return structure (tracked, expired, snapshot_dates) and key nuances (trend, decay_pp_per_day, lifespan). It also mentions caching and snapshot gaps. It is complete for an experienced user but might benefit from brief examples.

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 parameters (days, window) are fully described in the schema. The description restates defaults and adds the response structure, which is helpful for understanding output but does not significantly enhance parameter semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It explains what the tool answers and distinguishes it from sibling tools like polymarket_edges by focusing on persistence/decay rather than raw 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 context on when to use the tool (e.g., evaluating fresh vs. old edges) but does not explicitly state when to use this tool over alternatives like polymarket_edges or polymarket_arbitrage. It gives default parameters and limits but lacks clear guidance on exclusion.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) indicate a safe, read-only check. The description adds significant behavioral context: it walks the order book ladder, returns fill details, verdict (clean|degraded|cannot_fill), and warns about forced directional risk. No contradiction—description enhances transparency beyond annotations.

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

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

The description is detailed and well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). However, it is somewhat verbose; some sentences could be condensed (e.g., listing all return fields in a single phrase). Still, every sentence adds value, and the structure aids 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?

Given the tool's complexity (two modes, no output schema, 4 parameters), the description is complete. It lists all returned fields for each mode, explains the risks (thin legs, forced directional risk, partial fills), and provides actionable thresholds (trades above ~$500). The absence of output schema means the description must carry this information, which it does thoroughly.

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

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

Schema coverage is 100% (all 4 parameters described in schema). The description adds meaning beyond schema: explains market vs event modes, side defaults and logic (auto-detection in basket mode), size_usd interpretation differences for single-market vs basket, and clamp range. It also clarifies how returned outputs map to parameters (e.g., max_fillable_usd relates to size_usd).

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes and explicitly returns key metrics like top_of_book, vwap_fill_price, slippage, and verdict. It also differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a prerequisite check.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into unhedged directional position. This provides clear when-to-use and when-not-to-use guidance, plus names 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?

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds substantial behavioral context: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and clarifies that real spreads are rarer than the macro list suggests. No contradiction.

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

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

The description is detailed but well-structured with clear sections (modes, response, safety fields). It is front-loaded with the core purpose. While length is justified by complexity, minor condensation could improve conciseness.

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

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

Given the tool's complexity (cross-venue spread, mismatches, temporal alignment), the description is highly complete. It explains response structure, interpretation of safety fields, and common caveats. No output schema exists, but the description covers the return format adequately.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning by explaining the topic parameter's shortcuts, the explicit override behavior, and the interaction between topic and explicit parameters. Examples in schema further aid understanding.

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

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

The description clearly defines the tool as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on cross-venue differences. Title and name are descriptive.

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 outlines two modes (topic and explicit), lists all 10 pre-mapped shortcuts, explains when to use each, and includes warnings about compatibility and temporal alignment. It also notes that most pre-mapped topics return warnings, setting proper expectations.

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 it as a read-only, idempotent operation. Description adds that results are returned as JSON and SoQL clauses omit the leading $, but does not disclose any behavioral traits beyond annotations (e.g., pagination, rate limits).

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

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

Single sentence packed with essential information: action (run SoQL query), target (dataset by resource_id), optional parameters (SoQL clauses plus limit/offset), and output format (JSON). No wasted words.

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

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

Adequately covers the tool's purpose and parameters given its moderate complexity. However, it does not describe the return structure beyond 'matching rows as JSON' or mention error cases, which would improve completeness.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds valuable context: SoQL clauses should not include leading $, and provides examples that illustrate parameter usage, going 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?

Clearly states it runs a Socrata SoQL query against a specific open data portal (Washington State Open Data) by resource_id. Differentiates from siblings by specifying a unique data source and query language.

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?

Indicates usage for querying datasets with SoQL clauses, but does not explicitly state when to use this tool versus alternatives (e.g., datasets or search_within). Lacks guidance on when not to use it.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds scoping to identifier and dual behavior (retrieve vs list), enhancing transparency 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?

Description is about 70 words, front-loaded with purpose, each sentence adds new information (purpose, usage, scoping, sibling pairing), 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?

No output schema, but description covers both return behaviors and scope. Minor gap: does not mention performance or size limits, but sufficient for a simple key-value recall tool.

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

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

Schema coverage is 100%, and description adds value by explaining the two modes (omit key to list all keys), going beyond the schema's brief parameter 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?

Clearly states the tool retrieves a saved value or lists all keys, distinguishing it from siblings like 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 to use for looking up previously stored context without re-deriving, and mentions pairing with remember/forget. Could be more explicit about when not to use but is adequate.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds important context: setting mark_read to true modifies state (flags events as read), affecting subsequent calls. This explains a non-obvious side effect beyond the annotations, enhancing transparency.

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

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

The description is concise with about five sentences, front-loading the main action. It efficiently covers purpose, return contents, filtering, and state modification. No superfluous text, though could be slightly more structured.

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

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

Given no output schema, the description adequately explains return fields (source, citation_uri, raw payload). All parameters are covered, and the tool's role among many siblings is clear. A minor gap: it doesn't mention pagination or the default limit, 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?

All five parameters have schema descriptions (100% coverage), so the description's contribution is marginal. It does elaborate on mark_read's effect ('so the next call only shows newer ones'), but overall adds little 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 starts with a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly stating the tool's purpose. It also distinguishes itself by mentioning an alternative access method (GET registry.pipeworx.io/alerts.json) and implies no user/workspace filtering, helping differentiate from potential 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 explains when to use the tool (pulling recent alerts, polling) and mentions an alternative for scripts and dashboards. It does not explicitly state when not to use it, but the context is clear enough. The mention of filtering options and mark_read behavior provides practical 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 indicate readOnly, idempotent, openWorld, non-destructive. The description adds significant behavioral context: it fans out to SEC EDGAR, GDELT→GNews fallback, USPTO (with soft-fail note), and describes the return structure (changes[] grouped by source, total_changes, citation URIs). No contradiction with annotations.

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

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

The description is well-structured, starting with example queries and then detailing behavior and sources. It is not overly verbose, though the list of example queries could be slightly trimmed. Still, it efficiently communicates key information in two paragraphs.

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

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

Given the tool has 3 parameters, no output schema, and annotations fully cover safety, the description provides sufficient information: it explains the multi-source fan-out, fallback behavior, return structure, and when not to use it. This covers all contexts needed for correct invocation.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by clarifying accepted formats for 'since' (ISO date or relative shorthand like '7d', '30d') and giving examples. It also recommends using '30d' or '1m' for typical monitoring, which aids correct parameter selection.

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 in the last N days/weeks/months' using specific example queries. It explicitly distinguishes itself from the sibling 'entity_profile' by noting when to use the alternative, ensuring no confusion.

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

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

The description gives explicit usage scenarios (e.g., 'What's new with X', 'latest on Y') and provides a direct exclusion: 'Use entity_profile instead when you want the static profile...' This clearly guides the agent on when to use this tool versus the sibling.

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 idempotentHint=true and destructiveHint=false. The description adds value with behavioral details: scoped by identifier, persistence (24h for anonymous, persistent for authenticated), and pairing with recall/forget.

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 with multiple purposeful sentences. It front-loads the core purpose immediately, then expands with usage guidance, storage details, and sibling references.

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 adequately covers the tool's behavior and parameters, but lacks information about return value or success confirmation. However, given the simple nature (data storage) and absence of output schema, the omission is acceptable but still a 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 coverage is 100% with descriptions for key and value. The description adds semantic guidance: naming conventions for keys ('subject_property', 'target_ticker') and value type ('any text — findings, addresses, preferences').

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 'save data the agent will need to reuse later' with concrete examples like 'a resolved ticker, a target address' and distinguishes from sibling tools 'recall' and 'forget'.

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

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

The description specifies when to use ('when you discover something worth carrying forward') and pairs with recall/forget, but does not explicitly mention when not to use or alternatives beyond siblings.

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

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

The description adds significant behavioral context beyond the annotations: it explains that the tool 'cascades through several lookup endpoints internally', that 'LEI/FIGI enrichment degrades gracefully', and that unresolved identifiers are 'stated explicitly under `unresolved`' rather than omitted. This goes well beyond the readOnlyHint and idempotentHint annotations, providing valuable insight into the tool's operation.

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

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

The description is quite long and dense, with many details packed into a single paragraph. While it is front-loaded with example queries, the structure could be improved with bullet points for the supported types. Some sentences are lengthy and could be split for clarity, but it does avoid 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?

The description provides comprehensive context for a lookup tool with no output schema. It covers supported entity types, data sources, unresolved identifier behavior, graceful degradation, and internal cascading. This is more than sufficient for the agent to understand the tool's capabilities and limitations.

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

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

The schema already covers both parameters fully, giving a baseline of 3. The description enhances this by providing concrete examples for the 'value' parameter (e.g., 'AAPL', '0000320193', 'ozempic') and clarifying the accepted input formats for each type. This extra guidance helps the agent construct valid calls.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It uses a specific verb ('resolve') and resource (names to identifiers), and distinguishes itself from siblings like entity_profile by focusing on lookup by name. The 'Use FIRST' directive reinforces its distinct role.

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

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

The description provides explicit guidance on when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also gives concrete example queries to illustrate appropriate usage. However, it does not explicitly mention alternatives or when not to use the tool, so it falls 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 non-destructive. The description adds value by explaining the sub-probing mechanism (calls ai_visibility_check per entity), the ranking process, and the output format (score, confidence, signal density). It also notes that the first entity is treated as the 'subject' for narrative, a behavioral detail not in annotations.

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

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

Two sentences plus a parenthetical example. The description is front-loaded with the main action ('Compare AI visibility across multiple entities side-by-side') and every sentence adds distinct information. No fluff, perfectly sized for a tool with 4 parameters.

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

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

Given no output schema, the description appropriately explains the return value (ranked list with score, confidence, signal density). It covers the process (probe each, rank), the subject treatment, and the use case. Minor gaps: does not mention maximum entities or error behavior, but overall sufficient for typical use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some nuance beyond the schema: it mentions that the first entity is treated as the subject and that omitting the models parameter defaults to workers-ai. However, these are minor improvements; the schema already describes parameters adequately.

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

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

The description uses specific verbs ('Compare', 'Probes', 'ranks') and clearly states the resource (AI visibility across multiple entities) and outcome (ranked list with most/least recognized). It distinguishes from sibling tool 'ai_visibility_check' by describing a multi-entity comparison that uses that tool internally, making the purpose unambiguous.

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

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

The description provides clear context ('competitive AI-marketing audits') and an example question. It implies when to use (comparative analysis) but does not explicitly state when not to use or list alternatives (e.g., for a single entity, use ai_visibility_check). Still, the context is strong enough for an AI agent to infer appropriate use.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses partial failure behavior (bundlephobia first measurement takes 5-30s, sources_failed listing), NPM-only limitation, and return structure. 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 well-structured, front-loading purpose, then usage, then technical details and behavior. 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 fully explains the return value: a summary block with key fields, per-advisory details, links, and alternative versions. It also covers partial failures and ecosystem scope, making it complete for effective use.

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

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

Schema coverage is 100% and both parameters are described in the schema. The description repeats the parameter details but adds no new semantic information beyond what is already in the input 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 that the tool performs a composite check for adding an npm package, across deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency', and the scope (NPM ecosystem) distinguishes it from sibling tools like scan_competitor_ai_presence.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes that other ecosystems fall under deps.dev:version directly, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the tool is safe and idempotent. The description adds valuable behavioral details: truncation at 200K chars with flagging, use of BGE-base-en embeddings, cosine similarity over 500-char overlapping windows. However, it does not mention authentication or rate limits, which are not critical here. The additional context earns a 4, as annotations already cover the core safety profile.

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

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

The description is well-structured: first sentence states core purpose, second provides use case and benefits, third pairs with companion tool, and final sentence gives technical specifics. Every sentence adds unique value with no redundancy. It is concise yet comprehensive, fitting within a few lines.

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

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

Given the tool's moderate complexity (3 parameters, no output schema, no enums, no nested objects), the description covers all essential aspects: what it does, when to use, technical details (embeddings, window size, truncation), and return format (passages with offsets and scores). No gaps are apparent; an agent can confidently invoke this tool based on this description.

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

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

Schema description coverage is 100% (all three parameters have descriptions). The description adds concrete values: text max size (~200K chars), limit range (1-20) and default (5), and query examples (e.g., 'supply-chain risk'). This enriches the schema beyond mere present. Baseline for high coverage is 3, and the extra context pushes it to 4.

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

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

The description clearly states the tool performs semantic search inside a fetched record. The verb 'search' and resource 'record' are specific. It distinguishes from siblings by naming ask_pipeworx_grounded as a complementary tool, emphasizing internal search versus external grounding. The scope is well-defined: top-N passages with offsets.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt.' It explains benefits (saves context, returns only relevant passages) and mentions a companion tool (ask_pipeworx_grounded) for grounding. This provides clear guidance for selection among siblings.

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

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

Adds significant context beyond annotations: requires OAuth account, type-specific filtering, delivery constraints (SMS verification, cap, webhook signing secret). However, idempotency is implied by annotation but not clarified in description; could be more explicit about whether duplicate subscriptions are allowed.

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 primary purpose, then structured logically by type and delivery. Every sentence adds value despite length; no wasted words.

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

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

Completely covers tool usage for all provided types and delivery channels. Despite no output schema, it states the return value (subscription id) and includes critical details like webhook signing secret issuance. No gaps for this complexity level.

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 greatly enriches each parameter with examples, required fields, and constraints (e.g., clinical_trial requires sponsor or condition). Adds meaning beyond schema enumeration.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. Distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly states when to use (proactive monitoring), prerequisites (Pipeworx OAuth account), and provides delivery channel alternatives (feed, email, sms, webhook) with references to sibling tools like recent_alerts. Covers both usage and exclusion.

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 agent knows it's safe. The description adds value by explaining that it returns example questions with tool+argument shapes, and that calling with no arguments gives a full spread. No contradictions or hidden behaviors omitted.

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 alternate phrasings, which is helpful. It lists categories inline, which adds length but is informative. It could be slightly more concise, but overall it is well-structured and every sentence adds value.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains when to use, what it returns (category-bucketed examples with exact tool calls), and the optional topic filter. No gaps are evident given the tool's straightforward purpose.

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

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

Schema coverage is 100% with the only parameter 'topic' described in the schema. The description adds examples ('finance', 'pharma') and notes that omitting gives full spread. This adds marginal value beyond the schema, justifying 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 is an onboarding entry point that returns category-bucketed example questions. It uses specific verbs ('suggest questions') and distinguishes itself by advising to use it first when unsure of capabilities. The sibling list includes other tools like 'discover_tools', but this description uniquely positions it for initial exploration.

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

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

The description explicitly tells when to use ('FIRST when you do not yet know what Pipeworx can do for you') and provides example user intents. It implies alternatives (meta-tools) but doesn't explicitly exclude other scenarios. Clear context is provided, but could be stronger on when not to use.

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

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

Discloses that the row is deactivated, not deleted, and historical events remain available. This extends beyond annotations ('destructiveHint': false) with valuable behavioral detail.

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

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

Two concise sentences with no waste. Front-loaded with the action ('Cancel a subscription by id') followed by key constraints and side effects.

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

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

For a simple tool with one parameter and no output schema, the description covers all necessary context: action, ownership, idempotent effect, and impact on historical data.

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

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

Schema covers 100% of the single parameter with a description. The tool description adds minimal extra value by clarifying 'returned by subscribe', which is implicit in schema.

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

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

Description clearly states 'Cancel a subscription by id' with specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by mentioning deactivation and historical availability.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use. No explicit mention of alternatives, but the constraint is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial context beyond these: dual-path routing (SEC EDGAR/XBRL vs grounded pipeline), specific verdict values, and the critical distinction between 'could_not_verify' (did not happen, has error details) and 'unsupported' (no source). This is valuable behavioral guidance that annotations do not provide.

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

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

The description is long but information-dense, with every sentence earning its place. The structured flow from usage cues to return behavior to edge-case caveats is logical. The 'IMPORTANT for callers' section is a clear signal. Slightly front-loaded with examples could be considered verbose, but given the tool's complexity, it's appropriately sized.

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

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

The description is complete for an agent to select and invoke the tool correctly. It covers when to use, what it returns (verdict, actual value, citation, reasoning), edge-case semantics (could_not_verify vs unsupported), and performance benefits. There is no output schema, so the description effectively fills that 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 both parameters fully (100%), so baseline is 3. The description adds extra semantics for tolerance_pct, advising 'set 1–2 for hallucination detection' and noting the default cap of 5, which goes beyond the schema. The claim parameter is well illustrated with examples in the schema and the 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 verifies natural-language factual claims against authoritative sources, with specific verb ('verify') and resource ('claim'). It distinguishes itself from siblings by focusing on fact-checking with a verdict output, and mentions specific paths for financial vs other claims.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing for financial vs other claims. It doesn't name alternative tools for exclusions, but the context is clear and the 'Replaces 4–6 sequential calls' note implies an efficiency benefit over alternative workflows.

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