Datalastic

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 valuable context beyond annotations: it specifies that calling Anthropic requires the user's own API key and that the user pays Anthropic directly for those calls. It also discloses the return structure ('per-model {score, confidence, signals, raw_response} + a combined view'). This gives the agent a clear picture of external side effects and outputs.

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

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

The description is three sentences, each earning its place: the first explains what the tool does, the second covers models and costs, and the third lists return format and use cases. It is front-loaded with the core purpose and avoids redundant fluff. No unnecessary details or repetition of the 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 appropriately explains the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). It also covers the main parameters and their interplay (models list, _apiKey). The only minor gap is that 'signals' is not fully defined, and there is no detail on interpreting the score, but for a tool of this complexity the description is sufficient.

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

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

The input schema has 100% description coverage, so every parameter is already documented. The description goes further by clarifying the value ranges for `models` ('workers-ai' free default, 'anthropic') and explaining why `_apiKey` is needed (only when Anthropic is included). It also gives concrete entity examples ('Pipeworx', 'OpenInvoice') that illustrate expected input, adding value beyond the schema's generic 'brand/business name'.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This uses a specific verb ('probe') and names the resource (LLMs) and the outcome (visibility scores). It distinguishes itself from sibling tools like ask_pipeworx or deep_research by focusing on measuring model awareness rather than answering questions or conducting research.

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

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

The description provides clear usage context: default model is free ('Workers AI Llama-3.3-70b (free)'), when to supply an Anthropic key ('pass `_apiKey` to also probe Anthropic'), and example use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'). It does not explicitly state when not to use it or name alternative tools, but the context is sufficient for an agent to decide appropriately.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior; the description enriches that with specifics: it fills arguments automatically, works on every tier, makes one fast call, and returns 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 longer than typical but front-loads the critical guidance ('PREFER OVER WEB SEARCH') and each sentence contributes value (scope, examples, alternatives, tier compatibility). Slight redundancy between the initial directive and the later 'START HERE' phrase, but overall well-structured and skimmable.

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 thoroughly explains return value (structured answer with citations), when to use, when not to use (step up to siblings), and scope (factual/current data across many domains). It even covers edge cases like breaking news, making the context remarkably complete.

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

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

Schema coverage is 100%, so the parameter semantics are fully documented in the schema (question with five aliases). The description adds no param-level details but includes applicable examples that illustrate usage, which is a minor bonus.

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

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

The description clearly states the tool routes questions to the appropriate one of 5,564 tools across 1,462 sources and returns structured answers with stable pipeworx:// citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its scope unmistakable.

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

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

Explicitly instructs to prefer over web search for factual/current-data questions and provides trigger phrases ('what is', 'look up', 'find') and concrete examples. Clearly explains when to step up to ask_pipeworx_grounded (hallucination-resistant single answer) or deep_research (broad/multi-part questions), and offers guidance for breaking-news queries.

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 beyond annotations by explaining the beta nature: candidate routing improvements are enabled live whenever under test, currently none are active so it matches ask_pipeworx exactly, and it 'falls back to nothing' as a full working router. This adds valuable context about the tool's experimental status and behavioral equivalence.

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 yet information-dense, covering purpose, current state, usage, and relationship to ask_pipeworx in just four sentences. Every sentence earns its place without fluff, and the key point (beta version) 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?

For a beta variant with no output schema, the description fully covers the tool's complex nature: it explains the experimental routing, current state (no active candidate), usage equivalence, and that it's a complete working router. It also references the same response shape, so no behavioral gaps remain.

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

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

The schema fully documents all 6 parameters (aliases for 'question'), so the description adds no new parameter-level semantics. Baseline 3 is appropriate because the schema covers 100% of parameters and the description's only reference is 'same arguments,' which doesn't add meaning beyond the schema.

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

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

The description clearly identifies the tool as 'Beta version of ask_pipeworx' with a specific function: a universal router with 5,564 tools and same arguments/response shape. It distinguishes itself from the stable ask_pipeworx by noting it's the experimental edge with candidate routing improvements, making the purpose immediately clear.

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 it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. This gives clear when-to-use guidance. It could be stronger if it explicitly stated when NOT to use it (e.g., in production), but the context is adequate.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations, disclosing the exact refusal reasons, the structured return shape, and the guarantee that answers use ONLY tool results. This is rich behavioral context that helps an agent trust and interpret the outcome.

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, mechanism, output contract, usage boundaries, and cost tradeoff. It is front-loaded with the core statement and maintains a logical flow without fluff.

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

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

Given the tool's complexity and the absence of an output schema, the description fully specifies the return values, refusal modes, and use case boundaries. It also differentiates from the sibling tool, making it self-contained and complete.

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

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

Schema description coverage is 100% (all parameters are aliases for question, fully described). The description adds context about how the question is processed (routing, filling arguments) but does not introduce new parameter-level meaning, so the baseline 3 applies.

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

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

The description opens with a precise purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes this tool from sibling ask_pipeworx by describing the same routing but a more rigorous extraction process with refusal handling, and it names the resource (Pipeworx tools).

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on... prefer ask_pipeworx for casual lookups.' It also names the alternative and explains the cost tradeoff, making the when/when-not decision crystal clear.

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

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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses substantial behavioral detail: resolver contract with match confidence and alternatives, suppression on low-confidence matches, closed-market status handling, illiquidity warnings, news fallback behavior, and cancellation-rule risk. These are critical operational traits not present in the annotations, making the tool safe and predictable to invoke. No contradiction with annotations.

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

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

