sunrisesunset

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds key behavioral details: the default free Workers AI model, the requirement for a user-supplied _apiKey to access Anthropic, direct billing implications ('you pay Anthropic directly'), and the exact per-model response structure. This fully sets expectations for side effects and costs.

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 compact—three sentences—and front-loaded with the primary purpose. Every sentence adds useful information: what the tool does, how to configure it, what output to expect, and when to use it. 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?

Given the tool's moderate complexity, the description is complete: it covers the input entity, optional models, API key handling, output format, and example use cases. Since there is no output schema, the explicit mention of per-model {score, confidence, signals, raw_response} plus a combined view adequately compensates.

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 each parameter has a description. The tool description adds semantic value by explaining the default behavior of 'models' (omit for just workers-ai), the meaning of the '_apiKey' parameter (straight pass-through), and the practical implication of using Anthropic (direct payment). This goes slightly beyond the schema without overloading.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It clearly states the tool's function and scope, and distinguishes it from sibling tools like ask_pipeworx or compare_entities by focusing on visibility scoring rather than general Q&A or entity 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?

It provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model choice and optional Anthropic key. It does not explicitly state when not to use it or name alternatives, but the guidance is clear enough for an agent to decide when this tool is appropriate.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=true), and the description does not contradict them. It adds valuable context about behind-the-scenes routing across thousands of tools, argument filling, and the return of structured answers with stable citation URIs, which goes beyond the abstract 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 longer than average but well-structured: a strong opening directive, capability explanation, examples, and escalation paths. Every section adds operational value, but some redundancy exists (e.g., repeating the breadth of sources), so it is not perfectly concise.

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

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

This is a complex router tool with no output schema, yet the description explains its scope, routing behavior, return format ('structured answer with pipeworx:// citation URIs'), and when to escalate to siblings. It provides sufficient context for an agent to decide whether and how to invoke 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?

Schema has 100% coverage with a clear 'question' parameter and aliases, giving a baseline of 3. The description enriches parameter meaning by providing examples of natural-language questions and listing domains (SEC, FDA, FRED, etc.), which helps the agent formulate the input correctly.

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

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

The description clearly defines ask_pipeworx as a router that aggregates answers from 5,564 tools across 1,462 sources, with specific verbs like 'routes', 'returns', and 'fills arguments'. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research while giving concrete examples of supported queries.

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

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

Explicitly instructs to 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and provides clear escalation paths: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. Includes example query types and trigger phrases.

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

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

The description goes well beyond the readOnly/idempotent annotations by explaining that candidate routing improvements are enabled live whenever in test, that no candidate is currently active, and therefore it currently matches ask_pipeworx exactly. It also clarifies that it is a full working router rather than a fallback, making the experimental/behavioral status exceptionally clear.

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 few sentences long and front-loaded with the essence of being a beta version of ask_pipeworx. Starting with 'Beta version' is a slight redundancy with the title, and the sentence about prospective candidate merging adds nuance but also complexity. Overall, it is still reasonably compact and informative for an experiment.

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 compensates by stating the response shape and presentation are identical to ask_pipeworx, so an agent that understands ask_pipeworx will know what to expect. It also covers the dynamic candidate-testing lifecycle and instructs to use it exactly like ask_pipeworx, which is the essential context for activating 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?

The description only says 'same arguments' without adding specifics; all six parameters are already fully documented by the input schema with the 'question' field and its five aliases. Since schema coverage is 100%, the description doesn't need to add parameter detail, but it also doesn't contribute additional meaning beyond noting the exact same argument set as ask_pipeworx.

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 defines the tool as 'Beta version of ask_pipeworx', describing it as a universal router over 5,564 tools with the same arguments and response shape. This is more specific than a bare, making it clear it is the experimental twin of ask_pipeworx, though it doesn't state 'ask a natural-language question' explicitly beyond the schema's parameter descriptions.

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 says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. This provides a clear when-to-use context and identifies an alternative, but it doesn't explicitly say when not to use it or detail trade-offs beyond the experimental nature.

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

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

Despite annotations already declaring readOnlyHint and idempotentHint, the description adds significant behavioral context: it returns a structured refusal with specific refusal_reason values, discloses the 'one extra LLM call' cost, and clarifies that answers are grounded solely in the tool result. 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 six sentences long but every sentence earns its place: mode, routing, return shape, refusal reasons, use cases, and cost trade-off. It is front-loaded with 'Hallucination-resistant answer mode' and avoids redundancy, despite being detailed.

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 documents the return object ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and explicit refusal reasons. It also covers behavioral expectations (no fabrication) and operational costs, making it complete for high-stakes use.

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

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

Schema coverage is 100% with clear descriptions of the single 'question' parameter and its aliases. The description adds no additional parameter semantics beyond restating the natural-language question concept, so the baseline of 3 is appropriate.

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

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

The description clearly states this is a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb ('EXTRACTS') and return contract. It distinguishes itself from the sibling ask_pipeworx by emphasizing extraction only from the tool result and refusal behavior, making the purpose and unique value unmistakable.

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

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

