Data Santaclara

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

Annotations already indicate safe, idempotent, read-only behavior. The description adds value by disclosing the return structure (per-model scores, confidence, signals, raw_response + combined view) and the cost implication of using Anthropic (BYO key). 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 extremely concise (4 sentences) yet packs all essential information: purpose, scoring range, default model, optional Anthropic, return structure, and use cases. Every sentence earns its place with no redundancy.

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

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

For a tool with no output schema, the description adequately explains the return format (per-model and combined). It covers key behavioral aspects (default free, optional cost, disambiguation via context). Given the tool's complexity and that only one parameter is required, the description is fully complete for an agent to 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 has 100% description coverage, meeting the baseline of 3. The description adds meaningful context beyond schema: explains default model behavior, clarifies the API key's purpose (only needed for Anthropic), and gives usage examples for the context parameter ('Boston restaurant').

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 function: probing LLMs for visibility of a business/brand/product and scoring it 0-100. It specifies the default model and optional Anthropic, and distinguishes from siblings by focusing on AI visibility audits across multiple models, which is a unique capability among the listed sibling tools.

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

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

The description provides explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains default behavior (free Workers AI) and when to provide an API key for Anthropic. It doesn't explicitly exclude alternatives but gives enough context for appropriate selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond what annotations capture by revealing the massive internal routing (5,566 tools, 1462 sources), the stable citation URIs (pipeworx://), the one-call execution, and explicit behavior of filling arguments. It is fully transparent about the response format and points to the grounded variant for verbatim evidence, contrasting what this tool does NOT provide by itself.

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 packed with value. The first sentence immediately conveys the tool's primary distinction ('PREFER OVER WEB SEARCH') and front-loads the categories and sources. The strategic use of colons, the explicit 'Examples:' list, and the clear 'Step up only when needed' hierarchy earns high marks for scannability and structure. Slightly long, but every sentence does work.

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 of this complexity (route to one of 5,566 tools), the description is thorough. It covers what to expect as a default entry point, when to step up to more specialized siblings, how to use the grounded variant, and clarifies the behavior around news and broad research questions. It even anticipates and answers the question of 'what if I use web search instead?' by stating to prefer this. The description covers the essential aspects of the tool's scope, limitations, and exceptions.

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 parameter schema has 100% coverage with multiple aliases (q, text, input, query, prompt) and clear examples. The description adds value by clarifying the semantic flexibility of the parameter ('Your question or request in natural language') and confirms the tool fills arguments, so the agent understands it can just pass a natural language query without worrying about parameter details. The examples in the schema are good, but the description's explicit routing and argument-filling behavior gives full context.

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

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

The description uses a specific verb+resource structure ('Ask Pipeworx... Routes the question to the right one of 5,566 tools') and immediately differentiates from siblings by stating 'PREFER OVER WEB SEARCH' and naming ask_pipeworx_grounded and deep_research as alternatives. The explicit use cases and examples leave no ambiguity and clearly distinguish this from siblings.

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

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

The description provides explicit guidance on when to use this tool, stating 'START HERE for most questions' and 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. It also includes exclusions and alternatives for breaking-news scenarios, which is exactly what a usage guideline should offer.

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, covering the safety profile. The description adds the beta context and confirms it is a full working router, not a fallback, but doesn't elaborate on any other behavioral traits (e.g., latency, error handling, or return format specifics). It adds some value but not extensive transparency.

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

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

The description is moderately concise, with each sentence contributing to context (beta status, current state, usage note). It is front-loaded with the key differentiator. Slightly verbose due to the parenthetical about candidate retirement, but that provides useful historical context.

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 this is a router tool with no output schema, the description is somewhat incomplete on the return format. It mentions 'same response shape' as ask_pipeworx, which relies on the agent knowing the stable tool's format. Also, the complexity of a universal router with 5,566 tools is not fully conveyed in terms of routing behavior, but the reference to ask_pipeworx mitigates this. It's adequate but not fully self-contained.

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

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

With 100% schema description coverage, the schema already documents all parameters and aliases thoroughly. The description only says 'same arguments' as ask_pipeworx, which doesn't add meaningful detail beyond what is in the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same tool set and arguments. It distinguishes from the stable ask_pipeworx by noting it may have experimental routing improvements. However, it doesn't explicitly state it answers natural language questions by routing to internal tools, but that is implied through context and the sibling tool name.

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

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

Provides explicit guidance on when to use: use it like ask_pipeworx when you want the newest routing, and notes that currently it matches ask_pipeworx exactly because no candidate is active. Also explains that results are compared against the stable router for decision making, giving clear context for selection.

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

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

