Overpass

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

Beyond the read-only/idempotent annotations, the description adds valuable behavioral context: the default model, the cost implication for Anthropic ('BYO key — you pay Anthropic directly'), and the complete response shape ('per-model {score, confidence, signals, raw_response} + a combined view'). This goes beyond what annotations already disclose.

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

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

The description is four sentences, each contributing unique information: purpose, model defaults, return format, and use cases. It is front-loaded with the main verb and resource. No filler or redundant phrases.

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

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

Given the absence of an output schema, the description compensates by specifying the return structure. It covers model selection, API key requirements, cost, and practical applications. For a tool with 4 params and 1 required, this is a complete and informative description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining cost implications for _apiKey ('you pay Anthropic directly') and clarifies that the default model is free. These details are not present in the schema descriptions, enhancing parameter understanding.

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

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

The description clearly states the action ('Probe one or more LLMs'), the resource ('what they know about a business / brand / product / topic'), and the output ('score visibility (0-100) per model'). It also specifies the return structure and use cases, making it distinct from sibling tools like ask_pipeworx or scan_competitor_ai_presence.

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

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

The description explicitly enumerates use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and gives guidance on model selection ('Default model is Workers AI Llama-3.3-70b (free); pass _apiKey to also probe Anthropic'). It does not mention when not to use or name alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful behavior: routes to one of 5,529 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, works on every tier, and is a fast single call. It does not disclose fallback or error behavior, but the added context is substantial.

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 the minimal high-quality example, but every section serves a purpose: domain list, trigger phrases, examples, and escalation guidance. It is front-loaded with 'PREFER OVER WEB SEARCH' and uses clear structural markers. Some redundancy exists (e.g., 'START HERE' and 'default entry point'), but overall it is well organized.

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 general-purpose query router with no output schema, the description covers the essential facets: scope, usage triggers, routing behavior, return style with citations, and differentiation from more specialized tools. It could be more explicit about fallback if no source matches, but for its complexity and given annotations, it is reasonably complete.

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

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

The input schema already describes all parameters and aliases with 100% coverage. The description provides example questions but no additional syntax, constraints, or formatting details beyond what the schema offers, so the baseline 3 is appropriate.

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

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

The description clearly states the tool routes factual questions to authoritative data sources, serving as the default entry point. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research for specialized cases, and lists many domain examples.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'USE whenever', and 'START HERE'. It also explains when not to use it by recommending ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, and notes that breaking-news is already covered.

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

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

Beyond annotations, it discloses that it's a beta with live candidate routing improvements, that no candidate is currently active so it matches ask_pipeworx exactly, and that results are compared to the stable router for merge decisions. It also clarifies it is a full working router, not a fallback stub.

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?

At roughly 90 words, the description is front-loaded with the core purpose, then efficiently covers current status, usage guidance, and a clarifying fallback note. Each sentence contributes 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?

Though there is no output schema, the description explicitly mentions 'same response shape' as ask_pipeworx, allowing an agent to consult the sibling for details. It covers purpose, current state, usage, and behavioral expectations, making it reasonably complete for a simple one-question router.

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

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

The schema provides 100% coverage with descriptions for all six parameters (question and five aliases). The description adds no additional parameter semantics beyond stating 'same arguments,' so the schema does the heavy lifting and baseline 3 applies.

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

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

The description clearly identifies it as a beta version of ask_pipeworx: a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling by being the experimental edge with candidate routing improvements, thus a specific verb+resource+scope.

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

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

It explicitly states to use it exactly like ask_pipeworx when you want the newest routing, providing clear context. It doesn't explicitly name the alternative when not to use it, but implies asking the stable ask_pipeworx for non-experimental needs, and the sibling list makes that obvious.

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, and non-destructive behavior. The description adds substantial context: that answers are extracted solely from tool results, the exact refusal reasons (not_in_source, no_tool_match, etc.), and the extra LLM call cost. 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 dense and well-structured, with every sentence contributing key information: purpose, mechanism, return format, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the core purpose before diving into details.

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

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

Despite no output schema, the description fully explains return values and failure modes, including structured refusal reasons. It also covers usage context, cost implications, and differentiation from siblings, making it complete for effective tool 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 description coverage is 100% since all six parameters are documented as aliases for 'question'. The description does not add any parameter-specific meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb ('EXTRACTS the answer using ONLY what the tool result contains') and resource (same routing as ask_pipeworx across 5,529 tools/1455 sources). It clearly distinguishes from sibling ask_pipeworx by emphasizing the grounded, hallucination-resistant extraction mode.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including the cost tradeoff (one extra LLM call). Names the alternative tool directly.

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

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

Annotations already mark the tool as read-only, but the description adds deep behavioral context: resolver confidence (high/medium/low/none), status codes for low-confidence and closed markets, tradeability warnings for wide spreads, and the cancellation-rule risk. It also explains the fan-out mechanism and the blocking behavior of both low-confidence and closed-market routes.

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

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