Explicit guidance is given: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' It also mentions the extra LLM call cost, providing a clear trade-off and when not to use it, fulfilling the when/when-not criterion.

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?

Extremely detailed beyond the readOnly/openWorld/idempotent annotations. It discloses resolver match confidence levels, status codes for low-confidence and closed markets, wide-spread tradeability flags, news fallback fields (_fallback_attempted), and cancellation-rule risk (refund_50_50, resolves_no_on_cancel, etc.). This gives the agent a thorough picture of edge-case behavior.

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

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

The description is long but information-dense, with a clear opening that states purpose and usage, followed by scannable ALL-CAPS sections for classifiers, response shapes, safety, and cancellation risk. Some redundancy with the schema exists, but the structure (headings, examples, condensed notes) makes it navigable 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?

With no output schema, the description takes on full responsibility for return value semantics. It thoroughly defines result.market, result.analysis, result.evidence, parent_event, news fields, status codes, and safety behaviors. It also covers edge cases like closed/dead markets, wide-spread markets, and cancellation-rule risk, making it complete for an agent to invoke correctly.

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

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

Schema already documents all three parameters with descriptions and enums (100% coverage). The description adds examples for the market parameter but does not meaningfully expand on depth or include_raw semantics beyond what the schema provides. Baseline 3 is appropriate when schema coverage is high and description adds marginal value.

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

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

Description opens with a specific verb+resource pairing ('Research a Polymarket bet'), states the input formats (slug, URL, question text), and explicitly lists intended use cases ('should I bet on X', 'what does the data say about Y'). It clearly distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on bet-specific research rather than generic edge detection or arbitrage.

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

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

Provides explicit use-case examples ('Use for should I bet on X...') and describes the fan-out behavior with concrete examples (BTC, Fed, Hormuz, etc.), giving strong contextual guidance. However, it does not explicitly name alternative tools to prefer instead, so it lacks 'when-not' exclusions that would merit 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, but the description goes far beyond: it discloses data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, sorting by primary metric, and the inclusion of citation URIs. This is rich behavioral context that significantly helps an agent predict what will happen, and it contains no contradiction with the annotations.

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

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

The description is dense but highly efficient: trigger phrases come first, then usage guidance, then behavioral specifics. Every sentence and clause earns its place, and despite being long, the structure is front-loaded with the most important information for tool selection.

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

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

This is a complex tool with two entity types, multiple data sources, sorting behavior, citation returns, and no output schema. The description covers all these aspects, including a helpful note that it replaces 8–15 sequential lookups, making it nearly complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining exactly what each type value ('company' vs 'drug') retrieves and how the results are sorted, which enriches the semantic understanding of the parameters. The values parameter is already well covered by schema examples, so the additional value is modest but real.

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

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

The description clearly identifies the tool as a side-by-side comparison engine for 2–5 companies or drugs, with explicit trigger phrases and a strong distinction from sequential single-pack lookups. It names the verb ('compare'), the resource ('companies or drugs'), and the scope in a way that leaves no ambiguity.

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

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

It provides explicit when-to-use guidance through natural-language examples and an outright directive to prefer this tool over sequential lookups for comparison tasks. However, it does not mention edge cases such as comparing more than 5 entities or non-company/drug types, so it falls just short of a perfect usage-guideline 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 the readOnly/openWorld/idempotent annotations, the description reveals account/paid-plan gating, parallel decomposition, the exact findings packet structure (verbatim evidence + confidence + source + fetched_at + citation), gaps[] behavior (never invented), contradiction scanning, second-hop iteration, and semantic excerpting. No annotation contradiction.

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

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

The description is long but every sentence adds actionable detail, front-loaded with the account requirement and sibling alternative. Minor redundancy ('not open-web search' appears twice) and dense length, but appropriate for a tool with this many behavioral facets.

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 is self-sufficient: it covers prerequisites, alternatives, return format, failure representation (gaps[]), timing (15-60s), iteration semantics, and citation resolvability. Nothing critical is left to guesswork.

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 schema coverage is 100%, the description adds critical semantics: depth values are explained with exact facet counts (quick=3, standard=3, thorough=6) and their hop/recovery behavior, and question is clarified as natural language accepting broad/multi-part queries. This goes well beyond the schema.

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

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

The description opens with a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and explains the decomposition into facets with parallel routing to '5,564 tools'. It clearly distinguishes itself from siblings like ask_pipeworx by emphasizing the multi-hop, parallel nature.

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/when-not guidance: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and for breaking/colloquial news 'prefer ask_pipeworx'. The description also names alternative tools and the exact conditions under which they should be chosen.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full input schemas (with curated examples), and states that results are ready to call directly without a second lookup. This goes beyond what annotations convey.

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

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

The description is front-loaded with the core purpose and usage. It includes a long list of domains, which is informative but somewhat verbose. The first sentence earns its place; the domain list could be slightly trimmed, but overall it's efficiently 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?

The description covers purpose, when to use, return value (top-N with schemas and examples), and how results are ready for direct invocation. With no output schema, the description successfully compensates by explaining what the tool returns, making it complete for an agent to decide when and how to use 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?