Annotations already declare readOnly, openWorld, and idempotent. The description adds significant behavioral context: it routes through 5,566 tools, fills arguments, fetches data, extracts only from tool result, and enumerates structured refusal reasons (not_in_source, no_tool_match, etc.) and return fields including evidence verbatim quote.

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 dense but each sentence provides unique value: mode name, routing mechanics, return contract, usage cases, and cost trade-off. It is front-loaded with the core purpose and uses structured return formats to convey detail compactly.

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

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

Despite lacking an output schema, the description specifies the exact return structure on success and failure, including refusal reason enumerations. It covers when to use, how it works, resource scope, and cost implications, making it complete for a tool with this complexity.

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

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

Schema coverage is 100% (question with documented aliases), so baseline is 3. The description does not add parameter-specific details, but the single required question parameter is adequately covered by the schema's own description, and the description implies the question flows into routing without needing extra explanation.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from sibling ask_pipeworx by emphasizing extraction using ONLY tool result and evidence quotes, and from other siblings by its refusal mechanics.

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

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

Explicit user guidance is provided: use when answers will be quoted/cited/acted on and facts must not be invented, with concrete examples. It also specifies when not to use it ('prefer ask_pipeworx for casual lookups') and notes the extra LLM call cost, making the alternative choice 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details beyond annotations: how it resolves markets, fan-out examples, response shapes, resolver contract, parent event extractor, news fields with fallback handling, safety mechanisms (low-confidence, closed markets, wide spreads), and resolution-rule risk. 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, lacking conciseness. While it uses all-caps headings (CLASSIFIERS, FAN-OUT EXAMPLES) for some structure, it is a wall of text that could be more streamlined. For a complex tool, some length is justified, but it still could be improved.

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

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

Given the tool's complexity, the description is extremely thorough. It covers all aspects: input formats, classification types, fan-out examples, response shapes, resolver contract, parent event extraction, news field handling, safety behavior for various edge cases (low confidence, closed markets, wide spreads), and resolution-rule risk. No output schema is provided, but the description compensates fully.

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

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

Schema coverage is 100%, so baseline 3. The description adds extra context beyond schema: clarifying that 'market' can be slug, URL, or question text; explaining 'depth' values ('quick' vs 'thorough'); and describing 'include_raw' behavior. Examples in input schema also 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 states it researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, fanning out to data packs, and returning evidence. It specifies use cases ('should I bet on X') and provides extensive detail on what the tool does, distinguishing it from sibling tools like ask_pipeworx and polymarket_edges.

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

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

The description explicitly states when to use the tool ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It does not explicitly state when not to use it or compare with alternatives, but the use cases are clear and the sibling list provides context for differentiation.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds rich detail: data sources (SEC EDGAR/XBRL, FAERS, FDA, trial counts), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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?

Every sentence adds value, covering triggers, behavior, data specifics, sorting, and efficiency. Slightly long but front-loaded with user-facing query examples. Could be slightly more structured with bullet points, but overall efficient.

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

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

Given no output schema, the description adequately covers return format (paired data + citation URIs), data sources, sorting, and parameter nuances. The tool is well-characterized 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% but the description adds critical meaning: explains what 'company' and 'drug' types pull (specific financial metrics vs. adverse event/trial data), and clarifies that 'values' should be tickers/CIKs or drug names. This goes well beyond the schema descriptions.

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

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

The description explicitly lists natural-language triggers like 'Compare X and Y', 'which is bigger', 'head to head', and clearly states it performs side-by-side comparison of 2–5 companies or drugs. It distinguishes itself from sibling tools like entity_profile by emphasizing efficiency over sequential lookups.

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 strong guidance: 'ALWAYS PREFER over sequential single-pack lookups' and gives concrete query examples. It does not, however, mention when not to use it (e.g., when needing more than 5 entities or different data types).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds that the tool returns a list and suggests follow-up actions, but does not disclose behaviors like pagination handling or rate limits beyond what annotations imply.

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

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

Two sentences efficiently convey the tool's purpose, return fields, and how to use the result. No redundant words, and the structure is front-loaded with key information.

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

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

Given the simplicity of the tool (3 optional parameters, no output schema), the description is complete: it specifies what is returned and how to proceed with the results. No gaps remain for an agent to invoke it correctly.

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

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

The input schema provides 100% coverage with clear descriptions for all three parameters (limit, query, offset). The description only echoes that search is 'by keyword', adding no new semantic value beyond the schema. Baseline 3 is appropriate.

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

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