The description is long but well-organized with clear ALL-CAPS section headers and no filler. Every paragraph adds unique information (resolver contract, parent-event extractor, news fields, safety, resolution-rule risk). It is not a terse two-liner, but the complexity of the tool justifies the length and structure.

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 carries the full burden of explaining return values. It does this thoroughly: response shapes (result.market, result.analysis, result.evidence), resolver contract with match_confidence and alternatives, parent_event fields, news fallback flags, and safety/error statuses. No critical aspect of the tool's behavior is left undocumented.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the market parameter with concrete slug/URL/question-text examples and adds classifier and fan-out context, but it does not add meaning to the depth or include_raw parameters beyond what the schema already states.

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 opening sentence states a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from siblings like polymarket_arbitrage or polymarket_edges by focusing on the data-research workflow for a single bet, including a market-vs-model 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 says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to apply the tool, but it does not mention alternatives or when-not-to-use, so it stops short of a full 5.

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

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

Beyond annotations (read-only, non-destructive, idempotent), the description reveals data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling (AAPL Sep, NVDA Jan), sorting by primary metric, and output format (paired data + citation URIs). These details give the agent a strong behavioral model.

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

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

The description is dense but well-organized, front-loading trigger phrases and usage guidance. Some redundancy (e.g., 'ALWAYS PREFER' and 'Replaces 8–15 lookups') exists, but every sentence adds useful information. It earns its length.

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

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

With no output schema, the description compensates by stating returns (paired data + citation URIs), explaining data types, sorting behavior, and providing concrete examples. It is complete enough for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100%, providing baseline 3. The description adds semantics for each type: company pulls 10-K metrics, drug pulls adverse-event/trial counts, and values are tickers/CIKs vs drug names. This enriches param meaning 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 opens with natural-language triggers and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It names the operation (compare) and the resources (companies/drugs), distinguishing it from single-entity lookups like entity_profile.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' and lists example queries. It contrasts with alternative sequential lookups and notes the tool replaces 8–15 lookups, making the when-to-use decision clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds extensive context: account/paid requirements, gap recovery mechanics, contradictions[] scanning, citation_uri resolvability, semantic excerpting, and time expectations. This goes well beyond the structured annotations and is consistent with 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 information-dense, front-loaded with the critical account requirement. Each sentence adds new value (e.g., NOT open-web, gaps[], depth behavior, citation URI, contradictions, excerpting). Minor redundancy with the schema's depth description prevents a 5, but overall it is well-structured and efficient.

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

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

For a complex tool with no output schema, the description covers return values (findings packet, gaps[], contradictions[], hop field, citation_uri), behavioral nuances (second-hop recovery, excerpting), prerequisites (account), limitations (breaking news), and performance. It is exceptionally 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 description coverage is 100%, so baseline is 3. The description enhances depth semantics by noting 'depth:"thorough" needs a paid plan' and providing time estimates (15-60s, thorough up to ~90s), which are not in the schema. It also reinforces the question parameter's suitability for broad/multi-part questions, adding practical 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 precisely states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with explicit decomposition and parallel routing, and it differentiates from siblings by noting 'this is NOT open-web search' and contrasting with 'ask_pipeworx' for single lookups. The verb+resource+scope is clear and distinctive.

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

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

Explicit when-to-use and alternatives are given: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also provides an account prerequisite and a fallback: 'If you are not signed in, use ask_pipeworx instead — it works on every tier.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe, non-mutating profile. The description adds valuable behavioral context beyond the annotations: it specifies the return format (top-N tools with names, descriptions, full input schemas, curated examples) and assures that results are ready to call directly without a second schema lookup. This is useful disclosure of behavior not present in annotations.

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

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

The description is concise but information-dense. It front-loads the core purpose in the first sentence, then efficiently provides usage guidance, data domains, return behavior, and a clear call-to-action ('Call this FIRST'). Every sentence earns its place with no fluff or redundancy.

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

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

The tool is a discovery/meta-search tool with moderate complexity. The description fully explains what the tool does, when to use it, what it returns, and how the results can be used. Although there is no output schema, the description explicitly states the return format (top-N tools with schemas) and that no second lookup is needed. With good annotations and a rich input schema, the description is complete for the tool's purpose.

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

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

Schema description coverage is 100% with each parameter having a clear description, including aliases and the limit default/max. The description itself does not add meaning beyond the schema; it only reiterates that the tool accepts natural language queries. Since the schema already carries the full parameter semantics, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from sibling tools by positioning itself as a meta-search/discovery tool for locating other tools, not performing the underlying tasks. The extensive list of domains and the explicit 'Call this FIRST' guidance reinforce its unique role.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It gives clear context for use but does not explicitly mention when not to use it or name alternative tools, so it misses the 'when-not/alternatives' component for a top score.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description discloses detailed behavior: it fans out across multiple sources (SEC, XBRL, USPTO, GDELT, GLEIF), returns specific fields, includes a soft-fail note for the USPTO PatentsView sunset, and explains fallback logic (GDELT→GNews). This adds meaningful context about what the tool does and its limitations.

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

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

The description is dense and front-loaded with example queries, then defines scope, return data, and parameter constraints. While longer than average, every sentence carries useful information and the structure is logical. Slightly verbose but well-organized.

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

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

Given there is no output schema, the description thoroughly explains return values (cik, filings, fundamentals, patents, news, LEI) and provides sufficient context for a multi-source tool. It also covers edge cases (name inputs, patent API sunset) and aligns with sibling usage, making it highly complete.

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

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