Schema description coverage is 100%, so the schema already explains all parameters including aliases. The description's opening line implies the query is a natural language description, but it doesn't add significant detail beyond the schema descriptions. Baseline 3 is appropriate when the schema fully documents parameters.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It uses a specific verb ('find') and a clear resource ('tools'), and the list of domains distinguishes it from sibling tools that perform those tasks directly rather than discovering them.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' This tells the agent exactly when to prefer this tool over executing a specific task 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 indicate read-only/idempotent/non-destructive. The description adds rich behavioral context: fans out across sources, returns specific fields, notes USPTO API sunset with soft-fail, describes GDELT→GNews fallback, and reiterates input constraints.

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 examples, but the multiple paraphrases (7 query examples) are somewhat redundant. However, the rest of the description is well-structured, using semicolons to separate return fields and fallback behaviors, earning a strong score.

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

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

Even without an output schema, the description enumerates exact return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), source selection, and fallbacks. It covers constraints (ticker/CIK, not names) and performance characteristics ('ONE parallel call'), making it complete for agent 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% and already provides the same examples and constraints for both parameters (ticker/CIK, names not supported, resolve_entity). The description reiterates this without adding new semantic meaning, so baseline 3 is appropriate.

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

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

The description clearly defines the tool as producing a 'full cross-source profile of a US public company in ONE parallel call', with multiple query paraphrases and explicit output components. It distinguishes itself from sibling tools by stating preference over 'chaining single-pack SEC/XBRL/news lookups'.

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

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

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

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'Delete' action aligns without contradiction. It adds context about clearing sensitive data and stale context, going slightly beyond raw annotations. No explicit side effects mentioned, but annotations cover the destructive nature, so a 4 is appropriate.

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 core action, followed by practical usage context and sibling references. No wasted words; every sentence contributes value.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description fully covers purpose, usage, and safety context (with annotations). It 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% with the parameter description 'Memory key to delete.' The description adds only the phrase 'previously stored' and 'by key,' which reinforces but does not significantly expand on the schema. Baseline 3 is justified as the schema carries the parameter meaning.

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

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

The description clearly states a specific verb and resource: 'Delete a previously stored memory by key.' This directly distinguishes it from sibling tools like remember and recall, making the tool's function unambiguous.

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

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

Explicit usage contexts are provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also advises pairing with remember and recall, offering clear guidance on when to use this tool relative to alternatives.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context by explaining the internal steps (fetch page, extract content, emit markdown) and the output format, which goes beyond the basic safety profile. It doesn't introduce contradictions.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value—purpose, process, output format, and practical use cases. It is well-structured without unnecessary 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 simple output (single text blob), and the description explains that output clearly. Combined with the annotations and full parameter descriptions, the description is complete for an agent to correctly invoke and understand 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 description coverage is 100%, and the schema already documents both parameters (url and max_links) with clear descriptions. The tool description does not add additional parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb (generate) and resource (production-ready llms.txt file for any URL). It explains the process (fetches page, extracts title/description/key links, emits standard markdown) and distinguishes it from any sibling tool by focusing on the specific llms.txt output.

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'), giving clear context for when to use. It does not mention when not to use or alternatives, but the use cases are specific enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds value by specifying the output includes all listed times and that they are in the location's local timezone, which is a useful behavioral detail 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 a single, well-structured sentence that immediately lists the outputs and the input requirement. Every word contributes to understanding, with no fluff or repetition. It is concise and front-loaded with the core functionality.

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 simple with two fully described parameters and an output schema, so the description does not need to explain return values. The description covers the essential context: what data is returned, for what location, and in what timezone. Combined with the annotations and schema, it is fully complete for an agent to select and invoke correctly.

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

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

The input schema has 100% coverage for the two parameters (lat and lng) with descriptions and examples. The description only repeats 'given latitude and longitude' without adding new meaning or clarifying format beyond the schema, so the baseline score 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 'Get today's sunrise, sunset, dawn, dusk, solar noon, golden hour, and day length for a given latitude and longitude.' This is a specific verb (Get) with a specific resource (times for a location), and the inclusion of 'today's' differentiates it from the sibling tool get_times_date, which likely handles other dates.

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

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

The description provides clear context: it is for getting today's times at a specific latitude/longitude, and returns local timezone times. However, it does not explicitly mention when not to use this tool or suggest alternatives like get_times_date for other dates. Thus, it has clear context but no exclusions or alternative references.

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 established. The description adds context about the specific time values returned, but does not disclose other behavioral details like timezone handling or error conditions.

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, focused sentence that lists the key outputs and the query parameters. It is appropriately concise with no 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 read-only lookup with an output schema and fully described parameters, the description covers the core purpose. It could be slightly more complete by addressing sibling differentiation or timezone assumptions, but it is sufficient for common use.

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

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