The description explicitly states the verb 'search' and the resource 'Santa Clara County Open Data catalog', and lists the specific fields returned (resource_id, name, description, category, update date). This clearly distinguishes it from sibling tools like generic 'query' or 'search_within'.

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 guidance: use this tool to find datasets by keyword, then pass the resource_id to another tool ('query/metadata') for more details. However, it does not explicitly state when not to use this tool or list alternatives, though no direct alternative exists 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?

The description discloses extensive behavior beyond annotations: account/auth requirements, decomposition into facets, parallel routing to 5,566 tools, gap[] reporting with no invention, second-hop recovery for standard/thorough depths, contradictions[], semantic excerpting, latency expectations, and resolvable citation_uri only when source emits it. Annotations are readOnly/openWorld/idempotent/non-destructive and nothing contradicts them.

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

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

The description is long but dense and front-loaded with critical info (account required). Some sentences are overlong with parentheticals and the single-paragraph format could be better structured with bullets/sections, but every sentence adds value and the length is justified by the tool's complexity.

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

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

Given no output schema, the description thoroughly explains the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation, hop, contradictions[]) and all behavioral edge cases (gaps, unreachable citations, latency, excerpting). It is fully complete for a complex research 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?

Input schema has 100% coverage with detailed depth descriptions. The tool description adds narrative around depth semantics (gap recovery, lead chasing, contradictions scan) and clarifies the question param accepts broad/multi-part questions, enriching the schema's meaning.

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

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

The description explicitly states the tool performs grounded multi-source research across 1462 structured data sources in one call, decomposing questions into facets and routing them to parallel tools. It clearly distinguishes itself from ask_pipeworx and open-web search, making its scope and 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?

Provides explicit when-to-use guidance: broad/multi-part structured-data questions, with direct alternatives for single lookups (ask_pipeworx), breaking/current news (ask_pipeworx), and unsigned-in users (ask_pipeworx). Also notes account requirements and paid depth tier, leaving no ambiguity about selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that results include 'full input schemas (with curated examples)' and that each result is 'ready to call directly.' This provides useful 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 4 sentences, each serving a purpose: summary, use-case list, output format, usage advice. The first sentence immediately states the tool's function. Slightly verbose but efficient.

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

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

Given the tool's complexity (6 params, 1 required, many aliases, many siblings), the description covers purpose, scope, output details, and when to use. No output schema exists, but description explains what is returned.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions aliases (task, q, search, description) and gives example queries. It does not add significant semantic detail beyond the schema's descriptions.

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

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

Description starts with 'Find tools by describing the data or task.' It lists specific use cases (SEC filings, FDA drugs, etc.) and explains return format. This clearly distinguishes from sibling tools like 'query' or 'search_within' which are for direct data retrieval.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear when-to-use guidance and implies it is for discovery before selecting a specific tool. No alternative siblings are needed as the tool is unique.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. The description adds context about data sources (SEC, XBRL, USPTO, news, GLEIF) and a soft-fail on patents. This adds value beyond annotations, though annotations cover the safety profile well.

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: examples, purpose, data sources, return values, caveats. It is somewhat long but every sentence adds value. Could be trimmed slightly but is effective.

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

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

No output schema exists, so the description carries the burden. It lists key return fields (cik, filings, fundamentals, patents, news, LEI) with minor details (e.g., up to 5 filings). Lacks exact structure of each returned item but is sufficient for a broad profile tool.

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

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

Schema coverage is 100%, but the description adds meaning by clarifying that value accepts ticker or CIK (not names) and that type is limited to 'company' currently. This goes beyond the schema definition.

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

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

The description clearly states the tool returns a full cross-source profile of a US public company. It provides explicit example queries ('Tell me about X', 'research Acme') and distinguishes itself from chaining single-pack lookups, 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 explicitly advises prefer this tool over chaining individual lookups when a holistic view is needed. It also notes that names are not supported and directs the user to resolve_entity first, 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 already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to repeat those. However, it adds no additional behavioral context beyond deletion, such as reversibility or side effects. Missing detail is minor given the annotations.

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

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

The description is two concise, front-loaded sentences. Every sentence adds value: first states purpose, second gives usage guidance. 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 deletion tool with one parameter and good annotations, the description covers purpose and usage adequately. It does not explain return values or error cases, but these are not critical given the 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 a single parameter described. The description reiterates 'Memory key to delete' which adds no new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb ('Delete') and resource ('memory by key'), and distinguishes from sibling tools by mentioning 'remember' and 'recall'. The action is unambiguous.

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

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

The description provides explicit contexts for when to use the tool: when context is stale, task is done, or to clear sensitive data. It also suggests pairing with remember and recall, but does not explicitly list when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral specifics: fetching the page, extracting title/description/key links, and outputting standard llms.txt markdown. No contradictions with annotations.

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

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