Schema description coverage is 100% with detailed descriptions for both 'type' and 'value', including enumeration and formatting examples. The description reinforces the schema but does not add significant new parameter-level semantics beyond what the schema already provides, so a 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 identifies the tool as building a full cross-source profile for a US public company, with specific verbs like 'profile', 'brief me', and 'rundown'. It distinguishes itself from siblings by explicitly noting it should be preferred over chaining single-pack lookups and by referencing resolve_entity for name inputs.

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 examples ('Tell me about X', 'research Acme') and a direct preference statement for holistic views. It also gives a clear alternative: use resolve_entity first if only a name is available, and notes that names are not supported.

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

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

Annotations already cover destructiveness (destructiveHint=true) and idempotence (idempotentHint=true). The description adds minimal behavioral context (e.g., 'clear sensitive data') but does not go beyond what annotations imply. The bar is lower with annotations present, and the description contributes some value, though not substantial.

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

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

Two sentences, front-loaded with the action, no redundant wording. The second sentence adds valuable usage context without fluff.

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

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

This is a simple single-parameter tool with no output schema. Annotations cover behavioral safety, description covers usage scenarios, and schema covers parameter semantics. The tool's context is fully addressed.

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

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

Schema description coverage is 100% with 'key' described as 'Memory key to delete'. The description does not add further meaning beyond the schema. For a single obvious parameter, the baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, with a specific verb ('Delete') and resource ('memory'). This distinguishes it from sibling tools like 'remember' (store) and 'recall' (retrieve).

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

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

Explicitly provides when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. It also directs pairing with 'remember and recall', giving a clear picture of its role in the memory toolset.

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 readOnlyHint and idempotentHint annotations, the description discloses the actual behavior: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also reveals the output is a single text blob. This adds meaningful context without contradicting annotations.

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

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

The description is concise and well-structured: two sentences covering purpose and behavior, followed by a brief bulleted list of use cases. Every sentence earns its place with no redundancy or filler.

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

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

For a tool with just two parameters, full schema coverage, and strong annotations, the description covers purpose, process, output format, and use cases. The lack of an output schema is not an issue since the description explicitly states the output is a text blob. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for both parameters, with url and max_links already described in the schema. The description does not add parameter-specific details beyond what the schema provides, so it meets the baseline but adds no extra semantic value.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a given URL, with a specific verb ('Generate') and resource ('llms.txt'). It explains the purpose (AI crawler indexing) and output format, distinguishing it from sibling tools like scan_competitor_ai_presence or ai_visibility_check.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), offering clear context. However, it does not explicitly state when not to use the tool or mention alternatives, so it stops short of a 5.

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

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

Annotations already declare read-only and idempotent behavior. The description adds return field details and caller scoping, which is useful context 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?

Two concise sentences, front-loaded with purpose and return fields, with zero fluff.

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

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

For a simple read-only list with one optional param and no output schema, the description covers purpose, return fields, and usage guidance. Minor gap: no mention of inactive subscriptions in the description, but the schema covers it.

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

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

The only parameter include_inactive is fully documented in the schema (100% coverage), so the description adds no additional parameter semantics.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the returned fields. It distinguishes from siblings like subscribe/unsubscribe by focusing on review/cancel workflows.

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

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

Explicitly advises using this tool before adding more subscriptions or to find an id to cancel, giving clear when-to-use context relative to subscribe/unsubscribe.

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 are all false (no read-only, idempotent, etc.), so the description must disclose behavior. It does: anonymous filing returns a claim_token, passing that token later returns status/resolution, rate limiting is 5/day, and it's free with no quota. Also notes the team reads digests daily, setting expectations for response time.

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

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

The description is long but every sentence earns its place: purpose, usage criteria, exclusion, message framing, claim_token behavior, rate limit, and cost. It is well-structured, moving from what → when → how → constraints, with no redundancy or filler.

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

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

The tool has a nuanced behavior (filing vs. claiming) and no output schema, but the description covers all bases: use cases, exclusions, message quality guidance, token flow, rate limits, and cost. It is complete for an agent to select and correctly invoke the tool.

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

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

Schema coverage is 100%, so each parameter is already documented. The description adds meaningful guidance beyond the schema: describe issues in terms of Pipeworx tools/packs, don't paste the user's prompt (for message), and explains the two-step usage of claim_token (pass it alone to read status). This extra context justifies a score above baseline 3.

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

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

The description opens with a specific verb+resource pairing: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings by limiting scope to tools served by this Pipeworx connection and explicitly calling out other MCP servers as out of bounds.

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

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

The description gives explicit use cases (bug, feature/data_gap, praise) and equally explicit exclusions ('if the tool came from a different MCP server... file it with that server instead'). It also instructs not to paste end-user prompts and explains the claim_token flow for following up, which is valuable when-to-use guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description reveals the tool's underlying data source (CF analytics-engine), privacy guarantees (no PII), and caching behavior (cached 5min-1h depending on window). This is valuable behavioral context that helps the agent set expectations about freshness and data provenance. The description does not contradict any annotation.

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 a numbered list, making it well-structured and scannable. Every sentence earns its place: the first defines the output, the second lists use cases, and the third explains data provenance, privacy, and caching. It is appropriately sized for the tool's simplicity and richly informative without being verbose.

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

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

