Faa Delays

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds context beyond annotations by listing specific return elements (ground stops, delay program with avg/max, trends, closures, FAA reason) and explaining empty-result semantics. Could mention freshness, but current detail is solid.

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

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

Three sentences, front-loaded with purpose, then usage, output composition, parameter instruction, and empty-result interpretation. No wasted words; every sentence contributes unique information.

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

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

Given the tool's low complexity (one parameter) and strong annotations, the description fully covers the invocation context, return content, and result interpretation without needing an output schema. It is complete for a single-airport delay lookup.

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

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

Schema description coverage is 100% and already defines the 'airport' parameter as a 3-letter code with examples. The description merely repeats 'Pass a 3-letter airport code' without adding new semantic meaning, so baseline 3 is appropriate.

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

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

Description clearly states 'Live FAA operational delay status for ONE US airport' with specific verb (returns status) and resource (US airport). It distinguishes from siblings by emphasizing single-airport scope and explicitly contrasts with web search, making its purpose unambiguous.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' for delay queries and gives concrete example phrasings. It also implies not for multi-airport use by saying 'ONE US airport', and interprets empty results, offering clear when-to-use and interpretative 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 meaningful context beyond that: the default model and cost implications ('BYO key — you pay Anthropic directly') and the exact return structure ('per-model {score, confidence, signals, raw_response} + a combined view'). It doesn't mention error handling but covers the key behavioral aspects.

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 that front-load the primary action and output, then cost/usage specifics, then return details and use cases. Every sentence adds distinct information with zero waste.

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

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

The description covers the main input parameters, default behavior, return format, and target use cases, which is complete for a simple read-only tool. Since there is no output schema, the explicit return structure description is valuable. It could expand on failure scenarios (e.g., missing API key when requesting Anthropic), but overall it's sufficiently 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%, so the schema already documents all parameters. The description adds a small semantic layer by explaining the default model and the cost pass-through for `_apiKey`, but otherwise relies on the schema for parameter meaning. This meets the baseline for full coverage without substantial added value.

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

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

The description opens with a specific verb ('Probe') and resource ('one or more LLMs') and clearly states the output ('score visibility (0-100) per model'), differentiating it from unrelated siblings. It also specifies the default model and optional Anthropic interaction, leaving no ambiguity about the tool's function.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the free default vs. paying for Anthropic via `_apiKey`. However, it doesn't explicitly name alternatives or when-not-to-use, such as distinguishing from the sibling `scan_competitor_ai_presence`.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, non-destructive), the description adds that this is a real-time 'snapshot' covering ALL active programs, and that each result includes the delay reason. This provides useful behavioral context about the tool's scope and output content, though it does not disclose response size or potential truncation.

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, with the first sentence front-loading the core purpose and the second providing concrete use-case examples. Every phrase earns its place, and the inclusion of delay types adds clarity without excessive verbosity.

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

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

For a tool with no parameters, strong annotations, and no output schema, the description is sufficiently complete. It communicates the nationwide scope, the types of programs included, the reason field, and gives example queries. The absence of an output schema is compensated by this clear description of the data content.

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 tool has zero parameters, so the baseline is 4 as per the rubric. The description appropriately avoids mentioning parameters since there are none, and the schema already fully documents (vacuously) that no parameters are needed.

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

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

The description clearly states the tool provides a 'Nationwide snapshot of ALL active FAA delay programs right now' and enumerates the types of delays covered (ground stop, ground delay, arrival/departure delay, closure) including their reasons. This specific verb+resource+scope distinguishes it from the sibling tool 'airport_delays' which likely focuses on a single airport.

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

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

The description explicitly states when to use it with example queries like 'which airports have delays today' and 'are there nationwide ground stops'. It gives clear context for nationwide use cases, though it does not explicitly mention when not to use it or name the alternative 'airport_delays' tool.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals significant behavioral context: it routes to one of 5,564 tools across 1,462 sources, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and works on every tier with 'one fast call'. This adds useful insight into the tool's internal routing and output characteristics without contradicting the annotations.

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

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

The description is long but well-organized and front-loaded with the core directive. It efficiently uses lists and examples to convey breadth, and each sentence contributes a distinct piece of information (use cases, alternatives, behavior). Minor redundancy exists ('START HERE' and 'default entry point' both convey precedence), so it is not maximally concise, but it is far from bloated.

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 meta-tool that routes to thousands of sources, the description is remarkably complete: it covers purpose, target domains, output format (structured answer with citation URIs), reliability (stable citations), and escalation paths to sibling tools. Given that there is no output schema, the description appropriately explains the return value nature. It also addresses edge cases like breaking news and multi-part questions, leaving few gaps.

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

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

The schema already covers the parameter fully: the 'question' parameter has a description, and the five aliases (q, text, input, query, prompt) are enumerated as equivalents. The description provides examples of well-formed questions, which is helpful but not substantial semantic enrichment beyond what the schema offers. Since schema coverage is 100%, 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 strong directive to prefer this tool over web search for a broad set of factual/current-data questions, naming specific domains like SEC filings, FDA data, FRED/BLS statistics, patents, etc. It clearly distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research and positioning ask_pipeworx as the default entry point.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and it names explicit alternatives for when to step up ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also includes concrete trigger phrases and examples, which gives clear operational direction.

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

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