The description is well-structured with clear headings and a front-loaded first line that states the tool's core purpose. It is long and sometimes redundant (e.g., closed/dead markets discussed twice), but most sentences carry important safety and behavioral detail, so the length is largely justified.

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 explicitly naming response shapes (result.market, result.analysis, result.evidence), status values (low_confidence_match, market_closed_or_inactive), resolver contracts, parent-event extraction, news fallback fields, and cancellation-rule risk. This provides agents with the necessary context to correctly interpret and act on responses.

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 each parameter fully described, so the baseline is 3. The description mainly repeats the market parameter formats (slug, URL, question text) and provides fan-out examples that imply depth/quick behavior, but it does not add new semantic information 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?

The description opens with a specific verb-resource pairing: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from siblings by describing the evidence-packet + market-vs-model comparison, which is distinct from tools like polymarket_edges or validate_claim.

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 use cases are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to invoke the tool, though it does not name alternatives or specify exclusions, so it stops short of a 5.

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

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

Annotations already mark the tool as read-only and idempotent, but the description adds substantial context: parallel execution, per-type data sources (SEC EDGAR/XBRL vs. FAERS/FDA), off-calendar fiscal year handling, sorting by primary metric, and citation URIs. No contradictions with annotations.

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

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

The description is dense and front-loaded with trigger phrases, and every sentence adds meaningful information. However, it is a single run-on paragraph; a bulleted structure would improve scannability without sacrificing content.

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

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

Even without an output schema, the description covers return format (paired data + citation URIs), metric sources per entity type, entity count limits, and sorting behavior. This is complete for the tool's complexity and leaves no critical gaps 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%, but the description goes beyond the schema by explaining what each type ('company' vs 'drug') returns, providing example values, and clarifying output sorting. This gives the agent enough to construct valid calls with confidence.

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

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

The description explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific trigger phrases like 'X vs Y' and 'rank these companies.' This clearly distinguishes it from sibling tools such as entity_profile or sequential lookups.

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

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

The description gives clear context for when to use the tool (comparison queries) and explicitly says to prefer it over sequential single-pack lookups. However, it does not name a specific alternative tool or state when not to use it (e.g., for single-entity lookups).

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, so the safety profile is covered. The description adds behavioral context by specifying that the position is 'live' and enumerating the navigation data provided (current lat/lon, speed, course, heading, destination, status), which goes beyond the schema without contradicting any annotation.

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

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

The description is compact and front-loaded with the essential question ('Where is ship...'), followed by the return payload and a clear example. Every sentence earns its place, with zero fluff.

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

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

For a simple single-vessel lookup tool with no output schema, the description fully covers what it does, what identifiers are accepted, what data is returned, and how to invoke it via the example. It is complete for an agent to select and use 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 the parameters are already well-documented. The description reinforces the alternative identifiers (IMO, MMSI, UUID) and provides an example usage, but it does not add substantive new meaning beyond indicating that at least one identifier is required—which the schema already states.

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

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

The description clearly states the tool's function with a specific verb ('Locate') and resource ('a single vessel'), and distinguishes it from the sibling `datalastic_vessels_in_radius` by emphasizing 'single vessel' and listing the specific AIS fields returned. It also provides a concrete example, 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 implies usage for querying a single vessel by IMO/MMSI/UUID and clearly specifies the data returned (live AIS position, destination, speed, etc.). However, it does not explicitly mention alternatives like `datalastic_vessels_in_radius` or state 'use this when you need one ship, not a set', so it stops short of full exclusion guidance.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds value by disclosing that it returns live AIS positions, the specific fields (name, IMO, MMSI, position, speed, course, destination, type), and the need for an API key ('_apiKey'), which is a behavioral trait not covered by annotations.

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

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

The description is two sentences plus an example, achieving high information density with zero waste. The first sentence states the core purpose, the second lists return fields, and the example anchors the usage. It is well-front-loaded and easy to parse.

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

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

For a read-only, idempotent tool with no output schema, the description adequately explains what it does, what it returns, and how to call it. It does not mention potential radius limits or error handling, but these are not essential for basic usage. The presence of a sibling tool for specific vessels could be referenced, but the description stands on its own.

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

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

The input schema provides 100% coverage with clear descriptions for all four parameters. The description adds an example call that demonstrates the parameter order and values, which is modest additional value beyond the schema, but does not introduce new semantic information for any parameter.

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 begins with a specific verb 'Find' and clearly states the resource: 'vessels within <radius> nm of a lat/lon'. It distinguishes itself from sibling 'datalastic_vessel' by emphasizing 'all ships near a point' and listing return fields, making the tool's scope 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 clearly implies the use case: spatial search for all vessels near a point with live AIS positions. It does not explicitly mention alternatives or exclusions, but the contrast with the singular 'datalastic_vessel' sibling is implicit. The example call provides concrete usage 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 description adds significant behavioral context beyond the annotations. It discloses that it requires an account (paid for thorough), returns gaps[] when data is missing (never invented), performs parallel decomposition, returns contradictions for standard/thorough, and explains the hop field and citation_uri being resolvable. This goes above and beyond the annotations' simple readOnly/openWorld 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 dense and covers many points, but it is still structured in clear sentences and front-loads critical prerequisites (account required). It is on the longer side but each sentence serves a purpose; slight redundancy in citing example use cases could be trimmed, but it remains well-organized.

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

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