Despite having no output schema, the description clearly indicates what the return contains ('top tools, top packs, total call volume', 'just (pack, tool, count)'). It also covers latency (cached) and the data source, giving the agent a complete mental model for a tool with a single optional parameter. The level of detail is appropriate for the tool's complexity.

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

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

The schema already defines the enum for window, but the description adds crucial semantic guidance: shorter windows for current trends, longer windows for steady-state demand. This goes beyond the schema's bare enum description and helps the agent choose the right value. The single parameter is fully explained, and the description also notes the default behavior (24h default in schema) indirectly.

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 top tools, top packs, and total call volume over a recent window. It uses a specific verb ('Returns') and resource ('top tools, top packs, and total call volume'), distinguishing it from sibling tools like discover_tools. The opening line 'What other AI agents are calling on Pipeworx right now' succinctly conveys the unique value proposition.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical choice, aligning with agent needs), which fully answers 'when to use this tool.' It also provides guidance on choosing the window parameter ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), effectively explaining the tradeoffs. No explicit exclusions are given, but the use cases imply clear boundaries.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context that the tool operates on OSM data and that the bounding box order is (south, west, north, east), but does not disclose other behavioral traits such as pagination, rate limits, or default sorting. With annotations carrying most of the burden, this is adequate but not exceptional.

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, front-loaded with the primary action and resource, followed by two relatable examples and the coordinate order. Every sentence carries essential information, with no filler or repetition. It is exceptionally concise and well-structured.

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

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

Given the tool's simplicity (read-only POI query), the description explains what it does, when to use it, and a critical parameter detail. An output schema exists, so return values are already documented. The description is self-sufficient for an agent to select and invoke the tool correctly without additional context.

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 all parameters are individually documented. The description adds value by explicitly stating the bounding box order: '(south, west, north, east)'—a critical detail that the schema does not convey as a sequence. This helps agents correctly map coordinates to the south/west/north/east parameters.

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

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

The description opens with a specific verb and resource: 'Find OSM POIs inside a bounding box.' It clearly distinguishes from sibling tools like pois_near by emphasizing the geometric approach (bounding box) and provides concrete examples ('every park in this area'). This goes beyond a generic statement and ties directly to the tool's function.

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

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

The description gives explicit use cases: 'Use for "every park in this area" or "all restaurants in this neighborhood"'. It implies when to use this tool versus alternatives (e.g., radius-based search), though it does not name specific alternatives or explain when not to use it. The given scenarios are clear and actionable.

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

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

Annotations already declare the tool as read-only, open-world, and idempotent. The description adds meaningful behavioral details such as auto-geocoding for place names, accepting plain-English terms or exact OSM tags, and returning names, tags, and coordinates. It does not contradict annotations and provides useful context beyond the safety hints.

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

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

The description is concise, front-loaded with the primary purpose, and every sentence adds useful information. It includes examples and parameter clarifications without extraneous words, making it highly efficient 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?

Given the presence of an output schema (not shown but indicated), strong annotations, and a detailed description covering input modes, category handling, sample queries, and return values, the description is sufficiently complete for an agent to select and invoke the tool correctly in most scenarios.

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 already describes all parameters with 100% coverage, the description enriches the semantics by explaining the 'place' parameter's auto-geocoding behavior and the 'tag' parameter's flexibility (plain term vs. exact OSM tag). This adds value 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 clearly states the tool's function: finding OpenStreetMap points of interest near a location, and lists example categories (shops, amenities, businesses). It also specifies how to specify location and category, and even includes sample queries that demonstrate its exact purpose, effectively distinguishing it from siblings like 'places_in_bbox' by focusing on 'near a location' rather than bounding boxes.

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

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

The description provides explicit guidance on when to use the tool ('Answers "find bike rental shops in <city>"') and how to provide inputs (location via lat/lon or place name). While it does not explicitly mention alternatives or exclusions, the context and examples make the intended usage clear and practical.

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, but the description adds critical behavioral context: fill check against live CLOB depth, realizable_edge_pp ≤ 0 meaning 'do not trade', placeholder filtering (>20% returns null), and skipped_low_similarity surfacing rejected pair count. 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?

Though dense, the description is front-loaded with the core purpose and then organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK). Every sentence earns its place; there is no fluff or repetition.

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

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

Despite having no output schema, the description documents the response shape (opportunities[] with fields, partition_check in event mode), explains filters, and covers edge cases like realizable_edge_pp ≤ 0 and placeholder fraction >20%. For a tool of this complexity, this is complete and self-sufficient.

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

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

The input schema has 100% coverage for both parameters, and the description goes far beyond by explaining exactly what each parameter does: 'event' walks child markets and checks date-axis/partition, 'topic' flattens related events and runs the comparator on the union. It also clarifies how the parameter choices affect the response.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three call modes (trending_scan, event, topic) and names polymarket_fill_risk as the alternative for custom sizing.

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 usage guidance is provided: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'topic for a themed cross-event scan.' It also states when not to trade (realizable_edge_pp ≤ 0) and explicitly 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?