Annotations already provide readOnly/openWorld/idempotent safety signals. The description adds valuable context beyond the annotations: no active candidate right now, the last was retired on 2026-07-26, it currently matches ask_pipeworx exactly, and it falls back to nothing as a full working router.

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 intentionally sized and front-loaded: it states the key relationship to ask_pipeworx, the current experimental state, usage directive, and comparison behavior in four dense sentences. No redundant filler.

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

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

Given the circularity and novelty of a beta universal router, the description covers the key operational facts: what it matches, when to use it, its relationship to ask_pipeworx, and the 'full working router, no fallback' distinction. It is sufficiently complete for a list-like router 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%, with all six parameters documented as aliases for the required 'question' string. The description says 'same arguments' but adds no parameter-level detail beyond the schema, so the schema already carries the full semantic weight.

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: identical universal router (same 5,564 tools, same arguments, same response shape)' with candidate routing improvements. It distinguishes itself from the stable ask_pipeworx sibling by explaining it is the experimental edge with the same core function.

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

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

Provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' It also clarifies the current state and that there is no active candidate, so behavior matches ask_pipeworx exactly.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description goes far beyond by detailing the exact success and refusal return shapes, including refusal_reason enum values, evidence quoting, and the internal routing/execution process. No contradiction with annotations; this is exemplary transparency.

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

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

The description is relatively long but every sentence contributes meaningful information: behavior, return format, usage scenarios, and cost trade-off. It is well-structured with a logical flow from mechanism to examples to guidance, though it could be slightly tightened without losing value.

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

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

Given no output schema, the description thoroughly explains return values and refusal reasons, making the tool's behavior fully specified. It also provides scale context ('5,564 across 1462 sources') and operational nuance ('costs one extra LLM call'), covering all necessary aspects for an agent to use it correctly.

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

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

Schema coverage is 100% for all 6 parameters, all documented as aliases for 'question'. The description does not add additional parameter-specific details, but given full schema coverage, the baseline of 3 is appropriate. The description's focus on usage context does not harm parameter understanding.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, distinguishing it from the sibling ask_pipeworx by describing its extraction methodology and explicit refusal behavior. The verb 'EXTRACTS' and resource 'tool result' make the purpose specific and differentiated.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on...') and when not to ('prefer ask_pipeworx for casual lookups'), also noting the extra LLM call cost. This provides clear decision-making guidance relative to alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the description goes far beyond that by disclosing behavioral traits such as low-confidence resolution short-circuiting, closed/dead market handling, wide-spread illiquidity warnings, cancellation-rule risk (e.g., refund_50_50), and fallback behavior for news sources (GDELT 429, GNews backfill). These are exactly the kind of operational nuances an agent needs.

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 extremely well-structured, using uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) that make it scannable for an agent. Every section adds essential information for correct invocation and result interpretation. It could be slightly tighter (the fan-out examples are numerous), but the density is justified given the tool's complexity.

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

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

Despite having no output schema, the description fully explains the return structure (result.market, result.analysis, result.evidence, parent_event), the resolver contract with match confidence and alternatives, safety behaviors, and edge cases like market closure and cancellation rules. It also notes the blocking nature of low-confidence matches. This is a complete operational specification for a complex tool.

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

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

The input schema has 100% coverage for all three parameters (market, depth, include_raw), each with its own description. The tool description reiterates the market parameter's polymorphic input forms (slug, URL, question text) and gives examples of depth, but does not add substantial semantic meaning beyond what the schema already provides. Thus the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from the many sibling Polymarket tools by specifying the use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and by listing classifiers and fan-out examples that demonstrate its unique research function.

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

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

The description explicitly states when to use the tool ('Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"') and provides multiple concrete examples (BTC bet, Fed bet, Hormuz bet, etc.). It does not explicitly contrast with sibling tools like ask_pipeworx or polymarket_edges, but the clear use-case framing and the fan-out details make the intended context unambiguous.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description reveals data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs in results. It also notes it replaces 8–15 sequential lookups, adding significant operational transparency.

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

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

The description is long but front-loaded with trigger phrases and usage rules. Every sentence adds value—data sources, sorting behavior, output details—yet it could be condensed slightly without losing information. Still, it is well-organized and effectively 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?

Given the complexity of two entity types, multiple data sources, sorting, and citations, the description covers all essentials: what data is retrieved, how it is ordered, and what the response includes. No output schema exists, so the description adequately substitutes for explaining return values.

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 both parameters already described, but the description enriches semantics by explaining what each type pulls (10-K financials vs. FAERS counts), clarifies values as tickers/CIKs or drug names, and reiterates the 2–5 item constraint with examples. It adds contextual meaning beyond the basic 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 performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with explicit verb and resource. It distinguishes from siblings like entity_profile by emphasizing multi-entity comparison and parallel execution.

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 lists trigger phrases ("Compare X and Y", "which is bigger", etc.) and gives an absolute rule: "ALWAYS PREFER over sequential single-pack lookups when comparing entities." It also specifies when to use company vs. drug, providing comprehensive 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?