Given the tool's complexity (many sources, parallel execution, multiple depth levels), the description covers essential aspects: account tiers, behavior, output format, gaps, contradictions, and timing. No output schema exists, so the description's explanation of return values (findings packet, gaps, citations) is necessary and complete enough for an agent to know what to expect.

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

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

Schema already covers both parameters fully (100% coverage), so baseline is 3. The description adds value by explaining the behavior of each depth level (e.g., 'quick=3 single hop' vs 'standard adds gap-recovery hop'), which is not fully in the schema's enum descriptions. This extra nuance justifies a 4.

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

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

The description clearly states the tool's purpose: grounded multi-source research across Pipeworx's 1462 structured data sources, decomposing questions and routing to 5,564 tools in parallel. It explicitly distinguishes itself from open-web search and sibling 'ask_pipeworx' variants by noting it is not a single LLM call and returns structured findings with citations.

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: 'Best for broad/multi-part questions over structured data' and when-not-to-use: 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also names alternatives (ask_pipeworx) and explains the account requirement and fallback if not signed in. This is exemplary usage guidance.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and emphasizes that results are 'ready to call directly, no second schema lookup needed.' This clarifies the output format and the tool's meta-search purpose 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 four sentences, each earning its place: purpose, when-to-use with domain list, output format, and a prioritization guidance. It is slightly longer than the minimal two-sentence ideal, but the additional sentences deliver distinct, useful information about the tool's behavior and recommended usage.

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 properly explains return values: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also covers the recommended invocation context. It does not address edge cases like no matches or ambiguous queries, but those are not essential for a discovery tool with a rich parameter schema.

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

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

Schema description coverage is 100%, so the schema fully documents all six parameters, including aliases and the limit default. The description adds the example task phrasing ('analyze housing market trends', 'look up FDA drug approvals') but those examples are also present in the schema's examples array. The description does not add meaning 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 a specific verb and resource: 'Find tools by describing the data or task.' It enumerates a broad set of domains (SEC filings, FDA drugs, economic data, etc.) and distinguishes itself as a meta-tool for discovering other tools, especially compared to sibling tools like search_within or validate_claim.

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: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It does not explicitly name alternatives or exclusion criteria, but the 'not just one answer' caveat implies when a single known tool might be more 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, covering safety. The description adds valuable context: it details the parallel fan-out across multiple sources, discloses the USPTO API sunset with soft-fail behavior, and the GDELT→GNews fallback. It does not mention latency or rate-limit implications, but the fallback and sunset disclosures go beyond the annotation baseline.

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

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

The description is dense but well-organized: it starts with user-intent phrases, then states the parallel-call strategy, enumerates sources, and lists the exact return fields. While long, every clause contributes necessary detail for a multi-source tool, and the front-loading with example queries makes it 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?

With no output schema, the description compensates by enumerating all return components: cik, company_name, recent_filings with pipeworx URIs, fundamentals fields, patents, news, and LEI. It also explains source-specific quirks (patents sunset, fallback chain) and input formats. This is unusually complete for a complex, multi-source tool.

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

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

The input schema already provides 100% coverage of both parameters. The description adds concrete examples ('AAPL', '0000320193') and reinforces the constraint that names are not supported, pointing to resolve_entity. This extends beyond the schema's baseline 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 example queries ('Tell me about X', 'research Acme') and explicitly states the core function: 'full cross-source profile of a US public company in ONE parallel call.' This clearly distinguishes it from siblings like compare_entities and resolve_entity.

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

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

Provides explicit guidance with 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and clarifies unsupported input via 'names not supported (use resolve_entity first if you only have a name).' It also lists the data sources and fallback behavior, giving clear when-to-use and alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds little beyond restating deletion; it doesn't disclose details like permanence or error behavior. However, it does specify the use case of clearing sensitive data, which is contextual but not a behavioral trait.

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 every sentence contributes: purpose, usage context, and sibling pairing. No fluff.

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

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

For a simple one-parameter tool with annotations covering safety and idempotency, the description covers purpose and usage. It doesn't mention missing-key behavior, but that's minor given the tool's simplicity.

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

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

Schema coverage is 100% – the 'key' parameter is fully described in the schema. The description only says 'by key', adding no semantic detail beyond what is already structured.

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 'Delete a previously stored memory by key' – a specific verb (delete), resource (memory), and method (by key). It differentiates from siblings by naming 'remember' and 'recall' as counterparts.

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

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

Explicitly says 'Use when context is stale, the task is done, or you want to clear sensitive data' – providing clear when-to-use guidance. It also references pairing with 'remember and recall', effectively pointing 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 declare readOnlyHint, idempotentHint, and non-destructive behavior, covering the safety profile. The description adds behavioral context: it fetches the page, extracts title/description/key links, and emits standard markdown, plus clarifies output is a text blob. This is valuable but doesn't mention potential network errors or rate limits.

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

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

Three sentences with a clear structure: main action, process, output, and use cases. Every sentence contributes, with no fluff or unnecessary details.

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

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