The description goes far beyond the readOnly/idempotent annotations by disclosing caching ('Cached 1h at the KV level keyed on all knobs'), the response structure (by_segment, fed_candidates, _diagnostics), model-specific behavior (e.g., placeholder-slug filters, halved Kelly, 24h-move warning), and design limitations (Fed signal unreliable). This gives the agent an accurate picture of side effects and outputs.

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 an extremely dense, single-paragraph block with ALL-CAPS emphasis and no bullet points or line breaks. It contains valuable information but is not front-loaded or scannable; an agent must parse a large wall of text before reaching the key parameters. It could be significantly tightened while retaining the essential details.

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

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

With no output schema and a complex multi-segment response, the description compensates by explicitly enumerating the response top-level keys, diagnostics fields, and per-opportunity attributes. It also explains why segments might be empty and how knobs affect results, providing a complete mental model for the tool's behavior.

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

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

Even though the schema documents all 9 parameters (100% coverage), the description adds critical semantic context: it explains that min_partition_leg_kelly applies per-leg rather than parent-level because partition arbs return kelly_fraction_half=0 at parent level, clarifies the 'tradeable-edge' knobs, and provides execution-slippage rationale ('Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade'). This goes beyond the schema's literal field definitions.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which specifies the action, resource, and goal. It also states its intended use case ('what should I bet on today'), clearly distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on disagreement with Pipeworx data.

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

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

The description explicitly frames when to use it: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides context for discovery but does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Even with annotations (readOnly, openWorld, idempotent), the description adds substantial behavioral detail: the 60-day snapshot TTL, cache-miss writing behavior, daily closes vs. intraday, the absolute-value computation for trend/decay, signed edge meaning, and the full response structure. This goes far beyond what annotations provide.

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

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

The description is long but well-structured with clear sections (Args, RESPONSE, LIMITS) and front-loaded with the core purpose. Every sentence provides necessary context—no filler or repetition of the name/title. The detail about response fields and limits 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?

With no output schema, the description fully specifies the return format (tracked[], expired[], snapshot_dates[]) and their fields, plus limitations and edge-case behavior. It covers param semantics, response interpretation, and historical context, making it complete for a telemetry tool with no structured output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond the schema by explaining the lookback behavior in practice (history limited by TTL, gaps from cache-miss), and clarifies the window parameter as a 'snapshot family' that maps to specific snapshot sets. It recaps defaults but also provides operational semantics.

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

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

The description opens with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges by focusing on historical persistence/decay rather than just current edge values.

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 the heuristic about fresh vs. 3-week-old edges, implying when to use this tool. However, it does not explicitly name alternatives or state when not to use it, only implicitly differentiating from polymarket_edges (sibling).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds risk-relevant behavior: it walks the order-book ladder, computes VWAP fill and slippage, flags thin legs, and warns about forced directional risk. It reveals potential for partial fills and the dominant loss mode.

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 highly structured with explicit REQUIRES, SINGLE-MARKET, BASKET, and USE THIS sections. It front-loads the core purpose and every sentence adds specific operational detail rather than padding. Could be considered dense, but it earns its length for a complex tool.

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

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

No output schema exists, so the description carries full burden for return values — it enumerates all key fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, per-leg fill detail, capture_ratio, thin_legs, etc.). It also covers both modes, defaults, clamps, and practical risk guidance, making it 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%, so baseline is 3. The description adds meaningful context: for buys, size_usd is 'max spend'; for sells, 'target proceeds'; basket size is 'settlement notional S (shares per leg)' and side defaults are computed from partition sum. This goes beyond parameter names to clarify interpreted semantics.

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

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

The description opens with a precise purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It names sibling tools (polymarket_arbitrage, polymarket_edges) and explicitly positions itself as the pre-trade risk check, distinguishing it from those arbitrage-detection tools.

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

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

It explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the failure mode (partial basket fills convert an arb into an unhedged directional position) and differentiates single-market vs basket modes with clear requirements.

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 readOnly/idempotent annotations, the description discloses response structure, compatibility_warning triggers, skipped_cross_type counters, and temporal_alignment semantics. It thoroughly explains behavioral edge cases, such as when spreads are mathematically meaningless, without contradicting the annotations.

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

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

The description is front-loaded with purpose and organized into labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS), making it easier to scan. While it is dense and somewhat verbose, the detail is mostly valuable, and the structure prevents it from being a wall of text.

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 carries the full burden of explaining return values and behavior. It covers response fields, warning conditions, skipped pair counters, and temporal alignment meaning, providing comprehensive context for a 3-parameter optional-input 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?

The input schema already covers all 3 parameters with descriptions, providing a baseline of 3. The description adds value beyond this by explaining the two modes (topic vs. explicit ticker/slug) and how the parameters interact, including override semantics, which makes the parameter behavior clearer than the schema alone.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', clearly identifying the tool's function and scope. It further distinguishes itself from sibling tools by specifying the two venues and providing two explicit modes of operation.

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 strong usage guidance, explaining when the spread is a real signal vs. when bet shapes are non-equivalent and providing an explicit caveat: 'pre-mapped ≠ tradeable'. However, it does not name alternative tools, so it stops short of fully explicit when-to-use vs. when-not-to-use with alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context about the return format ('Returns the raw Overpass JSON (elements array with node/way/relation)') and includes an example with a timeout, which helps set expectations. It does not disclose potential pitfalls like timeout errors or rate limits, but the annotation coverage reduces the burden.

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 plus a full example, which is concise and front-loaded with the core action. Every sentence adds value: the action, the context for when to use it, and the output format. The example is self-explanatory and helps demonstrate usage without unnecessary verbosity.

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

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