Schema coverage is 100% and each parameter (lat, lng, date) has a clear description. The tool description mostly reiterates the schema's semantic scope without adding new parameter-level details.

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 verb and resource: it gets sunrise, sunset, dawn, dusk, solar noon, and golden hour times for a specific date and location. It is specific but does not explicitly differentiate from the sibling tool 'get_times'.

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 no guidance on when to use this tool versus alternatives. It does not mention situations where get_times would be more appropriate or any 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 this as safe, read-only, idempotent, and non-destructive. The description adds the return field list and the active-vs-inactive scope, which is useful beyond annotations.

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

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

Two sentences, front-loaded with the action and then the use case. No redundant information.

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

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

Given the simplicity, complete schema, and clear annotations, the description provides all necessary context. It also lists return fields in the absence of an 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?

The input schema fully describes the only parameter `include_inactive` with 100% coverage. The description doesn't add parameter details, but that's acceptable since the schema is complete.

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

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

The description clearly states it lists the caller's active subscriptions, with a specific verb and resource. It distinguishes from siblings by focusing on listing existing subscriptions rather than creating or canceling them.

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

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

The description explicitly tells when to use it: to review current monitoring before adding more or to find an id to cancel. This provides clear guidance for both subscribe and unsubscribe contexts.

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?

Goes well beyond the sparse annotations by disclosing rate limiting ('5 per identifier per day'), the claim_token mechanism for unauthenticated feedback, that it's free and doesn't count against quota, and that the team reads digests daily. No contradictions with annotations.

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

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

The description is long but richly informative. It front-loads the purpose and usage, then details the claim_token behavior. A few sentences like 'The team reads digests daily and signal directly affects roadmap' are motivational rather than essential, but they don't significantly harm clarity.

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

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

For a feedback tool with no output schema, the description covers all necessary context: when to use, what to include, what to expect (claim_token), restrictions (rate limit, scope), and the feedback categories. It also clarifies the 'other' type is valid via the schema, and the context object is explained.

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 extra meaning by explaining the claim_token usage pattern ('pass it back later... to read whether it was fixed') and by giving guidance on message content ('don't paste the end-user's prompt'). This pushes it 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 states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team), the action (tell), and the categories (bug, feature, data_gap, praise), which distinguishes it from all sibling research/query tools.

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

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

Provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and a critical when-not-to-use exclusion: 'if the tool came from a different MCP server... file it with that server instead.' Also explains how to use claim_token to retrieve status later, covering the full usage lifecycle.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This goes beyond the annotations by explaining data provenance, privacy, and caching behavior.

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

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

The description is front-loaded with the main purpose, then provides use cases, and ends with operational details. Each sentence earns its place; no filler or redundancy. Length is appropriate for the tool's complexity.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is highly complete. It covers purpose, concrete return values (top tools, packs, volume), use cases, data source, privacy, and caching. The agent has everything needed 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% and the schema description already explains window semantics ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description repeats this but does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states exactly what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This is a specific verb+resource (returns trending aggregates) and clearly distinguishes it from siblings like discover_tools or ask_pipeworx by focusing on aggregate usage signal.

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 'Useful for' scenarios: discovering hot data sources, confirming canonical tools, and checking alignment with typical agent needs. This gives clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternative tools.

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

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

The description discloses many behavioral traits beyond the annotations: internal steps (walks child markets, computes partition sum), filters (semantic similarity ≥0.30, placeholder fraction >20% returns null), and trade guidance (deviations >3pp emit BUY/SELL EVERY LEG signal; fill check prices against live depth). It clearly states that when realizable_edge_pp ≤ 0, the opportunity is not tradeable. No contradiction with the readOnly/idempotent/openWorld annotations.

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

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

The description is long but densely packed with non-redundant information. It is structured with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose and default behavior. Every sentence contributes critical operational or safety details, so the length is justified for the tool's complexity.

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

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

With no output schema, the description fully explains return values: opportunities[] with fields, partition_check object in event mode, and additional fields like skipped_low_similarity and thin_legs. It also covers edge cases (placeholder slugs, thin book legs, realizable edge ≤ 0) and distinguishes itself from sibling tools like polymarket_fill_risk. This is complete for the tool's moderate complexity.

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

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

Although schema coverage is 100%, the description adds substantial meaning: it gives concrete examples of event slugs and topic seed questions, explains the behavioral difference between event and topic modes, and clarifies that full URLs are accepted. It also documents the no-arg default (trending_scan), which isn't in the schema. This far exceeds the baseline for schema-covered 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 mechanism: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from sibling tools (e.g., polymarket_edges, polymarket_fill_risk) by naming the unique arbitrage detection methods and listing distinct modes (trending_scan, event, topic).

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

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

Provides explicit when-to-use guidance: call with no args for trending_scan, pass event for a specific market (recommended), or topic for cross-event scanning. It also names an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk') and warns when not to trade (if realizable_edge_pp ≤ 0). This is far beyond a basic usage hint.

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 read-only, open-world, idempotent, and non-destructive. The description adds extensive behavioral context: 1h KV caching, output response structure, diagnostics funnel counters, 24h-move warnings, slippage assumptions, and model-family specifics. No contradictions found.

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

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