The description is concise with two sentences plus a list. The core purpose is front-loaded in the first sentence. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (2 params, no output schema, strong annotations), the description covers the main behavior and output. It lacks details on error handling or format specifics but is generally complete for selection and 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 clear descriptions for both parameters. The description adds minimal new meaning beyond schema, only reiterating that the output includes links. Baseline of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb and resource. It distinguishes the tool by its niche use cases (indexing for AI, personal project, competitor audit) among many sibling tools.

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

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

The description explicitly lists use cases ('useful for...'), providing clear context for when to invoke the tool. However, it does not explicitly exclude scenarios or name alternative tools for different purposes.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint=false. Description adds return fields and mentions active subscriptions, providing useful 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?

Two sentences: first states main action, second gives use case. No wasted words, front-loaded.

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

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

Simple tool with one optional parameter. Description lists return fields, annotations cover safety, and usage is clear. 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?

Schema coverage is 100% and already describes 'include_inactive' well. The description does not add extra parameter semantics 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 'List the caller's active subscriptions' with specific verb and resource. It distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Implies alternatives for adding and canceling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns schema metadata (columns, types, row count, etc.), which is consistent. No further behavioral traits disclosed; rating is adequate given annotation coverage.

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 front-loaded with verb and resource, listing key metadata fields. No unnecessary words, efficient and clear.

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

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

For a simple one-parameter tool with no output schema, the description adequately covers purpose, parameter, and return fields. Lacks details on error handling or rate limits, but acceptable given minimal complexity.

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

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

Schema coverage is 100% with param description 'Dataset id, e.g. "n9u6-aijz"'. Description adds context (Santa Clara County Open Data) and example, enriching meaning beyond the schema's type string. Baseline 3, elevated to 4 for added 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?

Description clearly states verb 'Get', resource 'dataset schema + metadata', lists specific attributes (columns, types, row count, etc.), and provides an example resource_id. This distinguishes it from sibling tools like 'datasets' (which lists available datasets) and 'query' (which retrieves data within a dataset).

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

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

No explicit guidance on when to use this tool versus alternatives. While the purpose is clear, the description does not mention when not to use it or suggest alternative tools for different tasks (e.g., 'datasets' to find data, 'query' to retrieve data).

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

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

Although annotations only indicate non-read-only and non-destructive, the description adds substantial behavioral context: filing without an account returns a claim_token, passing that token later reads resolution status, and the action is rate-limited to 5 per identifier per day. It also warns not to paste end-user prompts, which is an important behavioral constraint. 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 longer than average, but every sentence earns its place: purpose, use-case triggers, cross-server exclusion, token mechanism, rate limit, and guidance on what to write. It is front-loaded with the core action and then escalates into operational details without fluff or repetition.

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

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

The description fully covers when to use the tool, when not to, how to follow up via claim_token, rate limits, and expected behavior. Despite lacking an output schema, it explains the return token and the resolution-reading flow. An agent can correctly invoke the tool and set user expectations.

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, but the description elevates this by explaining claim_token round-trip usage and message guidance (specificity, typical length, avoidance of end-user prompts). It also clarifies the meaning of 'type' values implicitly via the use-case list. The extra narrative goes beyond the schema's field descriptions.

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

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

The description opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly frames the tool as a feedback channel for Pipeworx's own tools, which distinguishes it from sibling tools like ask_pipeworx or discover_tools. The title and description are fully aligned.

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

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

The description explicitly states when to use the tool: for bugs, feature/data gaps, or praise. It also gives a crisp exclusion rule: do not report issues for tools from other MCP servers, and file those with the respective server instead. The phrase 'ONLY for tools served by this Pipeworx connection' provides a testable decision rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable context: data source (CF analytics-engine), no PII, cache duration (5min-1h). No contradictions. Fully transparent 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?

Four sentences, no redundancy. First sentence captures core purpose, second lists use cases in a bullet-like format, third provides data source context, fourth clarifies caching. 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?

Despite lacking an output schema, the description adequately explains what is returned (top tools, packs, call volume). For a simple tool with one parameter and clear output, the description is complete and actionable.

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 only parameter 'window' is fully covered by schema (enum, description). The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', which enriches agent understanding beyond the schema.

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

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

Description clearly states the tool returns top tools, packs, and call volume over a recent window, using specific verbs and resources. It distinguishes from siblings by emphasizing trending/aggregate usage data, which is unique among sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming popular tool, aligning use case). While no explicit when-not-to-use is given, the context is clear and sufficient for typical use. Lacks explicit alternatives but purpose is narrow enough.

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

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