For a 2-parameter read-only tool with no output schema, the description fully covers the output format ('single text blob ready to drop at site-root/llms.txt'), the process, and the use cases. It lacks only minor edge-case details, which are not essential for a tool of this simplicity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions extracting title/description/key links, which indirectly relates to max_links, but it doesn't add semantics beyond what the schema's own parameter descriptions already provide.

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 generates a production-ready llms.txt file for any URL, using a specific verb ('Generate') and resource ('llms.txt'). It distinguishes from sibling tools by emphasizing the llms.txt output format, which no other tool mentions.

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 use cases (getting a client's site indexed, drafting for your own project, auditing a competitor) and clarifies it works for 'any URL'. However, it does not mention when to prefer sibling tools like scan_competitor_ai_presence, so it lacks explicit exclusions or 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 it read-only, non-destructive, idempotent, and open-world. The description adds value by explicitly listing the return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the 'caller's' scope. While it doesn't describe pagination or cancellation details, it exceeds the annotation baseline by detailing the response shape.

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

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

Two sentences, front-loaded with the operation, then return fields, then usage guidance. Every sentence serves a purpose with no wasted words.

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

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

The description covers what the tool returns, who the data belongs to, and when to use it. There is no output schema, so listing the return fields is especially valuable. With one optional parameter and clear sibling context, this is complete for the tool's complexity.

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

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

Schema coverage is 100%: the single parameter include_inactive is fully described in the input schema. The description doesn't add parameter-specific meaning, but with full schema coverage the baseline of 3 applies. The phrase 'active subscriptions' hints at the default behavior but doesn't explicitly connect to the parameter.

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

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

The description starts with a specific verb and resource: 'List the caller's active subscriptions.' It clearly distinguishes itself from sibling tools like subscribe and unsubscribe by being a read-only listing operation. The mention of returned fields further clarifies what the tool does.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use it relative to subscribe/unsubscribe and gives clear use cases, forming a strong usage guideline.

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

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

Beyond the sparse annotations (all false), the description discloses return behavior (claim_token workflow), rate limiting (5 per day), cost (free, no quota), and roadmap impact, plus a rule about not pasting end-user prompts.

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 each sentence serves a purpose (purpose, usage, exclusions, mechanics, limits). It is front-loaded with the core purpose and organized logically; though verbose, it avoids redundancy.

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

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

The description covers the full workflow: what to report, scope restrictions, message guidance, claim_token retrieval, and practical constraints (rate limit, cost). Given 0 required params and no output schema, this is sufficient.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by instructing users to describe issues in terms of Pipeworx tools/packs and explaining the claim_token round-trip, which complements the schema descriptions.

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

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

The description clearly states the tool's function with an actionable verb ('Tell the Pipeworx team something is broken, missing, or needs to exist'), identifies the resource (Pipeworx tool feedback), and differentiates it from sibling tools by scoping to Pipeworx connection tools only.

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 lists when to use it (bug, feature/data_gap, praise) and provides an exclusion ('ONLY for tools served by this Pipeworx connection') with alternative guidance to file with the correct server.

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, idempotentHint, no destructive), the description adds valuable context: 'no PII', 'derived from CF analytics-engine', 'Cached 5min-1h depending on window', and the output structure '(pack, tool, count)'. These details go beyond annotations and disclose behavior relevant to an agent.

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 but information-dense: lead sentence, return summary, three bulleted use cases, and two clarifying notes. Every sentence earns its place, and the structure is directly scannable for an agent.

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 adequately explains return content (top tools, top packs, call volume, and 'pack, tool, count' tuple). It also covers caching and PII, giving a complete picture for safe invocation. Given low complexity (1 optional param), 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 coverage is 100%, and the parameter description already explains window behavior ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description only mentions the window options without adding new semantic meaning, so baseline 3 applies.

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

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

The description clearly states the tool returns trending calls on Pipeworx (top tools, top packs, total call volume) over selectable windows. It uses a specific verb phrase ('Returns') and identifies the resource precisely, distinguishing it from siblings like discover_tools by focusing on aggregated agent usage.

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 'Useful for' list provides three clear contexts (hot data sources, canonical tool confirmation, alignment with agent needs), giving concrete guidance on when to use. It does not explicitly mention when not to use or name alternative tools, so it misses the top tier.

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

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

Beyond annotations stating read-only and idempotent, the description discloses rich behavior: partition filter dropping placeholder slugs, the 3pp threshold for emitting signals, Jaccard similarity anchor, and fill-check behavior against live CLOB depth. It also explains null-signal and skipped_low_similarity responses, with no contradiction to annotations.

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

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

The description is long but well-organized with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence contributes, but the density might slow quick scanning; a slightly more compact version would earn 5.

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

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

With no output schema, the description fully specifies expected response structure: opportunities[] with key fields, partition_check contents in event mode, and fill-check outputs. It also covers edge cases like skipped_low_similarity, null arb signal, and when the edge is not realizable in the book, making it complete for an agent.

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

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

Although the schema covers both parameters, the description adds substantial meaning: accepted URLs for event, example seed questions for topic, what each mode does internally (walks child markets vs searches related events), and how outputs differ per mode. This goes well beyond the schema field descriptions.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the two operating modes (event vs topic) and mentions polymarket_fill_risk for custom sizing, separating it from sibling tools within its scope.

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

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

