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 declare readOnly, openWorld, idempotent, and non-destructive hints; the description adds valuable behavioral context by revealing that it routes to other tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. No contradiction between description and annotations exists.

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

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

The description is front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and then supplies domains, triggers, examples, and output behavior. It is somewhat list-heavy and the final breaking-news clause feels tacked on, but it remains organized and useful.

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 covers what the tool does, when to use it, what domains it serves, how it behaves as a router, and what returns. For a broadly scoped natural-language tool, this is complete enough for an agent to select and invoke it correctly.

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

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

All six parameters are documented in the schema as aliases for 'question', so schea coverage is 100%. The description adds little parameter-level detail beyond saying the tool accepts natural-language questions, keeping this at 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 defines the tool as a natural-language question router that sends queries to thousands of verified source tools and returns structured answers with citations. It is well differentiated from web search, but it does not distinguish itself from the closely named siblings ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

The description explicitly says to prefer this tool over web search for factual questions, gives trigger phrases like 'what is', 'look up', and 'get the latest', and provides concrete examples. It also says 'START HERE for most questions'. However, it does not explain when a sibling like ask_pipeworx_grounded or ask_pipeworx_beta would be the better choice.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral context: beta status, live candidate routing improvements only when under test, the current lack of an active candidate, and the experimental nature. It does not contradict the annotations, though it could say more about possible behavior differences while a candidate is active.

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 organized and front-loaded with the beta distinction, then gives current status, usage guidance, and a clarifying statement about fallback. It is slightly repetitive (for example, 'identical universal router', 'currently matches ask_pipeworx exactly', and 'Falls back to nothing — this IS a full working router' restate similar points), but it remains purposeful and readable.

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-required-parameter tool with full schema coverage and safety annotations, the description is largely complete: it explains what the tool is, how to use it, the current behavior, and the experimental context. The absence of an output schema is mitigated by noting the identical response shape to ask_pipeworx, although some specifics of that response are left to the sibling reference.

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 required parameter is the simple 'question' field. The description notes that arguments are identical to ask_pipeworx, but beyond that it does not add new semantic detail about the parameters. Baseline 3 is appropriate since the schema does the necessary documentation work.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx, an identical universal router serving the same 5,798 tools with the same arguments and response shape. It uses a specific verb/resource and distinguishes the tool from the stable sibling by emphasizing the experimental routing edge.

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 this tool: 'when you want the newest routing,' and contrasts it with the stable router whose results are used for comparisons. It also clarifies the current state (no active candidate, so it matches ask_pipeworx exactly) and that it is a fully functioning router, not a degraded fallback.

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

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

Annotations already declare readOnly, openWorld, and idempotent behavior. The description goes well beyond this by detailing the internal routing, the strict extraction rule, the exact success response shape, and the full refusal_reason enumeration. There is 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 every sentence earns its place: purpose, routing behavior, output contract, refusal contract, usage guidance, and cost tradeoff are all covered without redundancy. The critical distinguishing information is front-loaded.

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

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

With no output schema present, the description supplies the return shape for both success and refusal paths, lists all refusal reasons, and explains cost and intended use. This is complete enough for an agent to correctly select and call the tool without needing additional context.

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

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

Schema description coverage is 100%: the schema already documents the 'question' parameter and all aliases. The description does not add much parameter-level detail, but it doesn't need to. Baseline 3 is appropriate because the schema carries the full parameter documentation burden.

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 a hallucination-resistant answer mode for high-stakes reads, and explicitly contrasts itself with ask_pipeworx. It states the verb (extract answers from tool results), the resource (Pipeworx grounded answers), and the key differentiating behavior: using only the tool result content.

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

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

The description gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on, especially for financial, legal, medical, or public-statement contexts. It also gives an explicit exclusion: prefer ask_pipeworx for casual lookups, and notes the extra LLM call cost as a decision factor.

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?

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already cover the safety profile, and the description adds substantial behavior beyond them: account/tier gating (thorough requires paid plan), grounding guarantees (never invents, explicit gaps[] for unanswered facets), latency windows (15-60s, thorough ~90s), contradictions[] for standard/thorough, semantic excerpting 'not head-truncated', and a fetchability guarantee for citation_uri. Consistently aligned with annotations; no contradiction.

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

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

Front-loaded with the most operationally critical facts (account requirement, fallback tool, latency) and every sentence carries distinct information. However, the body contains clear corruption and duplication — the 'Grounded multi-source research... ask_pipeworx instead' block appears twice and there are garbled fragments (e 'one (NE', 'BREAKING') that an agent must wade through. The length is largely earned, but the textual flaws are real.

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

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

With no output schema, the description carries full responsibility for explaining return values — and it does: findings packet (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), gaps[], contradictions[], hop field, and citation fetchability. Auth requirements, tier differences, failure behavior, and latency are all covered. Nothing agent-critical is missing for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: the paid-plan gate on depth:'thorough', the facet-count semantics (quick=3, standard=3, thorough=6) and the hop/gap-recovery behavior per tier. This is value the enum descriptions alone cannot convey.

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

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

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call'. Explicitly differentiates itself from open-web search ('this is NOT open-web search') and from sibling ask_pipeworx (single lookup). An agent can tell exactly what this tool does and what it is not.

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?