Discloses behavioral traits beyond annotations: monotonicity checks, partition-sum logic, semantic anchor with Jaccard threshold (0.30), partition filter for placeholder slugs, fill check against CLOB depth. Annotations indicate read-only, idempotent, non-destructive, and description aligns with—and enriches—these.

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?

Detailed but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded core description. Slightly long but all content 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?

Comprehensive for a complex tool: covers all modes, output fields (opportunities, partition_check), edge cases (placeholders, similarity, fill check), and references sibling tool. Without output schema, it compensates by describing response structure.

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

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

Input schema covers both parameters (event, topic) with descriptions (100% coverage). The description adds context: recommends event for specific markets, explains slug format, and defines topic as a seed question. Valuable but schema already does heavy lifting.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly instructs when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also advises when not to trade (if fill_check shows non-positive realizable edge) and points to polymarket_fill_risk for custom sizing.

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

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

Description goes far beyond annotations by detailing output fields (edge_pp_net, kelly_fraction), caching behavior ('Cached 1h at the KV level'), Fed bet handling, and diagnostic fields. It explains model families and their assumptions, providing comprehensive transparency. 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?

Front-loaded with clear purpose in first sentence. Structured with numbered segments and bold labels. However, length is substantial (4 paragraphs), and some technical details could be condensed without losing completeness.

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 thoroughly explains response structure (by_segment, fed_candidates, _diagnostics) and all parameter tuning. Caching, edge cases (thin partitions, Fed bets), and diagnostic counters are covered, making the tool fully usable without external documentation.

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

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

With 100% schema coverage, baseline is 3, but the description adds extensive context for each parameter (e.g., slippage_pp explains typical bid/ask spreads, min_partition_leg_kelly explains partitioning logic). This significantly enhances agent understanding beyond the schema descriptions.

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

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

Description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('Scan', 'return') and identifies the resource ('top Polymarket markets') and outcome ('opportunities'). Distinguishes from sibling tools like polymarket_arbitrage by focusing on model-driven and structural arbitrage segments.

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

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

Description explicitly states it is built for 'what should I bet on today' and describes different segments and parameters. However, it does not provide direct comparisons or exclusions relative to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving inference to the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details: snapshot-based, 60-day TTL, daily closes not intraday, gap handling. No contradictions.

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

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

The description is well-structured: purpose first, then response format, then limits. It is dense but not overly verbose. A minor improvement could be trimming redundant mentions of defaults.

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

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

No output schema exists, yet the description comprehensively explains the response structure (tracked, expired, snapshot_dates) and edge cases (gaps, TTL). This fully compensates for the missing schema.

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

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

Input schema covers both parameters with descriptions. The description repeats defaults and options, adding minimal extra context (e.g., 'snapshot family'). With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge duration. It distinguishes itself from sibling polymarket tools by focusing on time-series history rather than current edges or arbitrage.

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

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

The description gives a clear use case with an example contrasting fresh and old edges, indicating when this tool is appropriate. It could more explicitly state when not to use it, but the context is sufficient.

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, and non-destructive. The description adds rich behavioral context: it walks the order book ladder, calculates slippage, returns verdicts (clean|degraded|cannot_fill), and details basket fill risks like 'thin_legs' and 'forced_directional_risk'. It discloses that partial fills convert arb into unhedged directional positions—a critical behavioral insight.

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

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

The description is verbose but well-structured with clear section headers (SINGLE-MARKET, BASKET) and bullet-like formatting. Every sentence serves a purpose, but some redundancy could be trimmed (e.g., repeating 'default' details). Still, it's effective and easy to scan.

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

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

Despite no output schema, the description thoroughly documents all return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and edge cases (thin_legs, forced_directional_risk). It also explains the risk of unhedged positions, making the tool's behavior fully understandable.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it explains the difference between 'market' and 'event' (single vs basket), clarifies the interpretation of 'size_usd' in both modes, and details the default behavior of 'side' in basket mode (auto from partition sum). This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and provides specific verbs ('walks the ladder', 'returns') that clarify the action. This sets it apart from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about scenarios when not to rely on theoretical edge ('theoretical overround on thin books is not capturable') and explains the risk of partial basket fills. This provides clear when-to-use and when-to-avoid guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, not destructive. Description adds critical behavioral details: compatibility_warning conditions (non-equivalent bet shapes, semantically unrelated events), temporal alignment, skipped cross types. 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 lengthy but well-structured with bold headings and clear sections. It front-loads the core purpose and modes. Could be slightly more concise, 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, the description fully explains the response structure (venue prices, matched spread, safety fields) and covers edge cases. No missing information apparent.

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

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