It gives explicit when-to-use guidance: recommend event mode for a specific market and topic mode for cross-event scans, with concrete examples and a note about catching date-axis patterns. It also provides a when-not-to-trade rule (realizable_edge_pp <= 0 after fill check) and references polymarket_fill_risk for custom sizing.

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

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

Even though annotations already declare readOnly/openWorld/idempotent, the description adds substantial behavioral context: it discloses edge_pp_net is computed after slippage, Kelly is capped at 0.25, a 24h-move warning is appended when the market move already exceeds the edge, results are cached for 1h, and Fed signals are unreliable without paid data. It also transparently describes why segments may be empty and how the placeholder-slug filter works. No contradictions with annotations.

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

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

The description is well-structured with clear section labels and front-loaded purpose, but it is quite long and includes internal versioning details ('Run 8 from prior 85%/5%/50:1') and highly specific model-family descriptions that are not essential for tool selection or invocation. It earns credit for organization but loses points for density and some extraneous detail.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly. It specifies the top-level response shape (by_segment, fed_candidates/fed_note, _diagnostics), documents the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and explains the diagnostic counters that help callers understand empty segments. This is complete enough for an agent to use the tool correctly without further documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining relationships between parameters, such as why min_kelly never filters partition_overround opportunities (basket trades don't compose to single-leg Kelly) and why min_partition_leg_kelly exists as the intended knob for those cases. It also clarifies that min_edge_pp is evaluated net of slippage. This extra context pushes it above the baseline, though it does not need to repeat each parameter individually.

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

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

The description opens with a specific, action-oriented statement: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly identifies the resource (Polymarket markets), the scope (top markets), and the unique value proposition ('what should I bet on today'). It also distinguishes itself from likely siblings by naming the three response segments and positioning itself as a discovery tool that avoids paging through hundreds of markets.

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

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

The description provides clear usage context ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') and explains when knobs like min_liquidity and max_spread_pp should be adjusted. However, it does not explicitly call out when to use or avoid this tool relative to sibling tools such as polymarket_arbitrage or polymarket_edge_tracker, so it falls short of a full 5.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive behavior, which the description goes well beyond by detailing response structure (tracked, expired, snapshot_dates), limitations (60-day TTL, snapshot gaps), and computation basis (daily closes, not intraday). This adds substantial context not present in annotations.

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

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

The description is well-structured with clearly labeled sections (Args, Response, Limits). Every sentence provides valuable information — from the core purpose to response shape to edge-case limitations. Despite being longer than minimal, no content is wasted.

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

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

Given the tool has no output schema and two parameters, the description fully compensates by detailing the exact response structure, all relevant limitations (snapshot TTL, gaps, non-intraday data), and the semantics of edge_pp_net. It is self-contained and adequate for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100% and both params are described. The description adds extra meaning: 'days' lookback default 14 and max 30 (schema adds clamp 2-30), and 'window' is explained as 'snapshot family' with default 1wk. It also adds conceptual context about how these parameters affect the time-series analysis.

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

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

The description explicitly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question. It clearly distinguishes from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage by focusing on time-series persistence and decay.

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

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

The description provides strong context for when to use the tool: 'a fresh wide edge and a 3-week-old wide edge are different trades' and explains that decay telemetry helps assess opportunity longevity. It does not explicitly name alternative tools or exclusions, but the use case is clearly differentiated from siblings.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds substantial behavioral context: it walks the order-book ladder, returns specific fill metrics, and warns about the risk of partial basket fills converting an arb into a directional position. It also discloses default clamping and mode-specific semantics, exceeding 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 lengthy but carefully structured: purpose statement, mode requirements, explicit usage directive. Every sentence contributes necessary detail for the tool's complexity, and the format (SINGLE-MARKET / BASKET / USE THIS) aids scannability. It could be trimmed slightly, but the length is justified by the tool's dual-mode 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 enumerates all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, capture_ratio, thin_legs[], etc.) and explains the risk interpretation of partial fills. It covers input requirements, defaults, and usage context, making it self-sufficient for an agent to decide when and how to invoke the tool.

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

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

The input schema already covers all 4 parameters with 100% coverage, including defaults and mode-specific descriptions. The tool description enriches this by explaining how size_usd means different things in each mode (max spend on buys vs target proceeds on sells vs settlement notional in basket mode) and clarifies the intent of each side value. This adds value beyond the schema, though the schema already does a good job.

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

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

The description opens with a precise definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates single-market and basket modes, and references sibling tools (polymarket_arbitrage, polymarket_edges) to position its role. This goes beyond a vague verb+resource and distinguishes the tool from alternatives.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when to use single-market vs basket modes and why the check is necessary (theoretical overround not capturable, partial fills create unhedged positions). This provides clear, actionable guidance with alternatives named.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond annotations by detailing safety fields (compatibility_warning conditions), temporal alignment implications, skipped_cross_type/subtype counters, and the caveat that most pre-mapped topics return warnings. This fully discloses the tool's behavioral limitations and failure modes.

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 structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. It is quite long, but every sentence contributes substantive information about usage, response format, or limitations. The length is justified by the tool's complexity, though a more concise version could earn a 5.

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

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