The description is extremely long (500+ words) and includes unnecessary granular details like per-sport alpha values, historical Run 8 gates, and model internals. While well-structured, it is over-specified and would benefit from trimming to the essentials for agent decision-making.

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 fully defining top-level response fields (by_segment, fed_candidates, _diagnostics) and explaining why segments may be empty. It also covers caching, knobs, and edge cases comprehensively, making it complete for a complex 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 covers all 9 parameters with descriptions, so baseline is 3. The description adds value by grouping tradeable-edge knobs and explaining min_partition_leg_kelly's special behavior (parent-level Kelly always 0), which is not obvious from the schema alone.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees; it also frames it for discovering bets without paging hundreds of markets. However, it does not explicitly distinguish itself from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 clear usage context ('what should I bet on today') and describes tradeable-edge knobs. It also notes that Fed bets are excluded from ranking because the signal is unreliable, which is a when-not-to-rely hint. No explicit alternatives are named for other scenarios.

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

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

The description goes far beyond the annotations. It details response semantics (tracked, expired, snapshot_dates), explains the sign convention of edge_pp_net (negative = SELL YES), the cache-miss snapshot gaps, the 60-day TTL limit, and that decay is computed from daily closes. This substantially enriches the agent's understanding of the tool's behavior and data 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?

Though lengthy, the description is exceptionally well-organized: it leads with a clear purpose, then uses labeled sections (Args, RESPONSE, LIMITS) for parameters, response structure, and caveats. Every sentence carries valuable information, and the formatting makes it easy for an agent to parse.

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

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

Given the tool's complexity (multi-snapshot time-series, trend classification, decay) and the lack of an output schema, the description does an outstanding job of explaining the full response contract: tracked[], expired[] with lifespan_days, snapshot_dates[], and all operational limits (TTL, daily closes, gaps). No crucial aspect is left unaddressed.

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

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

Schema description coverage is 100% and the parameter descriptions in the schema are already informative. The description's Args section largely repeats the schema (e.g., days lookback default 14, max 30; window family default 1wk). It does not add significant new meaning beyond the schema, 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 opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers the core question 'how long has this edge existed and is it shrinking?' It distinguishes itself from the sibling polymarket_edges by framing the edge's age and decay, not just its current value.

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

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

The description provides clear context on when to use the tool: when you need to know edge persistence and decay. It explains the trade-relevance of age ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternatives or state when not to use it, but the purpose and relationship to polymarket_edges is strongly implied. The LIMITS section also adds practical usage constraints.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds enormous behavioral detail: ladder walking, returned verdicts, basket leg analysis, forced_directional_risk, and max_clean_notional_usd. There is no contradiction with annotations.

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

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

The description is long but every segment earns its place: mode guidance, return fields, parameters, and a concrete usage warning. It is front-loaded with the core purpose and structured with clear mode headers, making it dense yet scannable.

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

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

Despite no output schema, the description enumerates all relevant return fields for both modes, clarifies size semantics, and warns about partial fill risk—making it sufficient 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%, but the description adds semantic meaning beyond the schema: it explains that market/event select modes, side defaults differ by mode ('default auto — sell if partition sum > 1, buy if < 1'), and size_usd means 'spend' vs 'proceeds' vs 'settlement notional' depending on mode.

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 ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly defines two modes (single-market and basket). It distinguishes itself from sibling tools by explicitly referencing polymarket_arbitrage and polymarket_edges as the tools this one preflights.

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 states an explicit trigger: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also names the alternative tools and explains the failure mode (unhedged directional position) that justifies using this check.

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 explaining the compatibility_warning trigger conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It also explicitly warns that pre-mapped topics are not necessarily tradeable, which is valuable behavioral disclosure.

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 typical but is front-loaded with the core purpose and then structured into clearly labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence contributes either operational guidance or important caveats; there is no filler or tautology.

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

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

Given the tool has no output schema, the description compensates thoroughly by specifying the response contents (leg-by-leg prices, top_spreads_pp), the semantics of compatibility_warning, temporal_alignment, and skipped counters. It also sets realistic expectations about the rarity of tradeable spreads, making it fully contextualized for an agent.

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

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

The schema already describes all three parameters with 100% coverage, and the description adds meaningful operational context: it lists the topic shortcuts, explains overriding behavior, and ties the parameters to the two modes. This adds value over the raw schema without being redundant.

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 first sentence states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' using a specific verb and resource pair. It clearly distinguishes itself from siblings by focusing on the two-venue comparison rather than a single-venue edge tool.

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 lays out two invocation modes ('topic' and explicit ticker/slug) and gives concrete context for when the tool is appropriate (equivalent bet shapes) and when it is not (compatibility_warning conditions). It does not name alternative sibling tools, but it provides enough guidance on when to use this tool and when its results are meaningless.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds valuable behavioral context by explaining the identifier scoping (anonymous IP, BYO key hash, or account ID) and the list-all-keys behavior when the key is omitted, which goes beyond the annotations.

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

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