Given the tool's complexity and the presence of an output schema, the description is complete. It tells the agent what the tool does, when to use it, what the query format looks like (via example), and what the return format is. Annotations cover safety, and the example addresses potential timeout settings. No significant 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% and the parameter description already explains the expected format ('Start with `[out:json][timeout:<n>];` and end with `out body;`'). The description's example duplicates the schema examples and adds no new meaning about the parameter itself. It does not explain edge cases or variations, so it meets the baseline but does not exceed it.

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

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

The description uses a specific verb and resource: 'Run a raw Overpass QL query against OpenStreetMap.' It clearly distinguishes from siblings by noting it is for 'complex spatial queries the helper tools can't express.'

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: 'Use for complex spatial queries the helper tools can't express.' This clearly implies that simpler tools like pois_near or places_in_bbox should be preferred when they suffice. However, it does not name specific alternatives or provide explicit 'when not to use' examples, so it falls just 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 declare read-only/idempotent/non-destructive. The description adds scoping behavior (per-identifier isolation) and clarifies the 'list all keys' mode, which is a useful behavioral detail beyond annotations.

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

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

Three concise sentences. Front-loaded with the action, followed by usage guidance and scoping. No redundant info or filler.

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

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

For a simple one-param read-only tool with strong annotations, the description covers purpose, usage mode, scoping, and relationship to sibling tools. No significant gaps.

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

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

Schema covers 100% of the key param, but the description adds semantics: omitting the key triggers listing all saved keys, and provides context on what keys may represent (ticker, address, research notes).

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 ('Retrieve'), names the resource (values saved via remember), and clarifies an alternative behavior (listing all keys when key omitted). It also distinguishes itself from sibling tools like remember and forget by referencing them.

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

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

Explicitly states when to use: to look up previously stored context without re-deriving. Provides examples of use cases and explicitly partners with remember/forget, creating a clear usage pattern.

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

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

Annotations declare readOnlyHint:true and idempotentHint:true, but the description states mark_read:true flags returned events as read, which mutates persisted state. This is a direct contradiction with the read-only annotation. The description is transparent about the side effect, but the inconsistency is severe and warrants a score of 1.

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

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

The description is four sentences, front-loaded with the core purpose, and each sentence provides necessary context (returned fields, filtering, mark_read behavior, alternative endpoint). It is efficient without being terse.

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 read tool with full schema coverage, the description covers return payload structure, filtering, mark_read state change, and an alternative access method. It doesn't cover limit/unread_only in prose, but the schema handles those, making the overall package complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds an example type ('sec_8k'), explains the consequence of mark_read for subsequent calls, and contextualizes the 'since' filter with ISO timestamps, going beyond the minimal 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 uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), and clarifies the events come from the evaluator's persisted feed, distinguishing it from siblings like recent_changes. It also lists return payload fields, making the purpose highly concrete.

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 filtering by type and since, explains mark_read semantics for incremental polling, and mentions an alternative GET endpoint for scripts/dashboards. It lacks explicit 'when not to use' exclusions but gives 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?

Beyond the annotations (read-only, open-world, idempotent), the description discloses fan-out behavior, GDELT→GNews fallback logic, USPTO soft-fail due to PatentsView API sunset, and the return structure (changes[], total_changes, citation URIs). This adds significant operational 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 dense but every sentence adds value: user-intent examples, source fan-out, fallback behavior, parameter format, output shape, and alternative tool. It is well-structured, front-loaded with natural language queries, and contains no fluff.

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

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

Despite lacking an output schema, the description explains the return format (structured changes grouped by source + total_changes + citation URIs), covers failure modes (GDELT rate limits, USPTO soft-fail), and provides an alternative tool for different needs. This is complete for the tool's complexity.

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

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

The input schema already provides 100% coverage, describing each parameter including the `since` formats and recommendation to use '30d' or '1m'. The description repeats the `since` syntax but adds no additional parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: a change feed for a company over a time window, with explicit fan-out to SEC EDGAR, GDELT→GNews, and USPTO. It distinguishes itself from sibling tools by explicitly naming entity_profile as the alternative for static profiles.

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

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

Usage guidance is explicit: use this tool for time-boxed changes, and 'Use entity_profile instead when you want the static profile... regardless of window.' This clearly indicates when to use this tool vs. the key alternative.

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

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

Adds meaningful behavioral details beyond annotations: memory is scoped by identifier, authenticated users get persistent memory while anonymous sessions retain for 24 hours. Annotations already cover idempotency and safety, and the description does not contradict them; it enriches them with lifecycle and scoping information.

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 the core action, followed by usage guidance, storage semantics, and companion tool references. Every sentence adds value; no fluff or repetition. Well-structured and appropriately sized.

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

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

For a simple two-parameter tool with no output schema, the description covers all essential aspects: when to use, persistence, key-value format, and related tools. It leaves no significant gaps for the agent to navigate the tool correctly.

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

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

Schema description coverage is 100% and provides clear examples for key and value types. The description adds context about key-value pairing and scoping, but parameter meaning is fully carried by 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 opens with a specific verb+resource: 'Save data the agent will need to reuse later.' It clearly distinguishes from siblings by naming companion tools (recall, forget) and clarifying the key-value store nature. This is more than just a restatement of the 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?