There is no output schema, so the description must explain return values, and it does so thoroughly: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning, temporal_alignment, and skipped_cross_type/subtype. It also covers edge cases and semantic mismatches, making the description self-sufficient for an agent to invoke the tool and interpret results.

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

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

The schema already provides 100% coverage with descriptions and examples for all three parameters. The description adds meaningful semantics about how parameters interact (explicit parameters override topic-mapped sides) and explains the two mode variants, which is beyond the schema. It doesn't delve into value format details beyond schema examples, so a 4 rather than 5 is appropriate.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, with a specific verb ('spread') and resource (two venues). It distinguishes itself from siblings by focusing on same-question cross-venue comparison and explicitly describing two operation modes.

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

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

The description explains when to use each mode: topic shortcuts for pre-mapped macro events and explicit ticker/slug for custom pairings. It also warns when the tool's output should not be trusted (compatibility_warning, temporal alignment false), which effectively tells the agent when to use and when to avoid. However, it does not explicitly name alternative tools or state exclusion criteria relative to siblings.

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

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

Annotations already declare read-only, non-destructive, and idempotent behavior. The description adds valuable context beyond that: scoping to an identifier (anonymous IP, BYO key hash, account ID), the omit-key behavior for listing all keys, and the lifecycle pairing with remember/forget. 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 three focused sentences: the first states action and alternative, the second gives usage examples, the third covers scoping and sibling relationships. Every sentence earns its place with no fluff.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, usage, scope, and relationships. It doesn't specify behavior for missing keys, but the examples and clear statement of retrieve/list behavior make it nearly complete for typical use.

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

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

Schema coverage is 100% and the key parameter description is clear. The tool description supplements the schema by explaining that keys are 'previously saved via remember', adding context about the key's origin that is not present in the schema.

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

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

The description clearly states the tool's primary action ('Retrieve a value') and resource ('previously saved via remember'), plus the alternative behavior ('list all saved keys'). It distinguishes from siblings by explicitly referencing 'remember' and 'forget' as paired tools.

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

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

The description says 'Use to look up context the agent stored earlier' and provides concrete examples (target ticker, address, research notes), giving clear when-to-use guidance. It names alternatives ('remember' to save, 'forget' to delete) but doesn't explicitly state when not to use the 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?

The description discloses that setting mark_read:true modifies the read state of events, meaning subsequent calls only show newer entries. This contradicts the readOnlyHint=true annotation, which implies the tool is strictly read-only, creating an annotation contradiction. Thus the behavioral transparency is severely undermined.

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 long and front-loads the core purpose in the first phrase. Every sentence adds useful information without redundancy.

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

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

The description covers the core return fields, filtering, and stateful behavior despite lacking an output schema. It also points to an HTTP endpoint for additional access. However, the contradiction in read-only status leaves some ambiguity that affects overall completeness.

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

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

The schema already describes each parameter, and the description adds concrete examples (e.g., filtering by type 'sec_8k' and ISO timestamps) and explains the effect of mark_read on future calls. This enriches the parameter semantics beyond the schema's basic descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, which is a specific action with a clear resource. It distinguishes itself from sibling tools like list_subscriptions by focusing on recent alert events, not the subscription list itself.

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

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

The description explains when to use the tool (to pull recent alerts), and provides guidance on filtering by type and time, as well as using mark_read to control future reads. It also mentions an alternative HTTP endpoint for scripts, though it doesn't explicitly contrast with sibling 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses fan-out to multiple sources, fallback behavior, the USPTO API sunset, and the exact return structure. It also clarifies the 'since' parameter format and typical usage, which is not covered by 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 adds critical information: usage examples, source lists, fallback logic, parameter formats, return structure, and alternative tool. No filler or redundancy exists, and the structure flows logically from use case to behavior to parameters to output.

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 the return structure (changes[] grouped by source, total_changes, citation URIs). It also covers edge cases like the USPTO soft-fail and GNews fallback, making the tool's behavior predictable in complex scenarios.

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

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

The schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by providing concrete examples for 'since' ('2026-04-01', '7d', '30d') and a recommendation ('30d' or '1m' for typical monitoring), which goes beyond the schema's generic explanation.

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

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

The description clearly identifies the tool as a change feed for a company in a time window, with concrete query examples like 'What's new with X'. It explicitly distinguishes this from entity_profile, which provides static profiles. The verb 'change feed' and resource 'company' are specific and unambiguous.

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

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

The description gives explicit when-to-use guidance via examples and contrasts with entity_profile: 'Use entity_profile instead when you want the static profile'. It also explains the fallback logic (GDELT→GNews) and notes the USPTO soft-failure, setting expectations for when the tool may not return complete data.

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

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

Annotations already declare the tool as non-destructive, idempotent, and non-read-only. The description adds valuable behavioral context beyond this: key-value scoping by identifier, persistence differences between authenticated (persistent) and anonymous (24-hour) sessions, and the ability to span conversations/sessions. This enhances the agent's understanding 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?

Three concise sentences: first states the primary purpose, second gives actionable usage examples, third covers storage details and companion tools. Information is front-loaded, with no redundancy or filler. Each sentence earns its place.

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

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

The description is complete for this simple write tool: purpose, usage, scoping, persistence, and relationship to siblings are all covered. With a fully documented schema and no output schema, there is no missing critical information. It adequately equips the agent to select and invoke the tool.

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

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