The description is concise and front-loaded with the core action. Each sentence adds value: the retrieval/list action, usage context, scoping detail, and pairing with sibling tools. There is 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 description covers the main functionality, optional behavior, scoping, and related tools. Since there is no output schema, it implies the return value (the stored value or list of keys) without spelling out format, which is sufficient for this simple 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 description coverage is 100% for the single 'key' parameter, with the schema already explaining 'omit to list all keys'. The description repeats this behavior without adding additional parameter-level details, so it does not meaningfully augment the schema.

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

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

The description uses specific verbs ('retrieve', 'list') and a specific resource (saved memory), and it distinguishes the tool from siblings by explicitly naming the paired tools 'remember' and 'forget'. It also clarifies the optional key behavior, making the purpose unmistakable.

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

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

The description explicitly states when to use the tool ('Use to look up context the agent stored earlier') and gives concrete examples. It also mentions the pairing with 'remember' to save and 'forget' to delete, effectively covering alternatives and context.

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

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

The annotations already declare readOnlyHint=true, idempotent, and non-destructive, lowering the burden. The description adds valuable behavioral nuance: it discloses the return payload fields, the mark_read side effect that affects future calls, and the external mirror feed. This goes beyond the annotations without contradicting them; the mark_read side effect is clearly described and consistent with the 'openWorldHint'.

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 primary action, and each sentence earns its place: purpose, return payload, filtering, state flag, polling, and alternative endpoint. There is no filler or repetition.

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

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

For a tool with 5 optional parameters and no output schema, the description is quite complete. It explains the return format, filtering semantics, state mutation via mark_read, polling suitability, and even provides an external URL for scripts/dashboards. This gives the agent enough context to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by giving an example for type ('sec_8k') and explaining the behavior of mark_read ('so the next call only shows newer ones'). This is more than the schema provides, though it does not add detail for limit or unread_only.

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 'Pull fired events from your subscription feed,' which is a specific verb+resource+scope. It also describes filter options and return payload details. While it doesn't explicitly distinguish from sibling tools like list_subscriptions or recent_changes, the resource and behavior are clear enough to infer 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 provides clear usage context: filtering by type and/or since, mark_read semantics for paging, and that polling is acceptable. It also mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or name a specific sibling alternative.

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

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

Annotations already mark readOnlyHint and idempotentHint, but the description adds substantial behavioral context: fans out to SEC EDGAR, GDELT→GNews with fallback rules, USPTO soft-fail due to API sunset, and the return structure (changes[], total_changes, citation URIs). No contradiction with annotations.

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

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

The description is long but every sentence earns its place: query patterns, source fan-out, fallback logic, output shape, and sibling differentiation. It is well-structured and free of filler or repetition.

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

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

With no output schema, the description thoroughly explains return values and source-specific behavior, including fallbacks and soft-fail. It covers parameters, behavior, and alternatives, making it fully self-contained for the agent.

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

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

Schema coverage is 100%, so the schema already documents parameters well. The description adds value by giving concrete examples for `since` ('2026-04-01', '7d', '30d'), clarifying `value` accepts ticker or CIK, and noting `type` only supports 'company'.

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

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

The description explicitly identifies the tool as a change feed for a company over a time window, with concrete example queries ('What's new with X', 'updates on Acme'). It clearly distinguishes itself from the sibling entity_profile by contrasting dynamic changes vs. static 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?

Provides explicit usage context: 'change feed for a company in the last N days/weeks/months' and gives practical guidance on `since` values ('Use "30d" or "1m" for typical monitoring'). It also names an alternative tool: 'Use entity_profile instead when you want the static profile...', clarifying when not to use this tool.

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

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

Annotations already signal read/write and idempotency. The description adds valuable context: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours' and 'scoped by your identifier'. These go beyond the structured annotations.

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

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

Four sentences, each earning its place: purpose, trigger, persistence behavior, and companion-tool integration. Front-loaded and free of 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 two-parameter write tool, the description fully covers purpose, usage context, data persistence, scoping, and lifecycle via recall/forget. No output schema is needed, and annotations cover idempotency and destructive safety.

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

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

Input schema has 100% coverage with descriptive parameter names, examples, and value guidance. The description reinforces key-value semantics but does not add meaning beyond what the schema already provides.

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

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

Description opens with 'Save data the agent will need to reuse later', clearly stating the verb and resource. It also distinguishes itself from siblings by noting 'Pair with recall to retrieve later, forget to delete', making the tool's role in the memory triad unambiguous.

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

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

Provides explicit trigger conditions: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject)'. It does not spell out when-not-to-use, but references to recall and forget give clear guidance on 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 readOnly, openWorld, idempotent, and non-destructive. Description adds valuable context beyond annotations: LEI/FIGI enrichment degrades gracefully with partial results, unresolved identifiers are explicitly listed, and the internal multi-endpoint cascade replaces manual lookups. No contradictions.

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

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

Description is lengthy but every sentence adds value. It is front-loaded with user-facing examples and the 'Use FIRST' directive. Some repetition in type details could be tightened, but structure is logical and informative.

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

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

Given the complexity of two entity types with multiple sub-sources, the description is fully complete. Despite no output schema, it explains what identifiers will be returned, how unsuccessful lookups are communicated (unresolved list), and addresses edge cases like graceful degradation and non-US entities. No gaps.

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

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