Explicitly states when to use ('Use when you discover something worth carrying forward') and provides concrete examples. It also names alternatives and companions: 'Pair with recall to retrieve later, forget to delete.' This gives clear context for choosing this tool over 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?

Beyond the annotations (read-only, idempotent), the description discloses graceful degradation when GLEIF/OpenFIGI are unavailable, explicit reporting of unresolved identifiers, source labeling, and internal cascading lookups. These behavioral traits significantly help an agent anticipate tool behavior and outputs.

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 most but each sentence carries meaning: examples, use-first guidance, per-type details, and degradation behavior. It is front-loaded with the core purpose and examples, though the density may make it slightly harder to scan quickly.

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

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

With no output schema, the description covers what will be returned: canonical identifiers, source labels, unresolved list, and graceful degradation. It addresses failure modes and output structure, making it sufficient for an agent to invoke and interpret results without needing an example output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value with concrete examples (AAPL, 0000320193, ozempic) and clarifies that company input can be ticker, CIK, or name, and drug input can be brand or generic. This enhances the parameter descriptions beyond the schema.

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

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

The description states a specific verb and resource: resolving user-spoken names to canonical identifiers. It provides concrete example queries and explicitly says 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from sibling tools like entity_profile and compare_entities.

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

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

It gives explicit guidance on when to use the tool ('Use FIRST whenever you have a name but need an ID'), describes the two supported entity types with their input formats, and notes that it replaces 2-3 manual lookups. This is clear usage context without needing to list excluded cases.

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

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

Annotations already declare read-only and idempotent behavior, allowing the description to focus on added context. It discloses that the tool probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density, which goes beyond annotations to explain internal behavior and output shape.

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 (three sentences) and front-loaded with the core purpose. Each sentence adds value: the function, the mechanism, and a usage example. 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 tool that aggregates multiple probes, the description covers the essential input semantics (entities, models, context) and output structure (ranked list with score, confidence, signal density). With no output schema, this suffices for an agent to correctly invoke the tool and interpret results.

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

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

Schema coverage is 100%, so parameters are fully documented. The description adds meaningful nuance beyond the schema, such as the first entity being treated as the 'subject' for narrative and the free default for models. This clarifies intended usage that the schema's descriptions do not fully convey.

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: comparing AI visibility across entities side-by-side, probing with ai_visibility_check, and ranking results. It distinguishes itself from the singular ai_visibility_check and generic compare_entities by focusing on competitive AI audits, with a concrete example ('does Claude know about us as well as our competitors?').

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 (competitive AI-marketing audits) and implies the alternative of using ai_visibility_check for single entities. However, it does not explicitly state when not to use this tool or explicitly compare with sibling tools like compare_entities, so it lacks explicit exclusions.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds valuable behavioral context beyond that: partial failure degradation, bundlephobia's first measurement may take 5-30s, and sources_failed listing timeouts. 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 a single coherent paragraph where every sentence contributes essential information: purpose, sources, use cases, output summary fields, ecosystem scope, and failure behavior. It is front-loaded with the core purpose and remains readable despite its length.

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

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

This is a complex composite tool with multiple external services and edge cases. The description covers the output summary block, per-advisory details, links, alternative versions, ecosystem limitations, and performance expectations. Without an output schema, this level of detail is essential and sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no new parameter semantics beyond what the schema already provides (package name, version defaults to latest). It does not compensate with extra detail, hence no increase above baseline.

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

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

The description clearly and specifically defines the tool as a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It distinguishes from alternatives by noting NPM-only scope and directing other ecosystems to deps.dev:version directly, which separates it 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?

Explicit usage guidance is provided: 'Use whenever an agent asks is X safe / popular / small...' and it states when not to use it (non-NPM ecosystems go to deps.dev:version directly). This clearly communicates when to invoke this tool versus 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 mark this as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail: it returns 'top-N passages with character offsets and similarity scores', discloses the embedding model and chunking ('BGE-base-en embeddings + cosine over 500-char overlapping windows'), and reveals input limits and truncation behavior ('cap is 200K chars (longer inputs are truncated and flagged)'). This goes far beyond the annotation hints and helps the agent anticipate outputs and edge cases.

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

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

The description is three sentences, front-loaded with the core purpose. Each sentence earns its place: the first defines function and output, the second explains when to use it and the pairing with ask_pipeworx_grounded, the third provides technical transparency. No filler or redundancy.

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

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

Despite having no output schema, the description clearly states what is returned (passages with offsets and similarity scores). It covers input constraints (cap, truncation), algorithm details, use-case rationale, and the complementary workflow. For a search tool of this complexity, this is complete and self-contained.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add new parameter-specific semantics beyond the schema: 'text' is already described as the document text, 'query' already has examples, and 'limit' is self-explanatory with min/max in the schema. The only marginal addition is the phrase 'Pass the text you already pulled', but this is contextual workflow, not new parameter meaning. Hence a 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 opens with 'Semantic search INSIDE a fetched record', clearly stating the verb and resource. It distinguishes from sibling tools by emphasizing the input is an already-pulled text, unlike broader search tools like ask_pipeworx or query. The phrase 'INSIDE a fetched record' preempts confusion with tools that search external datasets.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter'. It also names a complementary/alternative tool: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and how-it-fits guidance, fulfilling the dimension fully.

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: OAuth account requirement, phone verification, SMS daily cap, webhook auto-disabling after failures, and one-time signing secret. These are meaningful operational details that help an agent anticipate side effects and prerequisites.

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

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