Annotations already declare the tool safe/read-only, but the description adds far more: account and paid-tier constraints, parallel routing to 5,564 tools, the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[] behavior, contradictions[], semantic excerpting, and expected latency. Nothing contradicts 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 long but information-dense, and the most urgent operational constraint (ACCOUNT REQUIRED) is front-loaded. Every clause earns its place, though the single-block structure with many semicolon-joined clauses makes it slightly harder to parse than a cleaner bulleted layout would be.

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

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

For a complex tool with no output schema, the description is remarkably complete: it covers auth, cost, use cases, non-use cases, alternatives, internal mechanism, return packet fields, gap-filling behavior, citation resolvability, contradiction handling, and timing. An agent has enough information to select, invoke, and interpret results correctly.

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

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

Schema coverage is 100% and the depth parameter already has a detailed description, so the baseline is 3. The description adds meaningful extras beyond the schema: depth:'thorough' requires a paid plan, the account prerequisite, and approximate latency expectations per depth. This goes beyond schema but is incremental rather than transformative.

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 specific action and resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in ONE call, and explicitly warns 'this is NOT open-web search.' It also distinguishes itself from siblings by positioning itself for broad/multi-part structured-data questions and calling out ask_pipeworx as the single-lookup alternative.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and explicit when-not-to-use guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also names an exact alternative tool and accounts for sign-in/payment status.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds beyond annotations by specifying the return behavior: top-N most relevant tools with names, descriptions, full input schemas with curated examples, ready to call directly without a second lookup. It doesn't mention pagination or rate limits, but for a read-only search tool this is sufficient additional context.

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

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

Three sentences front-load the purpose, then provide domain examples and usage instruction. Every sentence adds value: purpose, return format/domains, and when-to-use. The domain list is long but directly informs the agent which queries route here. No filler.

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

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

With annotations and 100% schema coverage, the description still manages to cover the result shape (top-N tools with full schemas and examples) which an output schema would normally provide. Given the tool's low complexity (one required parameter) and rich structured data, this is fully complete for selection and invocation.

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

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

Schema description coverage is 100%: query, q, task, search, description, and limit are all defined. The description restates that the query is a natural language description with examples (already in schema examples). It adds no new semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task,' clearly stating a specific verb (find/discover) and resource (tools). It explicitly differentiates from sibling tools by listing domains it covers and framing itself as a discovery layer, unlike domain-specific siblings like airport_delays or deep_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?

Provides direct usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and instructs to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent exactly when to invoke it versus searching for a specific tool.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses important behavioral traits: the USPTO PatentsView API sunset with soft-fail, GDELT→GNews fallback, return limit of 5 filings, and sorted fundamentals. This contextual richness exceeds 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 long (~130 words) but every sentence contributes meaningful information—examples, return fields, fallback behavior, and input constraints. It is dense rather than verbose, though a tighter structure could improve scannability.

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

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

Given the complexity (multiple data sources, fallbacks, partial failures) and no output schema, the description fully covers return fields, edge cases (patent API sunset), and input requirements. It is a complete standalone reference for invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the zero-padded CIK format, giving concrete examples, and emphasizing that names are not supported, which goes beyond the schema descriptions.

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

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

The description uses a specific verb+resource pattern: 'full cross-source profile of a US public company' with concrete example queries. It clearly distinguishes itself from sibling tools by explicitly stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'.

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

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

The description provides explicit when-to-use guidance: 'when the user asks for a holistic view'. It also gives a clear exclusion: 'names not supported (use resolve_entity first if you only have a name)'.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds context about what gets destroyed: a previously stored memory. It also highlights 'clear sensitive data,' providing additional behavioral context. No contradiction with annotations is present.

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-loaded with the core purpose. Each sentence earns its place: one for what it does, one for when to use, and one for related tooling. No unnecessary verbiage.

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 one-parameter destructive memory operation, the description, combined with annotations and schema, provides complete guidance. It explains the action, usage triggers, and relation to sibling tools. No output schema is present, so return-behavior explanation is unnecessary.

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

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

The input schema fully describes the sole parameter ('key' with description 'Memory key to delete') with 100% coverage. The description adds only the phrasing 'by key,' which does not meaningfully enhance the schema's semantic content. Baseline 3 applies as the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' The verb is specific ('Delete'), the resource is clear ('previously stored memory'), and the mechanism is explicit ('by key'). It distinguishes from sibling tools like remember and recall by focusing on deletion.

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

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

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, indicating related tools. However, it lacks an explicit 'when not to use' clause, so it doesn't fully meet the top-tier 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context about fetching the page, extracting title/description/key links, and emitting a single text blob, going beyond what annotations convey 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 three sentences, front-loaded with the main action, and includes use cases without any redundant filler. Every sentence earns its place.

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

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

Given the tool's low complexity (2 params, no output schema), the description adequately covers purpose, process, output format, and typical use cases. Nothing essential is missing.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' fully documented. The description does not add parameter-level details beyond the schema, so it meets the baseline of 3.

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

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

The description clearly states the tool's function with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It details the process (fetches, extracts, emits) and distinguishes itself from sibling tools by focusing on producing a standard markdown file for AI crawlers.

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

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

The description provides explicit use cases in a 'Useful for:' list covering client work, personal projects, and competitor auditing. However, it does not mention when not to use the tool or name alternative tools, so it stops short of a perfect score.

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

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