Gives explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx instead'), and a precondition exclusion ('If you are not signed in, use ask_pipeworx instead — it works on every tier'). The routing to the correct alternative is unambiguous.

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

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

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?

The description richly discloses behavior beyond the annotations: it fans out across multiple sources in parallel, explains soft-failure for patents, clarifies that an empty section means real 'no data', specifies GDELT→GNews fallback, and details resolved:false for private companies. No contradiction with the read-only/idempotent 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 information-dense; nearly every clause serves a purpose given the tool's complexity. It is front-loaded with query examples and the key 'ALWAYS PREFER' directive, though the single-paragraph structure could benefit from bullets to aid scannability.

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 must carry the burden of explaining return shape. It does so thoroughly: lists each returned field, describes expected empty sections, documents source fallbacks, and covers edge cases like private companies and interchangeable type values. An agent has enough context to call and interpret this 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 already documents the 'company'/'ticker' interchangeability and acceptable value forms. The description adds meaning by explaining zero-padded CIK format, SEC EDGAR company-name resolution, and the resolved:false behavior for private companies, going beyond the 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 description clearly states a specific verb + resource: building a 'full cross-source profile of a US public company' in one parallel call, supported by concrete query examples. It distinguishes itself from chaining single-pack lookups, but it does not explicitly differentiate from sibling tools like compare_entities or resolve_entity, so it stops short of a 5.

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

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

The description explicitly says it should be 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This is an unambiguous when-to-use directive, and it explains what input shapes are accepted and how private-company cases are handled.

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?

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds extensive behavioral detail: compatibility_warning/codes can be non-empty even when pairs are returned, legs with 'unknown' metric_type are never paired, spreads are gross not net, temporal_alignment null does not mean aligned. This is exactly the kind of nuanced context that annotations cannot convey, and nothing contradicts the read-only 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 long and dense, but it is organized with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS, codes list) and front-loaded with the core definition. Every sentence conveys a distinct fact relevant to correct invocation and interpretation. It could be tightened, but the length is justified by the tool's complexity and the absence of an output schema.

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 carries the burden of explaining return values, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, flags[], compatibility_codes[], temporal_alignment, fees_note, and skipped counter semantics. It also covers failure modes and interpretation cautions, leaving no critical gap for an agent deciding whether and how to call this 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 already covers all 3 parameters at 100%, including override behavior, so the baseline is 3. The description adds value by grouping them into the two modes, explaining that the topic list is pre-mapped, and clarifying that both modes produce identical disclosures. This goes beyond what the schema alone provides, though the marginal gain is modest.

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?

Opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' — a specific verb/object pair that immediately defines the tool's function. It is clearly distinct from sibling tools like polymarket_arbitrage by emphasizing cross-venue comparison of equivalent outcomes on two named platforms.

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 documents TWO MODES (topic shortcuts vs explicit ticker/slug pairings) and explains that both modes run the identical matcher. It also sets expectations that pre-mapped topics often return compatibility_warning and are 'pre-mapped ≠ tradeable,' which guides correct use. However, it does not name specific sibling alternatives or state explicit 'use X instead' conditions.

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

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

Annotations already declare readOnlyHint, 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 mark this as read-only/idempotent, and the description adds substantial behavioral context: internal cascade of multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` field, `figi_candidates` when ambiguous, and label provenance per identifier. No contradiction with annotations.

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

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

The description is long but front-loaded and dense with actionable details; every sentence contributes. The structure moves from purpose to supported types to edge-case warnings, making it navigable despite length. Minor redundancy (e.g., repeating 'what's the ID' variants) prevents a perfect 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?

For a tool with no output schema, the description fully covers expected returns: which identifiers are produced, how ambiguity and failures are represented (`figi_candidates`, `unresolved`), and input formats. It also covers edge cases like non-equity instruments and non-US issuers, making the tool safe to invoke without external knowledge.

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

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

Schema covers 100% of parameters, and the description goes further by disambiguating the `value` parameter: warns against passing full noun phrases for bonds and gives concrete formatting rules (e.g., 'NEW YORK ST DORM AUTH' vs trailing security-class words). This adds semantic value well beyond the schema's short 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 opens with concrete user-phrase examples and states the core purpose: resolve a user-spoken NAME to canonical/official identifiers. It clearly distinguishes from siblings by positioning itself as the prerequisite lookup tool ('other tools require as input') and enumerates supported types (company, drug) with explicit identifier outputs.

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 'Use FIRST whenever you have a name but need an ID', giving an unambiguous trigger condition. It also includes when-not guidance for bond lookups (pass issuer exactly as printed, not the full noun phrase) and explains graceful degradation when enrichment sources fail, preventing misuse.

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.