The description is dense but well-structured: purpose → requirements → types → delivery channels. Every sentence carries useful information, though it is relatively long. It avoids redundancy and is front-loaded with the core action.

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 nested params, no output schema, and several caveats, the description covers prerequisites, each subscription type with example params, delivery options with security details, and return value (subscription id). It is thorough and self-sufficient 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 coverage is 100%, so baseline is 3. The description still adds value by giving concrete examples and semantic hints (e.g., items:["5.02"] = officer change, 'cross-venue mispricings'), enriching the parameter understanding beyond the schema's formal definitions.

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

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

The description explicitly states 'Create a proactive monitoring subscription to a live-data event stream' and mentions returning the new subscription id. This is a specific verb+resource pair that clearly distinguishes the tool from siblings like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides clear usage context: requires a Pipeworx OAuth account, explains supported types with examples, and describes delivery channels. However, it does not explicitly contrast with alternative tools (e.g., when to use 'recent_alerts' instead of subscribing), so it lacks explicit exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by explaining that output is category-bucketed example questions drawn from the live catalog, and that topic can be used to focus. This goes beyond the bare safety profile, though it doesn't describe rate limits or error cases.

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

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

The description is dense but well-structured, starting with example user queries, then stating purpose, return content, and parameter usage. While it's longer than necessary, every sentence contributes useful information and it is not tautological or redundant.

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

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

Given the tool's open-ended purpose, no output schema, and the complexity of categories, the description provides enough context: it covers what is returned, how to control scope via topic, and when to use it first. The agent can invoke it correctly without further clarification.

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

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

Schema coverage is 100%, so the schema already documents the 'topic' parameter with its allowed values. The description provides examples like 'finance' and 'betting' but doesn't add new semantic information beyond what the schema offers. Baseline of 3 applies.

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

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

The description clearly identifies the tool as the 'onboarding entry point' and states it returns 'category-bucketed example questions' with 'the exact tool + argument shape that answers it.' This specific verb+resource phrasing distinguishes it from sibling tools like discover_tools and 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?

Explicit guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to omit or pass the topic parameter, giving clear context for use.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description reveals that the operation is a logical deactivation rather than physical deletion, and that historical events remain visible via `recent_alerts`. This adds significant behavioral context that annotations alone wouldn't provide.

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

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

The description is three compact sentences, front-loaded with the primary action ('Cancel a subscription by id'), followed by the ownership constraint and the deactivation consequence. There is zero redundant or irrelevant content.

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

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

For a simple single-parameter tool with no output schema, the description covers the core purpose, constraints, and post-condition effect (deactivation not deletion). It also connects to related tool `recent_alerts`, providing enough context for the agent to select and invoke it correctly.

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

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

The input schema already provides 100% coverage of the parameter `id`, describing it as a subscription UUID returned by `subscribe`. The description adds only 'by id,' which does not meaningfully enhance the parameter semantics beyond the schema.

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

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

The description uses the explicit verb 'Cancel' with a specific resource ('subscription by id'), clearly distinguishing it from sibling tools like `subscribe` (create) and `list_subscriptions` (list). It also immediately mentions ownership enforcement, clarifying scope.

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

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

The description clearly implies this is the tool for canceling a subscription, and the ownership constraint ('you can only cancel your own') provides context for when it's applicable. However, it does not explicitly mention alternatives or when-not-to-use, though the sibling tools `subscribe` and `list_subscriptions` make the use case obvious.

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 rich behavior beyond the readOnly/openWorld/idempotent annotations: it explains verdict semantics, notably that could_not_verify means the check did not happen and must not be shown as evidence, and that unsupported means no source was found. It also discloses the routing behavior and return contents (verdict, value with citation, reasoning), which is valuable for callers.

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

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

The description is a single dense paragraph and is longer than minimal, but every sentence carries substantive information—trigger phrases, routing logic, verdict meanings, and a caller-facing warning. It is front-loaded with purpose and ends with a useful note about replacing multiple calls, so it is efficient despite its length.

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

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

Even without an output schema, the description enumerates the possible verdicts, explains the meaning of could_not_verify and unsupported, and describes the returned components (value, citation, reasoning). It also covers both input types and the internal fallback behavior, making it sufficiently complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific detail about claim or tolerance_pct beyond what the schema already provides; the phrase 'exact percent-delta math' hints at the comparison mechanism but does not elaborate on tolerance semantics. The schema's own descriptions are sufficiently detailed.

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: natural-language claim verification against authoritative sources, with trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself by explaining the structured SEC/XBRL fast path for company-financial claims versus a general grounded pipeline for all other factual claims, making it distinct from sibling Q&A or research tools.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two routing paths (company-financial vs. any other factual claim). It also warns about could_not_verify not being evidence, but it does not name alternative sibling tools or explicitly state when not to use it, so it falls slightly short of full alternative guidance.

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