Schema covers all 3 params with descriptions. The description adds context on how each parameter works in the two modes, including examples and override behavior. Exceeds 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 computes cross-venue spreads between Kalshi and Polymarket for the same question. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Explicitly describes two modes (topic shortcuts vs. explicit tickers), explains when compatibility warnings fire, and notes that most pre-mapped topics currently return warnings, setting 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description does not contradict. The description adds behavioral context: the syntax (SoQL clauses without leading $) and the return format (JSON). This is sufficient for a read-only query 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 two sentences long with no filler. Each sentence serves a purpose: one states the action and inputs, the other specifies the output format. It is front-loaded with the most critical information.

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

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

For a 7-parameter tool with full schema coverage, the description provides adequate context. It specifies the output format (JSON) and hints at syntax conventions. Though it lacks details on error handling or pagination, annotations and schema cover critical behavior. The absence of an output schema is compensated by the description stating 'Returns matching rows as JSON.'

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%, providing baseline clarity. The description adds the nuance that SoQL clauses should not include the leading '$$', and includes an example in the schema examples. This aids interpretation but does not go beyond what the schema already explains.

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

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

The description clearly states the tool runs a Socrata SoQL query on a Santa Clara County Open Data dataset, specifying the resource_id and available clauses (where/select/group/order, limit/offset). This distinctively separates it from sibling tools, none of which perform SoQL queries.

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 implicitly guides usage by specifying the exact context: Socrata SoQL against a specific dataset ID. However, it does not explicitly mention when to avoid using this tool or compare it with alternatives like 'datasets' for discovering available datasets.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds scoping to user identifier and rationale (avoid re-deriving). Does not contradict annotations, but could mention behavior on missing key.

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, no waste. Purpose first, then usage guidance, then scope and pairing. Very efficient and well-structured.

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

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

Completely adequate for a one-optional-param tool with no output schema and supportive annotations. Covers retrieval, listing, scoping, and paired tools.

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

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

Schema covers 100% of parameters with clear description. Description adds semantics that omitting key lists all saved keys, which is not in schema. Baseline 3 increased to 4 due to this extra 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?

Description clearly states the tool retrieves a saved value or lists keys, distinguishing it from siblings remember and forget. Verb+resource combination is specific and unambiguous.

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

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

Explicitly explains when to use (retrieve stored context), when to omit key (list all), and pairs with remember/forget. Provides concrete examples like ticker, address, research notes.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint as safe. The description adds valuable behavioral details: it returns source, citation_uri, payload; can mark events read; and is appropriate for polling. 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 concise, front-loaded with the main purpose, and every sentence provides useful information without redundancy.

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

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

Given 5 parameters with 100% schema coverage, no output schema, and annotations present, the description covers return fields, filtering, polling behavior, and an alternative access method—fully adequate for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description enriches each parameter with usage examples ('sec_8k' for type, ISO timestamp for since, 'so the next call only shows newer ones' for mark_read). This adds 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 pulls fired events from subscription feed, specifies return fields, and distinguishes itself with filtering and mark_read features. It uses a specific verb ('Pull') and resource ('fired events from your subscription feed').

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 indicates polling works fine and mentions an alternative endpoint for scripts/dashboards, providing context on when to use this tool vs. direct API. It doesn't explicitly exclude other tools, but the context is sufficient.

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

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

The description adds significant behavioral context beyond annotations: parallel fan-out to multiple sources, fallback logic, soft-fail for USPTO, and output structure (changes grouped by source, total count, citation URIs). Annotations already indicate read-only, idempotent, non-destructive, and the description aligns with these.

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?

Although somewhat long, every sentence is necessary and informative. The description front-loads the purpose with common queries, provides parameter details, sources, fallback, and output format. No redundancy or 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 complexity (multiple data sources, fallback logic, no output schema), the description is complete. It explains the input parameters, output structure, and distinguishes from a sibling tool, enabling the 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%, but the description adds substantial value: explains `since` parameter with examples of ISO date and relative shorthand, recommends typical use ('30d' or '1m'), and clarifies `value` accepts ticker or CIK. For `type`, it notes only 'company' supported.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' and lists specific sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes from sibling tool 'entity_profile' by explicitly stating when to use that alternative.

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

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