Schema coverage is 100% with clear parameter descriptions. The description significantly enriches semantics by detailing what each type resolves to (e.g., company yields CIK, ticker, LEI, FIGI with source labels; drug yields RxCUI and ingredient) and explains input formats like ISIN-to-LEI mapping. Aids agent understanding beyond schema.

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

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

Description clearly states the tool resolves names to canonical/official identifiers, with explicit examples of natural language queries. It distinguishes itself from siblings like compare_entities and entity_profile by being the primary lookup tool, reinforced by 'Use FIRST whenever you have a name but need an ID.'

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

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

Provides clear guidance on when to use ('Use FIRST whenever you have a name but need an ID') and gives specific query patterns. Could be improved by explicitly stating when not to use (e.g., if you already have an identifier), but overall context is strong.

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 safety is covered. The description adds transparency by explaining the internal mechanism ('Probes each entity with ai_visibility_check'), the ranking behavior, and the return contents ('ranked list with score, confidence, signal density'). This goes beyond the annotations without contradicting them.

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

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

Three sentences, front-loaded with the main purpose, followed by mechanism + usage context, and ending with output description. Every sentence earns its place; 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?

Given the tool's moderate complexity and no output schema, the description covers purpose, process, usage scenario, and key return fields. It doesn't describe how to interpret scores or edge cases, nor does it explicitly address alternatives like 'compare_entities', but it provides sufficient context for an AI 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 description coverage is 100%, so every parameter (entities, models, _apiKey, context) has a description in the schema. The description adds minimal new parameter semantics—it reinforces that entities are 'your brand + N competitors' and mentions the output fields, but doesn't detail parameter formats or dependencies beyond what the schema already provides. Thus baseline 3 is appropriate.

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

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

The description clearly states the action ('Compare AI visibility across multiple entities side-by-side'), names the resource (entities/brands), and specifies the goal (competitive AI-marketing audit). It distinguishes itself from the sibling tool 'ai_visibility_check' by explicitly mentioning it probes multiple entities and references the sub-tool, and from generic tools like 'compare_entities' by focusing on AI visibility.

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 concrete usage context: 'Useful for competitive AI-marketing audits' and 'does Claude know about us as well as our competitors?'. It implies when to use this over the single-entity 'ai_visibility_check' (when comparing multiple entities), but does not explicitly name alternatives or state exclusions, so it falls short of a 5.

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

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

Annotations already mark it read-only and idempotent, but the description goes further by disclosing the fan-out behavior across external services, the specific return fields, and the graceful degradation of partial failures. It even mentions a 5-30s latency for first-time bundlephobia measurements and how sources_failed will report timeouts, which is highly valuable beyond the annotations.

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

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

The description is dense but highly structured, leading with the core composite purpose, then usage, return values, and failure behavior. Every sentence adds value; there is no filler or redundancy. It is appropriately sized for the tool's complexity.

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

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

Given there is no output schema, the description fully covers the return format: summary block fields, per-advisory detail, links, and alternative versions. It also explains the partial failure behavior and ecosystem scope. The tool's complexity is well-served by this complete description.

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

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

Schema description coverage is 100% for both parameters (package and version), so the schema already documents them thoroughly. The description adds no extra parameter-level detail; it mentions npm ecosystem but that's already in the package description. 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 what the tool does: a composite 'should I add this npm package' check, fanning out to deps.dev and bundlephobia. It specifies the exact data points (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support), making it distinct from any sibling tool. The purpose is immediately obvious.

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 when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives a when-not by stating 'NPM ecosystem only in v1' and directs non-NPM users to 'deps.dev:version directly', offering a clear 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description details the algorithm (BGE-base-en embeddings, cosine over 500-char windows), the 200K char cap with truncation flagging, and the presence of offsets for verification. This gives the agent rich behavioral insight beyond what annotations convey.

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

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

The description is four sentences, each substantive: function, use case, integration, and technical details. It is front-loaded with the core purpose and wastes no words, though it is slightly denser than the two-sentence ideal.

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 no output schema, but the description adequately explains return values (passages with offsets and similarity scores), behavior on long inputs (truncation flagged), and how it fits with the sibling tool ask_pipeworx_grounded. With complete schema coverage and annotations, nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description essentially echoes the schema ('text you already pulled', 'natural-language query') without adding new parameter meaning. It does clarify the return format, but that's not parameter-specific.

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' – a specific verb, resource, and scope. It clearly distinguishes itself from siblings by noting it returns 'top-N passages with character offsets and similarity scores' and explicitly mentions pairing with ask_pipeworx_grounded, so an agent can differentiate it from other search/grounding tools.

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

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

It provides a clear usage condition: 'Use when the record is too big to cram into the prompt' and names an alternative: 'Pairs with ask_pipeworx_grounded'. However, it doesn't explicitly state when-not to use it (e.g., for small records), which would have made it a 5.

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

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