The description adds value beyond the annotations by specifying the scope ('caller's active subscriptions') and enumerating the returned fields (id, type, params, created_at, last_fired_at, fire_count). These details are not present in the annotations or the input schema, and they do not contradict the read-only and idempotent 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 three short sentences, each serving a distinct purpose: stating the function, listing return fields, and giving usage guidance. It is front-loaded, free of filler, and every word 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?

For a simple list tool with one optional parameter and no output schema, the description covers all essential aspects: purpose, scope, return fields, and usage guidance. It might benefit from a note about the include_inactive parameter or the meaning of 'active,' but the schema already handles that, so it is nearly complete.

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

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

The schema already provides 100% coverage for the single optional parameter include_inactive with a clear description. The tool description does not add any additional meaning for this parameter, so the baseline of 3 applies per the rubric.

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

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

The description states a specific action ('List the caller's active subscriptions') with a clear resource and scope. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions, and it names the return fields for added specificity.

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

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

The description provides clear context for when to use the tool: to review current monitoring before adding subscriptions and to find an id for cancellation. This implies alternatives (subscribe/unsubscribe) but does not explicitly exclude other tools or mention when not to use it, 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 are all false, so the description carries the full burden. It discloses rate limiting (5 per identifier per day), the fact that filing returns a claim_token, that the token can be reused to read status, that the team reads digests daily, and that it's free and doesn't count against quota. These are meaningful behavioral traits beyond the structured fields.

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

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

The description is longer than average (~160 words) but well-structured with explicit use cases, exclusions, token flow, and operational details. Every sentence serves a purpose, though a few could be tightened (e.g., 'signal directly affects roadmap') without losing essential info. Not maximally concise but efficient.

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

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

No output schema exists, but the description explains both the initial filing response (returns a claim_token) and the later claim_token query response (status and changes). Combined with usage guidelines, exclusions, formatting rules, and rate limits, it is fully sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning. It explains how claim_token is obtained and reused with an example call, instructs to describe issues in terms of Pipeworx tools/packs (mapping to context), and forbids pasting end-user prompts (guidance for message). This enriches all parameters beyond the schema.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a specific verb and resource. It explicitly enumerates feedback types (bug, feature, data_gap, praise) and distinguishes from other servers by limiting scope to 'tools served by this Pipeworx connection.' This clearly separates it from siblings like ask_pipeworx or discover_tools.

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

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

Provides explicit when-to-use criteria for each feedback type and a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also gives formatting rules (describe in terms of Pipeworx tools/packs, don't paste the end-user's prompt) and explains the claim_token workflow for following up.

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

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

Adds 'no PII', 'derived from CF analytics-engine', and 'Cached 5min-1h depending on window' — all beyond the annotations' readOnly/openWorld/idempotent hints. It also describes the output shape as '(pack, tool, count)'.

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 an opening hook, bullet list of use cases, and a concise data-source/caching sentence. 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?

Despite having no output schema, the description specifies the return contents (top tools, top packs, total call volume) and the data tuple shape. Combined with annotations, this covers safety, privacy, and staleness.

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 single 'window' parameter is fully described in the schema with enum and semantics. The description adds the caching dependency ('Cached 5min-1h depending on window') which is a useful extra consideration when selecting a window.

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 'What other AI agents are calling on Pipeworx right now' and specifies returns: 'top tools, top packs, and total call volume over a recent window'. This clearly distinguishes it from siblings like discover_tools by focusing on aggregate usage trends rather than discovery.

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 three explicit 'Useful for' bullet points covering discovering hot data sources, confirming canonical tool choice, and aligning use cases. No explicit alternatives or when-not-to-use, but the scenarios are concrete enough.

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

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

Despite idempotentHint and readOnlyHint annotations, the description adds substantial behavioral context: it discloses the 3pp deviation threshold, Jaccard similarity filter, placeholder-slug filtering, and the fill-check behavior with the caveat "realizable_edge_pp ≤ 0 means ... do not trade it." No contradiction with annotations; it richly surpasses what annotations alone 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 dense and action-packed but reads as a single lengthy paragraph. It front-loads the core purpose and then details modes, thresholds, response shapes, and fill-check logic. While every sentence provides value, the lack of bullet points or section breaks makes it slightly harder to parse quickly.

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

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

With no output schema, the description compensates by outlining response structures (opportunities[], partition_check fields, fill_check results) and critical decision cues. It covers edge cases like placeholder filters, similarity thresholds, and the distinction between theoretical vs realizable edge. It also points to a sibling for custom sizing, making it contextually complete for a complex tool.

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

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

The input schema already covers both parameters (event and topic) with descriptions, but the tool description adds deep semantics: full-mode explanations, examples ("fed-decision-may-2026"), and behavioral expectations ("walks child markets, checks date-axis / threshold-axis ordering"). It transforms each string parameter from a mere name into a mode with distinct outputs and use cases.

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

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

The description opens with a specific verb and resource: "Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks." It clearly distinguishes this tool from siblings like polymarket_edges and polymarket_fill_risk by naming its detection methods, and the distinction is reinforced by the detailed modes (trending_scan, event, topic).

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

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

The description explicitly states when to use each mode: "Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan." It also recommends event for specific markets, notes that cross-event mode catches patterns single-event misses, and directs users to a sibling for sizing: "For custom sizing use polymarket_fill_risk."

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds extensive behavioral context: 1-hour KV caching keyed on all knobs, response diagnostics for empty segments, model gate details, slippage subtraction, Kelly caps, and the 24h-move warning. This goes far beyond what annotations provide and does not contradict them.

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

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

The description is long but densely packed with non-redundant information. It is structured into model families, tradeable-edge knobs, and response top-level, with each sentence earning its place. The core purpose is front-loaded, and there is no filler.

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

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

Given no output schema, the description fully specifies the response structure (by_segment, fed_candidates, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume). It covers limitations, caching behavior, and why segments might be empty, making it complete for a complex tool.

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

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

Even though schema coverage is 100%, the description adds meaningful context about how parameters interact: min_liquidity/max_spread_pp are tradeable-edge filters, min_kelly does not apply to partition arbs, and min_partition_leg_kelly applies to best per-leg Kelly. This explains the rationale behind the knobs, adding value beyond the schema.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from siblings like polymarket_arbitrage by focusing on model-driven edges rather than arbitrage, and 'without paging hundreds of markets' signals its unique value.

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

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

It explicitly states the use case ('what should I bet on today') and explains when to use tradeable-edge knobs, why Fed candidates are excluded, and how to interpret empty segments. However, it does not explicitly name sibling alternatives or state when NOT to use this tool versus tools like polymarket_kalshi_spread, so it falls short of a 5.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses substantial behavioral details: the 60-day snapshot TTL, cache-miss gaps, decay computed from daily closes not intraday, and the exact meaning of expired[] and snapshot_dates[]. This is rich, honest disclosure that goes far beyond the structured annotations.

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

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

The description is well-structured with clear labels (Args, RESPONSE, LIMITS) and is front-loaded with a concise summary. Every sentence serves a purpose, providing detailed information about inputs, outputs, and limitations without fluff or repetition. The length is justified by the tool's complexity.

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

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

Since there is no output schema, the description fully specifies the response structure (tracked[], expired[], snapshot_dates[]) and their semantics. It also covers limitations (TTL, gaps) and calculation details, making the description complete enough for an agent to use the tool correctly without additional context.

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

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

The input schema already provides complete descriptions for both parameters (days and window), and the description largely repeats this information with minimal added meaning. With 100% schema coverage, the baseline of 3 applies; the description does not significantly enhance parameter understanding beyond what the schema already offers.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly answers the question it addresses. This specific verb+resource combination distinguishes it from sibling tools like polymarket_edges, which focus on current edges, and polymarket_arbitrage.

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

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

The description provides clear context for when this tool is relevant: 'a fresh wide edge and a 3-week-old wide edge are different trades' and 'the median lifespan is your competition clock.' However, it does not explicitly name alternatives or state when-not-to-use, so it misses the top score.

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

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

Annotations declare read-only, open-world, idempotent, and non-destructive. The description adds substantial context: mode requirements, defaults, clamps, output fields, per-leg details, and risk warnings like 'forced_directional_risk naming the legs most likely to strand you unhedged'. 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 lengthy but well-structured with REQUIRES, SINGLE-MARKET, BASKET, and USE THIS sections. Every sentence carries important information; no filler. It earns its length given the tool's complexity.

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

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

Despite no output schema, the description enumerates all return values for both modes (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, etc.), explains the meaning of size_usd in each mode, and warns about edge cases. It is fully self-sufficient for correct invocation and interpretation.

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 detailed parameter descriptions (modes, defaults, clamps). The description adds interpretive meaning beyond schema, such as 'size_usd interpreted as settlement notional S (shares per leg; each share pays $1)' and the auto-detection logic for basket side, enriching the schema without redundancy.

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 a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with specific verbs and resources. It distinguishes single-market and basket modes, setting it apart from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs to use before acting on polymarket_arbitrage signals or any polymarket_edges trade above ~$500, and explains why (theoretical edges are not capturable on thin books, partial fills create directional risk). This is clear when-to-use guidance with alternatives.

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

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

The description goes far beyond the annotations. It details specific behavioral traits such as the two operational modes, the compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0, or matched_pairs:0 with skipped_cross_type:0), temporal_alignment implications, and skipped_cross_type/subtype counters. It also warns that most pre-mapped topics return compatibility_warning today, setting accurate expectations.

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

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

The description is dense but well-structured, with clear sections for purpose, modes, response, and safety fields. It is longer than typical but justifies every sentence with important information. It is front-loaded with the core purpose and then logically expands. Slightly verbose, but appropriate for the tool's complexity.

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

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

Given the tool's complexity and absence of an output schema, the description fully compensates. It explains the response structure (leg-by-leg prices, spread[].top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and the meaning of counters. It also provides practical guidance on interpreting results, making it contextually 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?

While the schema already covers 100% of parameters with descriptions, the tool description adds substantial meaning beyond the schema. It explains how 'topic' auto-fetches matching events and how explicit 'kalshi_event_ticker' and 'polymarket_event_slug' override the mapped side. This clarifies parameter interaction and usage semantics, which the schema alone does not convey.

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

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

The description states a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on comparing the two venues. The two modes ('topic' and explicit identifiers) further clarify the tool's scope.

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

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

The description gives clear context for when to use the tool: to compare Kalshi and Polymarket prices for the same event. It also provides implicit exclusions, warning that spreads are only meaningful when bet shapes are equivalent and temporal alignment is true. However, it does not explicitly name alternative tools or state 'use this instead of X', so it falls short of fully explicit vs-alternative guidance.

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

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

Annotations already declare readOnlyHint and destructiveHint false. The description adds useful context about scoping ('anonymous IP, BYO key hash, or account ID') and the list-all behavior. It also notes the ecosystem relationship with remember/forget, providing beyond-annotation behavioral detail.

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

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

Three sentences front-load the purpose and then add illustrative examples and scope. No wasted words; every sentence contributes to understanding the tool.

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

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

With one optional parameter and no output schema, the description covers the tool's operation, use cases, scope, and sibling relationships. It could mention the return format of the saved value, but given the simplicity of a memory retrieval tool, the description is sufficiently complete.

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

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

The only parameter 'key' has full schema description coverage (100%), so the baseline is 3. The description repeats the schema's 'omit to list all keys' instruction and adds that the value was saved via remember, but does not introduce any format or constraint details beyond the schema.

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

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

The description opens with the exact action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly distinguishes the tool from its siblings (remember and forget) by stating the complementary relationship and the dual-mode behavior.

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 explains typical use cases with concrete examples ('user's target ticker, an address, prior research notes') and states the scoping to the agent's identifier. It does not explicitly list exclusions or alternatives, but the context is sufficient for an agent to know when to recall prior memories.

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 explicitly states that setting mark_read:true flags returned events as read, causing subsequent calls to return only newer events. This directly contradicts the readOnlyHint and idempotentHint annotations, which imply no side effects or state changes. This is a clear annotation contradiction.

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

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

The description is compact and front-loaded, using three sentences to cover purpose, return payload, filtering, mark_read semantics, polling suitability, and an alternative endpoint. There is no redundancy or unnecessary 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?

The description provides a complete picture of the tool's behavior: it states the return payload fields, explains filtering options, reveals the mark_read side effect, and gives an alternative access method. Even without an output schema, the return format is described. This is sufficient for an agent to use the tool effectively.

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 5 parameters with descriptions, so the baseline is 3. The description adds value by giving a concrete example for type ('sec_8k'), explaining the consequence of mark_read (next call shows only newer ones), and confirming the 'since' parameter uses ISO timestamps.

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 ('Pull') and clearly identifies the resource ('fired events from your subscription feed'), distinguishing this from sibling tools like list_subscriptions. It also specifies the source (evaluator-written alerts) and the scope (persisted feed), making the tool's purpose fully unambiguous.

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

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

The description provides explicit usage guidance: it notes that polling is fine and points to an alternative HTTP endpoint for scripts/dashboards, effectively giving a when-to-use vs. alternative. It also explains the mark_read behavior to clarify when to use read tracking.

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

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

Annotations already declare readOnly and idempotent, but the description goes further by detailing the exact sources (SEC EDGAR, GDELT→GNews fallback, USPTO), the rate-limit/5xx fallback condition, and the soft-fail due to PatentsView API sunset. This is substantial behavioral context beyond the annotations.

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

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

The description is detailed but every sentence carries information: examples, source fan-out, fallback behavior, date formats, return structure, and alternative tool. It is front-loaded with natural-language triggers and avoids redundancy. No filler.

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

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

Despite no output schema, the description explains the return format (changes[] grouped by source, total_changes, citation URIs). It also covers the alternative tool and edge cases like API sunset, making it complete for a complex tool with multiple integrations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful usage guidance: it clarifies the 'since' parameter with examples and a recommendation ('Use "30d" or "1m" for typical monitoring'), and reinforces that 'value' can be a ticker or zero-padded CIK. This practical context exceeds the schema baseline.

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

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

The description clearly specifies the tool's function: a change feed for a company over a time window, with explicit examples of queries. It distinguishes itself from the sibling 'entity_profile' by stating that tool is for static profiles, while this one focuses on recent changes.

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 alternatives: 'Use entity_profile instead when you want the static profile...' and clarifies the intended scenario (recent changes in a window). It also explains the fan-out behavior and fallback logic, giving users a clear sense of when this tool is appropriate.

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

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

Annotations only indicate idempotent, non-destructive, and non-read-only behavior. The description adds valuable context about scoping by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions, which goes beyond the structured annotations.

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

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

The description is compact yet information-dense, with the main purpose front-loaded. Each sentence adds necessary context: when to use, storage model, persistence behavior, and related tools.

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

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

For a simple two-parameter write tool with no output schema, the description provides complete guidance: usage triggers, scope, retention policy, and companion tools. No significant gaps remain.

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

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

The input schema already has 100% coverage with clear descriptions for key and value. The description reinforces key-value semantics and provides examples, but it doesn't add substantial meaning beyond what the schema already communicates.

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

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

The description clearly states the verb 'Save data' with the resource being memory for later reuse. It distinguishes itself from sibling tools recall and forget by explaining the pairing, and provides concrete examples like resolved ticker, target address, and user preference.

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

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

Explicit guidance is given: 'Use when you discover something worth carrying forward...' and it mentions pairing with recall and forget. However, it doesn't explicitly state when not to use this tool versus alternatives, though the context is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds significant behavioral context: graceful degradation of LEI/FIGI enrichment when sources are unavailable, cascading through multiple lookup endpoints, and explicit reporting of unresolved identifiers under an 'unresolved' field. 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 overly verbose (nearly 300 words). It includes internal implementation details like 'pipeworx://rxnorm/concept/{rxcui} citation' and 'cascades through several lookup endpoints' that are not necessary for the agent to decide whether to use the tool. While it front-loads the purpose, the later sections could be trimmed significantly without losing essential guidance.

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

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

Given the tool's complexity (multiple entity types, multiple data sources, graceful degradation, and ownership hierarchy), the description covers most important aspects: what each type returns, source fallback behavior, and how unresolved identifiers are communicated. It lacks a precise description of the response JSON structure, but the verbal description is sufficient for an agent to understand the output. No output schema exists, so the description carries the full burden.

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 both parameters described. The description adds substantial meaning: for 'type' it explains the two entity types and their output differences; for 'value' it gives accepted formats (ticker, CIK, ISIN, name) and special behavior (ISIN resolves to legal entity via GLEIF). This goes well beyond the schema's minimal 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: resolving a name to canonical identifiers. It provides multiple example queries ('What's the ticker for…', 'find the CIK for…') and explicitly says 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from sibling tools like entity_profile or compare_entities, which handle different aspects of entity data.

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

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

The description explicitly tells the agent when to use this tool ('Use FIRST whenever you have a name but need an ID') and lists supported types ('company' and 'drug'). It also explains that the tool replaces multiple manual lookups. However, it does not explicitly state when not to use it (e.g., if you already have an ID) or mention alternatives among siblings.

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

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

Description discloses that it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. It also notes the _apiKey requirement for anthropic. This goes well beyond readOnlyHint/idempotentHint annotations; no contradictions.

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

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

Two sentences: first states core action and mechanics, second provides context and use case. No fluff; front-loaded with primary purpose.

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 multi-entity comparison tool with 4 params and no output schema, the description covers operation, output fields, and use case. Annotations cover safety. Missing some detail on model behavior differences, but not critical given schema coverage.

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

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

Schema already covers all parameters (100% coverage), but description adds the semantic that the first entity is treated as the 'subject' for narrative while others are competitors. This nuance is not in the schema's entity description, adding valuable meaning.

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

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

Description uses specific verb 'Compare' plus resource 'AI visibility across multiple entities side-by-side', clearly distinguishing it from sibling ai_visibility_check which likely handles a single entity. It also mentions ranking and output, so purpose is 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 use case 'competitive AI-marketing audits' with example query. Does not explicitly name alternative tools or when-not-to-use, but the multi-entity vs single-entity contrast is implied through 'side-by-side' and 'your brand + N competitors'.

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 the annotations by disclosing degradation behavior ('Partial failures degrade gracefully'), timing expectations ('bundlephobia's first measurement on a new version can take 5-30s'), and the exact failure signal ('sources_failed will list it'). It also clearly states that the tool inherits read-only and idempotent behavior, consistent with the annotations, while adding operational context.

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

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

The description is information-dense yet well-structured. Each sentence serves a purpose: purpose and data sources, usage triggers, return fields, ecosystem limitation, and failure behavior. It is front-loaded with the core purpose and avoids redundancy, making every sentence valuable.

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

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

Given the absence of an output schema, the description compensates by enumerating the return summary fields and additional details like per-advisory links and alternative versions. It also covers edge cases (scoped packages, partial failures, timeout), making the tool's behavior fully predictable. This level of completeness is exemplary for a composite 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?

Schema description coverage is 100%, with package and version already clearly defined in the input schema. The description adds no additional parameter-specific meaning beyond restating the default behavior for version. Baseline of 3 is appropriate since the schema handles parameter semantics adequately.

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

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

The description opens with a clear, specific statement: 'Composite "should I add this npm package to my project" check in ONE call', immediately conveying the tool's function and scope. It further distinguishes itself from siblings by detailing the exact data sources (deps.dev, bundlephobia) and the types of checks performed, making it unique among the provided sibling tools.

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

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

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion criterion for non-NPM ecosystems, stating that PyPI/Maven/Cargo/Go fall under deps.dev:version directly, guiding the agent toward an alternative approach.

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 behaviors beyond the annotations: embedding model (BGE-base-en), windowing (500-char overlapping windows), and the 200K character cap with truncation and flagging. It also mentions the return format (passages with offsets and similarity scores), which is not covered by the output schema (none exists). No contradictions with readOnlyHint=true or other 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 information-dense but every sentence earns its place. It fronts the core purpose, then usage guidance, then technical details, and finally a pairing note. No filler or redundant repetition of schema or annotations. The structure is logical and 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?

Given the tool's moderate complexity (3 params, no output schema), the description covers all essential aspects: input semantics, use case, technical limits, return values, and relationship with sibling tools. It is complete enough for an agent to select and invoke correctly without additional 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 valuable context: it explains 'text' as a previously fetched record with examples (SEC 10-K body, article, tool result), and provides query examples ('supply-chain risk'). This goes beyond the schema's descriptions, elevating the score to 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 a specific verb+resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and contrasting with fetching the whole document. The purpose is unambiguous and well-scoped.

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

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

The description provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also names a complementary alternative ('Pairs with ask_pipeworx_grounded') and explains how it fits into a workflow, giving clear context for tool selection.

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

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

Beyond annotations (readOnly=false, idempotentHint=true), the description discloses the OAuth requirement, the return of the subscription id, the always-on feed, phone verification requirement, and the 10/day SMS cap. These are genuinely useful behavioral details that complement the annotations without contradiction.

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

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

The description is front-loaded with the core action, then systematically covers supported types and delivery channels. While it's lengthy, the tool's inherent complexity justifies the detail; every sentence serves a purpose, and the structure 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?

It covers the main function, return value, type examples, and delivery constraints, including the account requirement and feed consumption path. It omits webhook delivery (covered in the schema) and doesn't mention all five enum types, but the schema fills those gaps, so the description is complete enough for a tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds concrete examples for sec_8k, polymarket_edge, and fred_series, but these examples largely repeat what's in the schema's parameter descriptions. No significant new parameter semantics beyond the schema.

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

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

The description starts with 'Create a proactive monitoring subscription to a live-data event stream' — a specific verb and resource. It clearly distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation, and it states the return value (new subscription id).

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

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

It states a clear prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)'. It also describes how to consume the feed via recent_alerts or a registry URL, and gives concrete examples per type. It does not explicitly say 'use this instead of X', but the context and prerequisites are sufficient.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral context by explaining it returns dynamically generated category-bucketed examples from a live catalog, and that passing a topic focuses results, which is useful 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 front-loaded with example queries and quickly defines the tool's purpose. It is slightly longer than necessary but every sentence contributes meaning, balancing detail with 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?

For a simple tool with one optional parameter and no output schema, the description fully covers what it returns, how to invoke it, and when to use it. It even explains the value of the output (exact tool+argument shapes), making it complete for onboarding.

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

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

Schema coverage is 100% for the single optional `topic` parameter. The description adds examples like 'finance', 'pharma', 'betting' and clarifies the no-argument behavior for a full spread, but these are minor additions over the schema's own 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 states the tool answers 'What can I ask Pipeworx?' and returns category-bucketed example questions with exact tool+argument shapes. It clearly distinguishes from siblings by positioning it as the first stop for discovering capabilities, unlike more specialized tools like ask_pipeworx or discover_tools.

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

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

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call it with or without a topic. It also references meta-tools to learn from, giving clear usage context, though it doesn't explicitly name alternative tools to use instead.

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 reveals behavioral traits beyond the annotations, including ownership enforcement and the soft-delete mechanism (deactivated, not deleted). It also explains the relationship to recent_alerts, which is valuable context not present in the annotations.

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

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

Two sentences, front-loaded with the primary action, followed by relevant caveats. No filler or repetition.

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

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

For a simple one-parameter tool with annotations and no output schema, the description covers the action, the constraint, and the effect on historical data. It is sufficiently 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?

The input schema fully documents the id parameter, so the baseline is 3. The description adds the constraint that the id must correspond to a subscription owned by the caller, which enriches the parameter semantics beyond the schema.

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

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

The description uses the specific verb 'cancel' with the resource 'subscription' and specifies the identifier. It clearly distinguishes from sibling tools like subscribe and list_subscriptions by describing the inverse operation.

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

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

It states an important usage condition: ownership is enforced, so you can only cancel your own subscriptions. It also explains the deactivation behavior and points to recent_alerts for historical events, giving context on when this tool is appropriate. However, it does not explicitly name alternatives or exclusion scenarios, so it earns a 4 rather than 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses critical behavioral traits: the distinction between 'could_not_verify' (check failed, not evidence) and 'unsupported' (no source exists), the presence of verification_error{stage,detail} on failures, and the return structure (verdict, actual value with pipeworx:// citation, reasoning). It also explains the percent-delta tolerance mechanism and the fallback behavior for non-financial claims. This adds substantial value beyond annotations.

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

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

The description is dense but not bloated, with each sentence serving a purpose: example phrasings, usage trigger, routing logic, return values, and critical caveats. It is front-loaded with the most important user-intent signals. However, the list of verdicts and the explanation of error states could be considered verbose for a description that could have been shorter; still, the complexity justifies the length.

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

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

With no output schema, the description fully compensates by listing the return verdicts, the actual value with citation, and reasoning. It also explains error scenarios (could_not_verify, unsupported) and their proper handling. For a tool with only 2 parameters and no output schema, it covers the semantic space comprehensively, including edge cases and caller instructions.

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 with detailed descriptions for both parameters (claim and tolerance_pct), including examples and defaults. The tool description adds no new parameter-specific information beyond what the schema offers; it only mentions 'exact percent-delta math' which is related but not parameter-level detail. Thus the schema carries the burden, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'natural-language claim verification against authoritative sources.' It provides example user phrasings ('Is it true that…', 'fact check', etc.) and explicitly distinguishes itself from simpler tools by saying it replaces 4–6 sequential calls. The verb 'verify' and resource 'claim' are specific, and the scope is unambiguous.

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

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

The description gives explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details internal routing (SEC EDGAR fast path for company-financial claims, grounded pipeline for anything else), providing clear context on when the tool applies. However, it does not name alternative tools or explicitly state when not to use this tool, so no exclusions are given.

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