The description provides explicit usage examples ('What's new with X', 'latest on Y') and gives guidance on fallback behavior (GDELT→GNews). It also explicitly states when not to use this tool ('Use entity_profile instead when you want the static profile').

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 idempotentHint=true and destructiveHint=false. Description adds key details: persistence differences (authenticated vs anonymous), 24-hour retention for anonymous, and key-value pair scoping. No contradictions.

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

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

Two sentences with front-loaded purpose, then usage, then behavioral details. Every sentence earns its place with no redundancy.

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

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

Covers purpose, usage, persistence, and pairing with recall/forget. No output schema exists, but for a storage tool the description is sufficient. Minor gap: doesn't mention if overwriting existing key is possible or any size limits.

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

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

Schema coverage is 100%, but description adds value by providing concrete examples for key (e.g., 'subject_property', 'target_ticker') and clarifying that value is 'any text.' This aids correct usage beyond bare 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 'Save data the agent will need to reuse later' and provides specific examples like ticker, address, preference. It distinguishes from sibling tools recall and forget by explaining its role in the workflow.

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

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

Explicitly states 'Use when you discover something worth carrying forward' and 'Pair with recall to retrieve later, forget to delete.' It gives clear context for when and how to use this tool.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and the description adds substantial context: identifiers are labelled with their source, unresolved identifiers are explicitly stated under `unresolved`, and enrichment degrades gracefully if GLEIF or OpenFIGI are unavailable. This goes well beyond the annotations.

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

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

The description is somewhat long but well-structured: it opens with example queries, then covers supported types, data sources, fallback behavior, and efficiency benefits. Each sentence adds value, though it could be tightened without losing important information.

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

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

With no output schema, the description thoroughly explains return contents (CIK, ticker, LEI, FIGI, RxCUI), source labelling, unresolved handling, and graceful degradation. It also covers edge cases like ISIN and non-US issuers, making it complete for a tool of this complexity.

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

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

Although the schema covers 100% of parameters, the description greatly enhances meaning by detailing both `type` options and their data sources, and by giving concrete `value` examples (AAPL, CIK, ISIN). It also explains special cases like ISIN mapping to legal entities via GLEIF, adding 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 resolves user-spoken names to canonical identifiers, with specific verbs and scope ('resolve a user-spoken NAME to the canonical/official identifiers other tools require as input'). It is easily distinguished from sibling tools like compare_entities or entity_profile, which operate on already-resolved entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing strong when-to-use guidance. It also lists supported types and input formats, but does not explicitly name alternative tools or when not to use it, so it falls short of a 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds valuable context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. No contradiction.

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

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

Two sentences, each dense with information. Front-loaded with primary verb and resource. No filler or repetition.

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

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

No output schema exists, so description compensates by detailing the return format (ranked list with score, confidence, signal density). Covers all 4 parameters, use case, and expected behavior comprehensively.

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

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

Despite 100% schema coverage, description adds meaning: explains that the first entity in 'entities' is treated as the subject and the rest as competitors. Provides usage details for 'models', '_apiKey', and 'context' parameters beyond their schema descriptions.

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

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

Description uses specific verb 'Compare' and resource 'AI visibility across multiple entities', clearly distinguishing it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison). Example use case reinforces purpose.

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 applicability for competitive AI-marketing audits and gives an illustrative example. Implicitly differentiates from ai_visibility_check by focusing on multi-entity comparison, but does not explicitly state when to avoid using 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?

Beyond the annotations (readOnlyHint, etc.), the description adds critical behavioral details: partial failure handling (bundlephobia timeout up to 5-30s, sources_failed list) and return structure. 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 fairly long but each sentence adds value. It is front-loaded with the core purpose and then details. Slightly verbose but all earned.

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 details return fields (summary block, per-advisory, links, alternative versions), usage context, limitations, and failure modes. Complete for the complexity.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema: explains scoped packages, version defaults, and implications. Provides context that helps 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's purpose: a composite check for npm packages covering license, advisories, version history, bundle size, etc. It uses specific verbs and resources, and distinguishes 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?

Explicitly says when to use ('whenever an agent asks...') and notes limitations (NPM only v1, fallback for other ecosystems). Provides clear context and alternatives.

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

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

Annotations already document non-destructive, read-only, idempotent, open-world behavior. The description adds specific technical details such as embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation flag.

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

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

The description is concise, front-loaded with the core purpose, and every sentence earns its place by adding useful information without redundancy.

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

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

Without an output schema, the description adequately explains return format (top-N passages with character offsets and similarity scores). It also covers constraints like the character cap and truncation behavior. Combined with rich annotations, the tool is fully specified.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the limit parameter controls top-N passages, provides query examples, and clarifies the text parameter's maximum length constraint.

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 semantic search inside a fetched record using a natural-language query, and distinguishes it from siblings by mentioning it pairs with ask_pipeworx_grounded for grounding over passages.

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 recommends using this tool when the record is too large for the prompt, explaining it saves context and returns only relevant passages. Also provides a pairing strategy with another tool.

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

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