The description adds substantial context beyond annotations: account requirements, per-type parameter examples, and delivery constraints (SMS phone verification and 10/day cap). While annotations indicate idempotency, the description doesn't clarify how repeated identical subscriptions behave, but it doesn't contradict the annotations either.

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 clause carries distinct information about purpose, requirements, types, and delivery. It is a single run-on sentence, making it slightly less scannable, but there is no wasted verbiage given the tool's complexity.

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

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

It covers the core purpose, preconditions, type examples, and delivery options, and plainly states the return value (subscription id). Webhook delivery is not mentioned in the prose, but the schema documents it extensively. Given the rich schema and annotations, this is a solid, near-complete 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, but the description enriches parameters with concrete examples (e.g., items:['5.02'] = officer change) and delivery behaviors (email/SMS). It omits patent_grant and clinical_trial from the prose, but the schema covers them fully, so the added examples still raise the 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 opens with 'Create a proactive monitoring subscription to a live-data event stream' and specifies 'Returns the new subscription id,' clearly stating a create operation. This distinguishes it from sibling tools like list_subscriptions and unsubscribe, which are about managing existing subscriptions.

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

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

It provides explicit preconditions ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)') and an alternative for retrieval ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). It also implies when to use it (for persistent monitoring) versus pulling on demand, with clear when-not conditions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by explaining that output is category-bucketed example questions with exact tool+argument shapes, and that it draws from a live catalog. This goes beyond structured data 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 longer than average but well-structured, starting with user-phrasing examples and moving to purpose, behavior, and usage. Each sentence provides useful information, though a slight tightening could improve it.

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

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

For a single-optional-param tool with no output schema and strong annotations, the description is complete. It covers what the tool does, how to call it, what to expect (category-bucketed examples with tool+argument shapes), and when to use it. No critical gaps.

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

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

The schema description coverage is 100%, so the baseline is 3. The description enriches the topic parameter with examples ('finance', 'pharma', 'betting') and clarifies optionality (omit for full spread), adding meaning beyond the schema's enum-less description.

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

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

The description clearly identifies the tool as the onboarding entry point for Pipeworx, with specific verbs ('returns category-bucketed example questions') and a resource ('live catalog of thousands of tools'). It distinguishes itself from siblings like discover_tools by emphasizing question suggestion and meta-tool education.

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

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

It explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning meta-tools. However, it does not explicitly mention when not to use it or name alternative tools, so it misses the full 'when-not/alternatives' bar.

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 non-read-only, non-destructive, idempotent behavior. The description adds valuable context: ownership enforcement ('only cancel your own subscriptions') and the soft-delete mechanism ('deactivated not deleted'). This explains why destructiveHint is false and gives insight into side effects and data retention 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 (3 sentences) and front-loaded with the core action. Each subsequent sentence adds a necessary behavioral detail (ownership enforcement, soft-delete) without waste or fluff.

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

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

For a simple one-parameter tool with no output schema, the description covers the key aspects: what it does, who can use it, side effects (deactivation vs deletion), and downstream availability via recent_alerts. Combined with rich annotations (idempotent, non-destructive), it is complete for its scope.

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: it identifies the id as a uuid returned by subscribe. The description adds no additional parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes from siblings like subscribe (creation) and list_subscriptions (listing) by focusing on cancellation. Additional details about ownership and soft-delete further clarify 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?

Clear context is provided: you cancel a subscription by id, and you can only cancel your own. The soft-delete note mentions historical events remain available via recent_alerts, giving a hint of complementary tooling. However, it does not explicitly state when not to use this tool or name alternatives like list_subscriptions for finding a subscription id.

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 note readOnly/idempotent/openWorld, and the description adds critical behavior beyond that: the exact meaning of could_not_verify (check failed, not evidence) and unsupported (no source covered), plus the two execution paths (SEC EDGAR fast path vs. grounded pipeline). The warning to never show could_not_verify as evidence is essential and goes far beyond the annotation 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 a bit long but well-structured: it starts with trigger phrases and a one-sentence purpose, then covers routing, return values, and an important caller warning. Each sentence contributes meaningful detail. It could be slightly tighter, but the density is justified by the tool's complexity.

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

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

With no output schema, the description compensates by enumerating the verdict set (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify) and stating the return components (actual value with citation, reasoning). It also clarifies error semantics and routing. It does not fully outline the exact response JSON structure, but the provided detail is sufficient for an agent to interpret the result.

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 claim and tolerance_pct clearly with coverage of 100%. The description adds extra value by explaining how tolerance_pct overrides the wording-implied default, caps at 5, and recommends 1–2 for hallucination detection. This goes beyond the schema's basic type/description, effectively guiding parameter use.

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 natural-language claim verification against authoritative sources, with explicit trigger phrases and a defined output (verdict + evidence). It distinguishes itself from siblings by focusing on fact-checking with verdicts like confirmed/refuted, and by noting it replaces multiple sequential calls (NL parsing → entity resolution → data lookup → 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and explains the routing logic for company-financial vs. other claims. It does not name specific alternative tools, but the note about replacing 4–6 sequential calls gives guidance to prefer this tool over composing multiple steps. Missing explicit exclusions or named alternatives, so not a 5.

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