The schema covers both parameters with descriptive examples (key and value), so the description need not repeat them. The phrase 'key-value pair scoped by your identifier' adds slight semantic context about the key's scoping, but overall the description offers minimal additive parameter detail. Baseline 3 is appropriate given full schema coverage.

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 ('Save data the agent will need to reuse later') and clarifies the key-value store nature. It distinguishes itself from siblings by explicitly pairing with 'recall' and 'forget', which are close alternatives, making its role 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?

Provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject'). It also tells the agent when to use companion tools ('Pair with recall to retrieve later, forget to delete'), effectively covering both use and non-use cases.

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

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

The description goes well beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing internal cascading behavior ('each call cascades through several lookup endpoints internally'), graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), and explicit handling of unresolved identifiers ('stated explicitly under `unresolved` rather than omitted'). 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 front-loaded with the core purpose and example queries, which is effective. However, it is somewhat verbose, containing detailed explanations of identifier sources and behavior that could be streamlined or organized into bullet points. Every sentence adds value, but the length may reduce quick scanning efficiency.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, no output schema), the description is remarkably complete. It covers the return structure (labeled identifiers, unresolved list), graceful degradation, and internal cascading. The agent has enough context to correctly invoke the tool and interpret its results without needing 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?

Although the input schema already covers both parameters with 100% description coverage, the description adds substantial meaning. For the 'type' parameter, it explains what each entity type returns (e.g., for 'company': CIK, ticker, LEI, FIGI; for 'drug': RxCUI, ingredient, brand). For the 'value' parameter, it specifies valid input formats (ticker, CIK, ISIN, name for company; brand or generic name for drug). This enriches the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides specific example queries ('What's the ticker for…', 'find the CIK for…') and explicitly distinguishes it from siblings by advising to 'Use FIRST whenever you have a name but need an ID.' This verb+resource+scope combination is precise and 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?

The description gives explicit guidance on when to use this tool: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups, implying it is a primary lookup step. It details the supported types (company, drug) and what inputs each accepts, effectively telling the agent when to invoke this tool versus alternatives like entity_profile (which would be used after obtaining an 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?

The description adds meaningful behavioral context beyond the annotations: it reveals that the tool internally probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. Annotations already declare readOnly/openWorld/idempotent, and the description complements these without contradiction, though it could mention potential rate limits or failure modes.

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 adds distinct value: what it does, how it does it, and a concrete use case. 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?

With no output schema, the description adequately explains return values (ranked list with score, confidence, signal density). It also covers input constraints (2-8 entities) and the internal mechanics, making it sufficiently complete 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?

The input schema provides 100% coverage with detailed descriptions for all parameters, including the special meaning of the first entity in the array. The description itself adds little parameter-level nuance beyond what the schema already states, 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 opens with a clear verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It goes on to explain the ranking and detection of most/least recognized entities, which distinguishes it from single-entity tools like ai_visibility_check and generic comparison tools like compare_entities.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example question ('does Claude know about us as well as our competitors?'). While it doesn't explicitly name alternatives or state when not to use the tool, the context is clear enough for an agent to decide when this multi-entity comparison 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?

The description discloses concrete behavioral traits beyond annotations: 'bundlephobia's first measurement on a new version can take 5-30s' and 'Partial failures degrade gracefully — sources_failed will list it if it times out, the rest still returns'. These latency and failure handling details are not present in the annotations, which already declare the operation read-only and idempotent. No contradiction with 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 six sentences long, each serving a distinct purpose: defining the composite operation, listing covered data sources, giving usage triggers, enumerating return fields, declaring ecosystem scope, and explaining failure behavior. Every sentence earns its place, and the main purpose 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?

Given the tool's complexity (composite of two external services, no output schema), the description compensates fully by enumerating every returned field in the summary block, detailing partial failure and timeout behavior, and stating ecosystem limitations. An agent can correctly invoke the tool and interpret results 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 coverage is 100% with descriptions for both parameters, giving a baseline of 3. The description adds useful semantics: 'Scoped packages (e.g. "@types/node") are accepted' and 'Defaults to the latest published version when omitted', which clarify invocation specifics not fully captured in the schema. This meaningful addition justifies a score above baseline, though it is not extensive enough for 5.

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 'Composite should I add this npm package to my project check in ONE call', which precisely states the tool's purpose, resource, and composite nature. It distinguishes itself from siblings by explicitly limiting scope to the NPM ecosystem and naming the backend services (deps.dev and bundlephobia), which no other sibling tool appears to combine.

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 an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', giving clear invocation triggers. It also provides a direct exclusion: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', pointing to an alternative for non-NPM packages.

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

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description adds significant behavioral context: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)' and 'every passage carries an offset so the agent can verify a verbatim quote.' This details the embedding model, chunking strategy, truncation behavior, and output features — well beyond what annotations alone could 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 structured with a clear lead sentence, usage guidance, workflow pairing, and technical details. Each sentence contributes value, but the technical details make it a bit longer than strictly necessary. It remains well-organized and front-loaded, earning a 4 rather than a 5 due to slight density.

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, so the description must explain return values — and it does: 'get back the top-N passages with character offsets and similarity scores.' It also covers input constraints (200K chars), use case (large records), and integration (ask_pipeworx_grounded). Combined with thorough annotations and schema, the description is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so each parameter already has a description. However, the description enhances the meaning of 'text' by noting the 200K char cap and truncation flag, and it clarifies how 'query' is used with natural-language examples. It also explains the relationship between text and output (window size), adding context not present in the schema. This exceeds the baseline 3 for high schema coverage.

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 action ('Semantic search') on a specific resource ('INSIDE a fetched record'), and immediately differentiates itself from siblings by emphasizing 'Pass the text you already pulled' — making it clear this is for searching within user-provided text, not external sources. This contrasts with sibling tools like ask_pipeworx_grounded and ask_pipeworx, which likely operate on whole documents or external data.

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

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

The description gives explicit guidance: 'Use when the record is too big to cram into the prompt' and explicitly names an alternative and pairing: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This tells the agent both when to use this tool and how it fits into a larger workflow, satisfying the 'when/when-not/alternatives' criterion.

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

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

The description adds substantial behavioral context beyond the annotations: it requires a Pipeworx OAuth account, returns a subscription id, explains each subscription type and delivery channel in detail, notes SMS phone verification and caps, and discloses webhook signing behavior and auto-disable after failures. It does not contradict any 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 each sentence contributes useful information, including prerequisites, supported types, and delivery channels. It is front-loaded with the core action and return value. Some redundancy with the schema's delivery details is present but not excessive 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?

This is a complex subscription tool with nested params, multiple types, and no output schema. The description covers the return value, account requirements, type-specific parameters, delivery channel options, constraints, and failure behavior. Combined with the fully described input schema, it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already defines parameters well. The description adds concrete examples for each type (e.g., items:["5.02"]) and detailed delivery semantics, but some of this duplicates the schema's property descriptions. It adds meaningful value without being strictly necessary.

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

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

The description uses a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states it returns the new subscription id, and the mention of subscription creation distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 context by listing supported subscription types, required OAuth account, and optional delivery channels. It does not explicitly state when to avoid this tool or compare it to alternatives like list_subscriptions, but the usage boundaries are reasonably clear.

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

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

Annotations already declare read-only, open-world, and idempotent hints. The description adds valuable context about the response content (category-bucketed examples, exact tool and argument shape, live catalog) and how the topic parameter changes behavior. 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?

The description is longer than typical but every segment earns its place: example queries, category list, tool-shape detail, and usage instructions. It is front-loaded with example queries and structured with em-dashes. Slightly verbose but not wasteful.

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

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

Given no output schema, the description adequately explains the return format and purpose. It covers both invocation modes (no args vs topic) and the tool's role in onboarding, making it complete for an agent to use 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 a clear description of the topic parameter including allowed values and default behavior. The description adds example values ('finance', 'pharma', 'betting') and explains the focus effect, providing marginal extra value.

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

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

The description clearly states it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It is distinct from siblings like discover_tools or ask_pipeworx, and uses specific verbs like 'returns example questions'.

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 this FIRST when you do not yet know what Pipeworx can do for you' and provides context for both no-argument and topic-filtered calls. It also names meta-tools to learn about, giving clear cross-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?

The description discloses important behavioral traits beyond annotations: ownership is enforced, and the row is deactivated rather than deleted, preserving historical events. This aligns with destructiveHint=false and adds valuable context about side effects.

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

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

Two concise sentences that front-load the core action and then add necessary constraints. No wasted words 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?

For a simple one-parameter tool with rich annotations, the description covers the essential context: ownership, soft-delete behavior, and impact on historical events. It is complete enough for an agent 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?

The schema already provides full coverage for the single 'id' parameter with a clear description. The tool description adds only 'by id', which does not significantly enhance the parameter understanding beyond the schema.

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

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

The description uses a specific verb 'Cancel' with a clear resource 'subscription by id'. It also adds ownership enforcement, distinguishing it from sibling tools like subscribe and list_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?

The description clearly implies when to use the tool (when you have a subscription id to cancel) and mentions the ownership constraint. However, it does not explicitly compare with alternatives or state when not to use it.

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

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

Despite annotations already indicating read-only, open-world, idempotent, and non-destructive, the description adds substantial context: the two distinct execution paths, the full list of verdicts, the meaning of could_not_verify (check did not happen) and unsupported, and the return payload with citation and reasoning. This far exceeds annotation coverage.

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

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

The description is compact yet information-dense, with a logical flow: purpose, trigger phrases, usage, internal routing, output format, and critical caller notes. Every sentence adds value, and important caveats are marked with 'IMPORTANT for callers.'

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 covers all necessary aspects: input, behavior, output, error semantics, and comparison with alternatives. Even without an output schema, it clearly enumerates the verdict types and the contents of the return value. It is fully self-contained 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%, but the description enriches both parameters: claim is explained as natural-language with concrete examples, and tolerance_pct is detailed with range, override behavior, and use-case guidance (e.g., set 1–2 for hallucination detection). This goes well beyond the schema's property descriptions.

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

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

The description clearly states a specific verb and resource: 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings like ask_pipeworx or deep_research by explicitly defining the fact-checking use case and the unique two-path pipeline (SEC EDGAR/XBRL for financial claims, grounded pipeline otherwise).

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides concrete behavioral guidance by distinguishing could_not_verify from unsupported, and notes that it replaces 4–6 sequential calls, implying when to prefer it over chaining other tools.

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