Annotations indicate creation (readOnlyHint=false) and non-destructive behavior. Description adds significant behavioral context: OAuth requirement, delivery channel behavior (persistent feed, optional email/sms/webhook), SMS cap, webhook HMAC signing and auto-disable after 10 failures. 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 appropriately sized for a complex tool, well-structured with clear sections (purpose, requirements, type examples, delivery channels). Every sentence adds value, front-loaded with the core action and return value.

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

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

Given the tool's complexity (multiple subscription types, delivery options, OAuth requirement) and no output schema, the description covers all essential aspects: input constraints, parameter details, side effects, and return value. 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%, and the description adds substantial meaning beyond schema: explains each subscription type's params structure inline (e.g., sec_8k items codes, polymarket_edge topic), clarifies delivery sub-fields (SMS verification, webhook signing details), and documents constraints. Greatly reduces ambiguity.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Provides explicit usage context: requires a Pipeworx OAuth account, lists supported subscription types with examples, and details delivery channel options and constraints (e.g., SMS cap, webhook auto-disable). Does not explicitly state when not to use or mention alternatives, but the guidance is thorough.

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 significant value by detailing the return format (category-bucketed example questions with tool+argument shapes) and the use case. No contradictions; slightly more context could be given about side effects but none exist.

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 informative and well-structured, starting with example queries. It is slightly verbose but every sentence adds value. Could be tightened slightly without loss.

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 low complexity (single optional parameter, no output schema), the description fully covers what the tool does, how to use it, when to use it, and what output to expect. 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 coverage is 100% for the single parameter topic. The description adds the exact enum values (finance, pharma, etc.) and explains that omitting topic gives a cross-category spread, significantly enriching the schema definition.

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

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

Description clearly states it's the onboarding entry point for an agent to learn what questions to ask, returning category-bucketed example questions. It distinguishes itself from siblings like ask_pipeworx (a meta-tool for asking questions) by focusing on discovery and orientation.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do' and explains how to use the optional topic parameter to focus. It also mentions learning how to call meta-tools, providing clear context for when this tool is appropriate.

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

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

Annotations indicate a mutation (readOnlyHint=false) that is idempotent and non-destructive. The description adds crucial behavioral details: ownership enforcement, row deactivation rather than deletion, and preservation of historical events. 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 three sentences with no wasted words. The first sentence states the action and parameter, the second adds ownership constraint, the third explains post-action state. Information is front-loaded and each sentence earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all necessary aspects: action, constraints, side effects, and links to related tools (subscribe, recent_alerts). It is fully sufficient for correct selection and 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?

The input schema has 100% coverage with a clear description for the 'id' parameter. The description adds no additional semantic information beyond stating 'by id', which is redundant. The baseline of 3 is appropriate since the schema already documents the parameter 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 clearly states the action 'Cancel a subscription by id' and explains the behavioral effect (deactivation, not deletion). It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying what it does and its ownership constraint.

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: 'Ownership is enforced — you can only cancel your own subscriptions.' It also implies when not to use it (not for others' subscriptions) and references alternative tool 'recent_alerts' for historical data, but does not explicitly list when to avoid using this tool.

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

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

Beyond the annotations (readOnly, idempotent), the description explains two distinct routing pipelines (SEC EDGAR fast path vs. grounded pipeline), the verdict set, and the critical distinction between could_not_verify (check did not happen) and unsupported (no source exists). It also warns callers against treating could_not_verify as evidence, which is essential 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 longer than average but every sentence carries useful information: user phrasings, routing logic, verdicts, error semantics, and efficiency benefits. It is front-loaded with examples and intent phrases, making it scannable. Slight redundancy like 'Replaces 4–6 sequential calls' could be trimmed, but overall it is appropriately dense.

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 execution paths, multiple verdicts, error states) and absence of an output schema, the description provides a thorough account of behavior, return values, and edge cases. It covers not just what the tool does, but how the result should be interpreted and when it may fail.

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

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

Input schema coverage is 100% with detailed descriptions for both 'claim' and 'tolerance_pct', including an example for claim and defaults/cap for tolerance_pct. The description adds no further parameter-specific detail, so a baseline score of 3 is appropriate since the schema already does the heavy lifting.

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

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

The description clearly states a specific verb and resource: 'natural-language claim verification against authoritative sources.' It also provides common user phrasings ('fact check', 'verify the claim that…') that make the tool's purpose unmistakable. This distinguishes it from siblings like query or ask_pipeworx_grounded, which are broader information retrieval tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates two execution paths (company-financial vs. any other claim). It does not name alternative tools or list when-not to use, but the context is clear and actionable for an agent.

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