Weather

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond annotations: the BYO key model ('you pay Anthropic directly for those calls'), the default model, and the per-model return structure. No contradictions are 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 a compact, front-loaded paragraph that packs essential information (action, default model, key requirement, return format, use cases) without excessive fluff. It earns its length, though it could be slightly tightened.

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

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

With no output schema, the description compensates by explicitly stating the return format: 'per-model {score, confidence, signals, raw_response} + a combined view.' It also covers model selection and purpose. It lacks some operational details like rate limits or error handling, but overall is quite complete for its complexity.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds minimal extra semantics—e.g., explaining that the default model is free and that _apiKey incurs direct Anthropic costs. This is a small addition, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is specific with verb+resource. However, it does not differentiate itself from the sibling tool 'scan_competitor_ai_presence', so it lacks explicit sibling distinction.

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives a sense of use cases but does not explicitly exclude alternatives or mention when not to use it. It also explains model selection (default vs. Anthropic) which aids usage decisions.

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

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

The annotations already establish a read-only, open-world, idempotent profile. The description adds meaningful behavioral detail: it routes across 5,798 tools and 1,517 sources, fills downstream arguments, and returns structured answers with stable pipeworx:// citation URIs. It does not discuss failure or low-confidence outcomes, but the core observable behavior is clearly disclosed.

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

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

The description is longer than typical but front-loaded and information-dense: preference, behavior, triggers, examples, and guidance appear in a sensible order. Minor redundancy in repeating the web-search comparison and a slightly awkward final clause keep it from a perfect score.

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

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

For a single-parameter, read-only router with no output schema, the description covers input scope, examples, delegation behavior, and return format well enough to call the tool correctly. The only notable gap is guidance for choosing between ask_pipeworx and its beta/grounded sibling variants.

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

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

Schema coverage is 100% and the schema already documents the single natural-language 'question' parameter plus all aliases. The description adds trigger phrases and examples, but these reinforce rather than substantially extend the schema, so the baseline 3 applies.

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

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

The description clearly defines ask_pipeworx as a natural-language router for factual, current, or historical questions that returns cited structured answers. It is specific about the resource and behavior, but it does not distinguish ask_pipeworx from sibling variants ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

It explicitly opens with 'PREFER OVER WEB SEARCH', lists trigger phrases such as 'what is', 'look up', 'find', and 'current', and provides concrete example questions. It closes with 'START HERE for most questions' and even addresses the breaking-news edge case, making the when-to-use guidance unusually explicit.

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, and non-destructive hints. The description adds valuable context by disclosing the current state (no active candidate, last retired on 2026-07-26) and the experimental edge behavior, which exceeds what annotations convey.

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

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

The description is moderately long but front-loaded with the key beta relationship and includes necessary current-state and usage information. The final sentence about no fallback is somewhat redundant with 'full working router' but does reinforce the operational reality.

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 simple single-parameter schema, safety annotations, and the explicit statement that it is identical to ask_pipeworx, the description adequately covers behavior and current state. It does not define what the underlying router does, but this is an acceptable reference to a sibling 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%, so the schema fully documents the question parameter and its aliases. The description adds no parameter-specific meaning beyond noting 'same arguments' as ask_pipeworx, which is a reference rather than additional semantic detail.

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 is a beta version of ask_pipeworx, an identical universal router with the same 5,798 tools and response shape. It explicitly names the sibling it derives from, making its function and differentiation immediately apparent.

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

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

It gives explicit guidance to use it 'exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router. However, it does not explicitly state when NOT to use it, leaving the exclusion to inference from the beta/stable contrast.

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, the description richly explains the tool's behavior: it routes through other tools, only uses fetched data, returns exact refusal reasons, and never invents facts. This goes well beyond what readOnly/idempotent hints 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 but every sentence earns its place: purpose, mechanism, return shape, refusal reasons, usage guidance, and cost. It is front-loaded with the most important purpose and selection 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?

Despite having no output schema, the description fully documents the success and refusal return shapes. It also covers selection context, cost, and cautions against hallucination, leaving no critical behavioral or usage gap.

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 documents the question parameter with aliases at 100% coverage, so the description need not add much. It doesn't describe the parameter itself, but there is no gap for the agent to fall into.

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

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

The description clearly identifies a specific mode: a hallucination-resistant, grounded answer tool that extracts answers only from tool results. It explicitly contrasts itself with ask_pipeworx, so sibling differentiation is clear.

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

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

Explicitly says when to use it ('whenever an answer will be quoted, cited, or acted on'), when not to use it ('prefer ask_pipeworx for casual lookups'), and names the alternative. It even provides the cost tradeoff of an extra LLM call.

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

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

Even though annotations already declare readOnlyHint=true, destructiveHint=false, the description goes well beyond with critical behavioral disclosures: low-confidence short-circuit, closed-market handling, wide-spread liquidity warnings, GDELT fallback behavior, and the resolution-rule risk for void settlements. This is extremely rich, actionable context that would be invisible without the description. No contradiction with annotations.

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

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

The description is long but impeccably structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). The main purpose is front-loaded in the first sentence, and each subsequent section earns its place with essential operational details. There is no repetitive or filler content.

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

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

With no output schema, the description fully carries the burden of explaining return values. It comprehensively details result.market fields, analysis fields, evidence keying, match confidence contract, parent_event structure, news fallback fields, and status signals. It also covers edge cases like illiquid markets and closed/inactive markets, making it exceptionally complete for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining how the market parameter is resolved (slug, URL, or question text), giving concrete fan-out examples for different classifiers, and demonstrating the depth parameter's effect via 'quick' vs 'thorough' examples. It adds value beyond the schema without being fully exhaustive on every parameter behavior.

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 explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which clearly distinguishes it from siblings like get_forecast or polymarket_edges. The scope is well-defined: one-call family-out to category-specific data packs.

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

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

The description clearly specifies when to use the tool with direct query examples, and provides extensive guidance on how to interpret results (e.g., always inspect match confidence before trusting analysis). However, it does not explicitly name when-not-to-use or mention alternative tools, so it misses the full 'when-not/alternatives' bar for 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?

Adds context beyond annotations: data sources (SEC EDGAR/XBRL, FAERS, FDA), fiscal year handling, sorting by primary metric, paired data with citation URIs. Annotations already declare readOnlyOpenWorld, idempotent, non-destructive; no contradiction.

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

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

Despite length, every sentence adds value: triggers, core function, alternative preference, per-type details, and output format. Front-loaded with usage signals and structured logically, making it dense yet accessible.

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, description explains return format (paired data, citation URIs, sorted by metric), covers edge cases (off-calendar fiscal years), and sets expectations for scale (replaces 8–15 lookups). Complete for an agent to know what to expect.

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

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

Schema covers 100% of params, and description enriches meaning by detailing what each enum value does and giving examples for values. It also explains constraints and behavior (parallel call, sorting), adding value beyond 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?

Description clearly states the tool performs side-by-side comparison of 2–5 companies/drugs in one parallel call, with explicit trigger phrases and per-type data sources. It distinguishes from sequential single-pack lookups, aligning with alternatives like entity_profile.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving strong when-to-use guidance. Also clarifies the two entity types and what each returns, which helps the agent choose this tool over single-entity lookups.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description goes far beyond them: account/paywall requirements, 15-60s/~90s latency expectations, and detailed return semantics (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation, gaps[] for unanswered facets, contradictions[] for disagreeing findings). It also discloses honesty guarantees ('never invented') and the condition under which citation_uri is present, which materially affects how an agent should consume results.

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

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

The description is extremely dense but reads as a single run-on paragraph mixing auth, routing, mechanism, output format, hop semantics, and latency with no section breaks. Some depth mechanics ('standard' gap recovery, contradictions[]) duplicate what the schema's depth parameter already documents, and the editorial aside calling the tool 'Pipeworx's main workhorse' does not earn its place.

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

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

With no output schema, the description carries full responsibility for return-value disclosure, and it delivers: findings packet structure, hop field, gaps[], contradictions[], semantic excerpting, and the fetchable-citation guarantee. Auth, tiering, latency, and alternative routing are all covered. Minor omissions — error/rate-limit behavior and result-volume caps — keep this from a 5 for a tool this complex.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine value on top by tying depth levels to auth ('depth:"thorough" needs a paid plan'), latency bands, and hop behavior that the schema describes only abstractly. The question parameter is contextualized ('Broad/multi-part is fine — decomposition is the point'). No new syntax is introduced, but the pricing and latency constraints are real invocation factors beyond the schema.

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

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

The description states a specific verb and resource — 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' — and explicitly separates itself from open-web search ('this is NOT open-web search'). It names the closest sibling (ask_pipeworx) and gives concrete example questions, so an agent can unambiguously tell this tool apart from search_within, validate_claim, and the ask_pipeworx family.

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?

Routing guidance is explicit and front-loaded: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It states the intended use case ('Best for broad/multi-part questions over structured data') and discloses the paid-tier requirement for depth:'thorough', letting an agent avoid a doomed or unauthorized call.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and emphasizes 'ready to call directly, no second schema lookup needed,' which tells the agent the tool is a self-contained lookup. It doesn't overpromise or contradict annotations.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by usage guidance and return-value details. The long list of domain examples ('SEC filings, financials, revenue, profit...') is a bit verbose but provides concrete scope and helps the agent choose when to invoke this tool. Every clause adds context, so it is not wasteful.

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

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

Despite having no output schema, the description thoroughly explains what the tool returns (top-N tools with names, descriptions, and full input schemas) and that results are directly callable. It also gives workflow guidance ('Call this FIRST') which is a complete operational context. Combined with rich annotations, this is a self-contained description for an agent.

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

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

Schema description coverage is 100%—all parameters are individually described with aliases and examples. The description adds minimal parameter-specific detail beyond restating that you use 'natural language description' (already in the schema). It does not explain the difference between q, task, query, etc., but that is already handled by the schema. Thus baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from sibling tools by positioning itself as the discovery/meta-tool ('browse, search, look up, or discover what tools exist'), while siblings like get_weather or get_forecast are specific domain tools. The scope is well-defined with many concrete examples.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and gives a strong directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This contrasts with direct single-answer tools and implies a search-then-act workflow without needing to name 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?

Beyond the read-only/idempotent annotations, the description discloses fan-out architecture, soft-failure for USPTO patents, expected empty fda_products for non-biologic companies, and the meaning of sources_used/sources_failed. It also clarifies that empty sections are real 'no data' rather than bugs, which is essential non-obvious behavioral 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 long but front-loaded with purpose and example queries, and the dense detail that follows earns its place by explaining return fields, edge cases, and failure semantics. Some trimming is possible, but for a tool this complex the length is justified.

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

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

With no output schema present, the description compensates by enumerating all major return fields (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/sources_failed) and covering resolution behavior and expected no-data cases. An agent has enough context to invoke the tool and interpret its 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?

The schema already documents type and value clearly, and the description goes further by stating that type='company' and 'ticker' behave identically, that value can be a ticker, CIK, or name, and that names resolve via SEC EDGAR's company-name match. It also explains private-company resolution results, adding meaning beyond the schema fields.

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

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

The description opens with concrete natural-language triggers and states a specific action: building a full cross-source profile of a US public company in ONE parallel call. It clearly distinguishes the tool from piecemeal SEC/XBRL/news lookups by emphasizing the holistic single-call behavior, even if sibling tool names are not explicitly listed.

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

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

The description explicitly says to use this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view, giving a clear selection condition. It also explains private-company behavior, but it does not name alternative sibling tools like resolve_entity or compare_entities or state when those should be preferred.

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, so the description adds little beyond confirming deletion. It does not disclose edge cases like non-existent keys or permanence, but the annotations cover the safety profile adequately.

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

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

Two sentences, front-loaded with the action verb, and every clause adds value. No wasted words or redundancy.

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

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

For a one-parameter tool with clear annotations, the description fully covers purpose, usage timing, and related tools. No output schema needed for such a simple operation.

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 describes the 'key' parameter fully ('Memory key to delete'), and the description only repeats 'by key', adding no new semantic information. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It distinguishes itself from siblings 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?

It provides explicit when-to-use scenarios ('context is stale, task done, clear sensitive data'), but does not mention when not to use it relative to alternatives. The pairing with remember and recall is helpful but not a full exclusion list.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the agent knows this is a safe, non-mutating operation. The description adds valuable behavioral context by explaining that the tool fetches the page, extracts content, and emits a text blob, and it notes the output format. This goes beyond what annotations provide, though it omits edge cases like network failures.

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 well-structured, with a clear main sentence, a process sentence, and a use-case list. Every clause earns its place, with no redundant or vague language.

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

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

Given the tool's simplicity, the description covers the essential purpose, process, output format, and use cases. The annotations provide safety context. It would benefit from a note on potential edge cases, but for a tool of this complexity, it is largely complete.

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

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

Schema coverage is 100%, with both url and max_links fully described in the input schema. The description adds no additional parameter-specific meaning beyond reinforcing that url is the target, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file. It specifies the verb ('Generate'), the resource ('llms.txt file'), and the target ('for any URL'), and outlines the extraction and formatting steps. It also provides concrete use cases, making the purpose unmistakable.

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

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

The description lists three explicit use cases in the 'Useful for' section, giving clear context for when to use this tool. However, it does not explicitly exclude alternatives or name sibling tools, so it lacks the 'when-not' guidance needed for a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful context by specifying the return payload: 'daily high/low temperature (°F), precipitation probability + amount, conditions, sunrise/sunset' and notes 'Default 7 days.' It does not contradict annotations and supplements them with output format details.

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

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

The description is longer than average but every sentence earns its place: purpose statement, usage preference, multilingual examples, parameter guidance, return summary, default, and alternative tool pointers. It is front-loaded with the core action and flows logically. No filler or redundancy.

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

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

Given the tool's complexity (multilingual support, multiple location parameter modes, return fields, defaults), the description covers all bases: what it does, when to prefer it, how to pass location, what data it returns, and how it differs from siblings. The presence of an output schema reduces the need to describe return structure in detail, but the description still covers the essentials.

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 aliases and descriptions. The description adds value by summarizing the two input modes: 'Pass a city name or lat/lon.' It also reiterates the default day range. This helps agents choose between location and coordinate parameters without needing to parse every alias detail.

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: 'Weather forecast 1–16 days ahead for any location worldwide.' It clearly distinguishes from siblings by explicitly stating that get_weather is for 'RIGHT NOW conditions' and get_historical for 'historical climate.' The scope and action are unambiguous.

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

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

Provides explicit usage guidance: 'PREFER OVER WEB SEARCH' with concrete example queries ('weather this week in X', 'will it rain tomorrow in Y'), plus multilingual examples. Clearly states when not to use ('RIGHT NOW conditions' and 'historical climate' point to alternatives). This is a model of usage guidance.

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

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

Given annotations already declare readOnlyHint=true and destructiveHint=false, the description adds valuable context beyond these: data source (ERA5 reanalysis), temporal reach (back to 1940), default date range (last 30 days), and output fields (daily high/low, precipitation, conditions). It does not mention potential limitations like missing location handling, but the added context is substantial.

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

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

The description is four sentences, front-loaded with the core function and supported by source, output, defaults, and use cases. Every sentence contributes new information, and there is no redundancy or fluff.

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

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

The description is rich for a historical data tool: it covers data source, time range, defaults, output fields, and intended use cases. However, since all 11 parameters are optional, it does not clarify what happens if no location is provided (which could cause an error or unexpected behavior), leaving a minor gap in completeness.

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

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

The input schema has 100% description coverage for all parameters, including aliases and defaults, so the baseline is 3. The description adds a high-level summary ('Pass a city or lat/lon + date range') but does not provide additional per-parameter meaning beyond what the schema already documents.

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 providing historical daily weather data for any location, back to 1940, with a specific verb ('get') and resource ('historical daily weather'). It distinguishes itself from siblings like get_forecast and get_weather by emphasizing the historical aspect and referencing ERA5, making its purpose unmistakable.

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

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

The description explicitly lists use cases (e.g., 'what was the weather in X on date Y', climate baselines) and notes default behavior for missing dates. However, it does not explicitly contrast with get_forecast/get_weather or state 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 already declare readOnly, idempotent, and non-destructive behavior. The description adds value by specifying real-time live data, the exact weather fields returned (temperature, feels-like, humidity, wind, sky conditions, timestamp), and input formats (city or coordinates). 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 appropriately sized and front-loaded with the core purpose. Each sentence contributes value: real-time scope, preference over web search, multilingual support, input flexibility, and returned data. No filler or redundancy.

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

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

For a read-only tool with an output schema and comprehensive annotations, the description covers purpose, usage, multilingual scenarios, inputs, and key outputs. It does not need to detail return values since an output schema exists, and it provides enough context for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by providing concrete city examples ('Tokyo', 'London', 'Napoli', 'Austin TX') and summarizing the two main input modes (city name or lat/lon), making parameter usage clearer than the raw schema alone.

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

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

The description clearly states the tool provides real-time current weather for any location, with a specific verb ('get') and resource ('weather'). It distinguishes from siblings by emphasizing 'current' vs forecast/historical, and explicitly says to prefer it over web search for weather queries.

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

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

The description gives explicit usage guidance: 'PREFER OVER WEB SEARCH' for weather questions, and provides multilingual example queries to cover international usage. It clarifies when to use this tool (current weather) without overcomplicating, implicitly excluding forecast/historical use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying the caller scoping ('caller's'), the set of returned fields, and implicitly the distinction between active and inactive subscriptions. This is meaningful supplementary 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?

Two sentences: the first states purpose and return fields, the second provides usage context. No redundant information, front-loaded with the core action, and appropriately compact for the tool's simplicity.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It covers what is listed, the fields returned, how to use it, and the default behavior (implied by 'active'). Annotations cover safety, and the schema covers parameters, so 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?

The single parameter include_inactive is fully described in the schema with 100% coverage. The tool description does not add any additional semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also enumerates the returned fields, making the tool's 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?

Provides explicit when-to-use context: 'review what you're monitoring before adding more' and 'find an id to cancel'. This implies the alternatives (subscribe/unsubscribe) but does not name them directly, so it falls short of the highest bar.

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

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

With all annotations false (no safety hints), the description carries the full burden and delivers: it discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), token-based follow-up flow ('Filing without an account returns a claim_token... to read whether it was fixed'), and business cadence ('The team reads digests daily'). This covers side effects, constraints, and stateful behavior well 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 longer than minimal, but each sentence carries operational value: use cases, scope boundaries, message construction, token flow, rate limit, quota. The structure front-loads the core action and then flows through guidance. Slightly verbose (e.g., 'The team reads digests daily' is motivational rather than instructional), but this is a minor deduction.

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

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

Given there is no output schema, the description compensates thoroughly by explaining the return behavior (claim_token) and how to consume it. It covers all four parameters (type categories, context structure, message guidelines, claim_token usage), the tool's scope boundary, and operational constraints (rate, quota). This is complete for a feedback tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful guidance beyond the schema: for `message`, it instructs 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' For `claim_token`, it reiterates the usage pattern and emphasizes it can be used alone. This enriches parameter semantics, though the schema already documents the token workflow.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes feedback submission from sibling tools (ask/research/resolve tools) by defining its exact object (tools/packs served by this Pipeworx connection) and purpose (reporting issues, gaps, or praise).

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion and alternative: if the tool came from a different MCP server, 'file it with that server instead.' This is exemplary usage guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses the data source (CF analytics-engine), privacy guarantee (no PII), exact aggregated fields (pack, tool, count), and caching behavior (5min-1h). This is rich operational context that annotations alone do not provide.

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

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

The description is well-structured: a bold opening statement, a bulleted list of use cases, and a concise technical note on data source, privacy, and caching. Every sentence adds value, and it is front-loaded with the 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?

The description covers purpose, use cases, data source, privacy, caching, and parameter semantics. However, since there is no output schema, it would be helpful to specify the exact return format (e.g., structure of 'top tools' and 'total call volume'), though the aggregation is simple enough that this is a minor gap.

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 window parameter is fully covered in the schema (100% coverage), but the description adds semantic meaning by explaining the trade-off: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema enum descriptions and helps the agent choose appropriately.

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

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

The description clearly states what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This is a specific verb+resource+output, and it distinguishes itself from sibling tools like discover_tools by focusing on trending call volume from other agents.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tool choice, and checking use-case alignment. This gives clear context for when to use the tool, though it does not explicitly name alternatives or exclusions, which prevents a 5.

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

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

Annotations already mark readOnly/openWorld/idempotent, and the description adds substantial behavior: it discloses the semantic anchor threshold (≥0.30 Jaccard), partition filter behavior (drops placeholder slugs, null arb if >20% placeholder), and the fill-check pricing logic (realizable_edge_pp ≤ 0 means do not trade). This goes far beyond annotation safety flags.

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

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

The description is a single dense paragraph with semicolons, covering many details; while every sentence is substantive, the lack of visual structure (bullets/paragraphs) makes it harder to parse. It is front-loaded with the main purpose but still quite verbose.

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

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

Given no output schema, the description covers return fields (opportunities[], partition_check, fill_check) and important edge cases (placeholders, similarity threshold, thin legs). It also references polymarket_fill_risk for custom sizing, making it self-contained for typical use.

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

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

Schema coverage is 100%, and both params are already described. The description adds even more value by explaining what each mode does, providing concrete examples ('fed-decision-may-2026', 'Fed rate decision'), and clarifying the 'recommended' usage for event mode. This makes parameter selection clear.

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

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

The description opens with a clear verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from siblings by detailing the unique mechanisms and modes (trending_scan, event, topic) and explicitly points to polymarket_fill_risk for custom sizing.

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

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

It provides explicit usage guidance: no args for trending scan, event for specific markets, topic for cross-event scans, and recommends 'event (recommended for a specific market)'. It also gives an alternative: 'For custom sizing use polymarket_fill_risk', and explains when cross-event is valuable ('catches ... patterns that single-event misses').

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

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

Even though annotations already declare readOnlyHint and idempotentHint, the description adds extensive behavioral detail beyond them: how edge is computed net of slippage, the placeholder-slug filter, partition overround correction, the 24h-move warning, diagnostics for why segments are empty, and 1h KV caching. 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 extremely informative but not concise: a single massive stream of text with run-on sentences, parenthetical model details, sport-specific alpha values, and historical Run 8 context. Although it uses uppercase section labels, it would benefit from tighter paragraphing and removal of low-level implementation detail from the summary description.

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 thoroughly by specifying the top-level response shape (by_segment, fed_candidates, _diagnostics), listing per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and documenting filter/caching behavior. For a complex tool with 9 optional parameters, the description is fully sufficient for an agent to understand expected behavior.

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

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

Schema coverage is 100%, but the description adds important meaning around the parameters that the schema does not provide: it explains the 'tradeable-edge knobs' (min_liquidity, max_spread_pp), why min_kelly does not apply to partition arbs, and how min_partition_leg_kelly works per-leg. This goes well beyond the baseline for full schema coverage.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately distinguishes the tool from siblings like polymarket_arbitrage or polymarket_edge_tracker via the 'what should I bet on today' framing and by naming the three model families it scans.

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 usage context: it is built for daily opportunity discovery without paging hundreds of markets, and explicitly explains why Fed candidates are excluded from ranking. It does not name alternative sibling tools or explicitly state 'when not to use this tool,' so it stops just short of a 5.

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

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

Annotations already indicate read-only and idempotent behavior, so the description adds substantial context beyond that: the 60-day TTL, snapshot gaps (cache-miss writes), and that decay values come from daily closes not intraday. It also details the response structure, explaining what the agent should expect regarding tracked, expired, and snapshot_dates.

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

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

The description is long but well-structured with Args, RESPONSE, and LIMITS sections. It front-loads the purpose and uses a concrete example to convey the tool's value. Some prose (e.g., 'the latter is wide for a reason nobody is willing to take') is illustrative rather than strictly necessary, but it earns its place by conveying the analytical mindset.

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

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

With no output schema, the description thoroughly explains the return format (tracked[], expired[], snapshot_dates[]) and their semantics, plus critical limitations (TTL, snapshot gaps, slippage). It covers all aspects needed for an agent to use the tool correctly: purpose, args, response, and edge cases.

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% (both params documented). The description repeats the defaults and families ('days (lookback, default 14, max 30), window (snapshot family, default 1wk)') but adds little meaning beyond the schema's existing descriptions. The baseline of 3 applies because the description doesn't compensate or expand on the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It uses a specific verb+resource ('answers how long this edge existed...') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence and decay rather than current edge computation.

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

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

It provides explicit use cases ('Answers how long has this edge existed and is it shrinking?') and explains the relationship to polymarket_edges snapshots. While it doesn't name alternative tools explicitly, the context makes it clear this is for historical analysis. Missing explicit 'when not to use' guidance, but the purpose is well-defined.

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

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

Despite annotations already declaring readOnlyHint=true, the description adds substantial behavioral context: it walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), identifies thin legs, and warns that partial basket fills convert an arb into an unhedged directional position. This goes well beyond the annotation's safety profile and describes the tool's operational behavior.

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

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

The description is long but densely structured with clear labeled sections (SINGLE-MARKET, BASKET, USE THIS) and no filler. Every sentence conveys necessary operational detail—mode requirements, defaults, output fields, risk warnings—making it appropriately scannable for a complex tool.

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

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

For a tool with no output schema, the description thoroughly enumerates return values in both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, theoretical_sum, capture_ratio, thin_legs, etc.), plus the rationale and risk context. It fully equips an agent to select and invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds essential semantics: size_usd means 'max spend on buys, target proceeds on sells' in single-market mode but 'settlement notional' (shares per leg) in basket mode. It also explains side defaults and the auto-detection logic for basket mode, which are not present in the schema.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource+scope that clearly identifies the tool's function. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal generation.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why: theoretical overround on thin books isn't capturable, and partial fills create unhedged directional risk. It also names the exact modes (single-market vs basket) and when each applies.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds substantial non-obvious behavior: spreads are gross because Kalshi fees are unmodeled, pairing_unverified is always set, compatibility_codes can be non-empty even when matched_pairs > 0, null temporal_alignment means unknown rather than aligned, and unclassified legs are never paired. This goes well beyond what annotations alone communicate.

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 organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and front-loads the core purpose and mode choice. It could be tightened—the repeated insistence that both modes share disclosures and the extensive code catalog push it past minimal—but most sentences carry load-bearing caveats.

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 bears the burden of defining the response, and it does: leg prices, top_spreads_pp, flags, compatibility fields, temporal_alignment semantics, fees note, and skipped-leg counters. It is complete enough for an agent to call and interpret results correctly despite the tool's complexity.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description still adds real value by explaining that topic values are pre-mapped auto-fetch shortcuts, that the explicit ticker/slug override the topic-mapped side, and that both modes run the same matcher.

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 function—'Cross-venue spread between Kalshi and Polymarket for the same resolving question'—and explains what the number means. It distinguishes this tool by its cross-venue nature, though it never explicitly contrasts a sibling tool.

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

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

It clearly documents two invocation modes (pre-mapped topic shortcuts vs explicit ticker/slug overrides) and tells the agent which mode to use. It also warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable, but it does not explicitly route the agent away from sibling tools like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds useful behavioral context beyond annotations: the scoping to the user's identifier (anonymous IP, BYO key hash, or account ID) and the dual retrieve/list behavior. This goes beyond the annotation coverage.

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

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

Three sentences, each earning its place: the first states the core action, the second identifies use cases, and the third explains scoping and related tools. No fluff, front-loaded with the action. Ideal size for the tool's simplicity.

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, the description covers the two modes of operation, scoping, and relations to remember/forget. It doesn't describe behavior on missing keys, but given the annotations and schema clarity, this is a minor gap. The tool is easy to use with the information provided.

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 for the single parameter 'key', including the note 'omit to list all keys'. The description repeats this but adds no new semantic meaning beyond the schema. Per the rubric, baseline is 3 when schema coverage is high, and there's no extra parameter insight.

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 does two things: retrieves a saved value by key, or lists all keys when the key is omitted. It names the specific verb and resource (retrieve/list memory) and explicitly distinguishes itself from the sibling tools remember and forget.

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

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

Provides clear when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also explicitly pairs with remember and forget, giving direct alternative/complementary tool context, which satisfies the when/when-not requirement.

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

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds crucial behavior: mark_read:true flags events as read, affecting future calls, and it notes that polling works fine. It also describes the return payload fields and the alternative endpoint, providing rich context 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 three sentences with no fluff. It front-loads the main action, details the return fields, filtering options, and the mark_read behavior, plus provides an alternative URL—all in a compact, well-structured form.

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 5 optional params, no output schema, and strong annotations, the description covers the essential context: what the feed contains, how to filter, the mark_read side effect, polling friendliness, and an alternative endpoint. Nothing seems missing for a simple feed retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving a concrete example for 'type' (sec_8k) and explaining the side-effect behavior of 'mark_read' (flagging returned events read so next call shows newer ones). It doesn't elaborate on limit or unread_only, but the schema already describes those 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 clearly states the tool 'Pull fired events from your subscription feed' and returns 'the most recent alerts'. It specifies the resource (subscription feed) and the verb (pull), distinguishing it from siblings like list_subscriptions and recent_changes by focusing on fired events with source, citation_uri, and raw payload.

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

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

It provides clear context for when to use this tool (polling, retrieving recent alerts) and even suggests an alternative access method via a direct URL for scripts/dashboards. However, it doesn't explicitly contrast with sibling tools like recent_changes or list_subscriptions, so it lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, and the description adds important behavioral details: parallel fan-out to multiple APIs, GDELT-to-GNews fallback on rate limits/5xx, and USPTO soft-fail due to PatentsView sunset. It does not exhaustively cover error handling or ordering, but the additional context is valuable and non-contradictory.

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

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

The description is dense but well-organized, leading with user-friendly examples and then explaining sources, parameter formats, return value, and alternatives. Every sentence adds information, though the length is substantial for a tool with only three parameters; it earns its length by covering multi-source complexity.

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

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

With no output schema, the description compensates by clearly stating the return structure ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers parameter formats, source fallbacks, and an alternative tool, making it sufficiently complete for a read-only aggregator. Minor gaps like empty-result behavior or timeout handling are not critical given the transparency provided.

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

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

Schema coverage is 100%, providing baseline descriptions for all three parameters. The description enriches semantics with concrete examples: '7d', '30d', '3m', '1y' for `since`, ticker/CIK formats for `value`, and notes that `type` only supports 'company' today. These examples clarify usage beyond the schema.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' with specific sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes from entity_profile, noting to use that instead for static profiles, which sets it apart from a likely sibling.

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

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

It provides natural language triggers ('What's new with X', 'latest on Y') to signal appropriate use, and explicitly directs users to entity_profile when a static profile is needed regardless of window. This gives clear when-to-use and when-not-to-use guidance beyond the schema.

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 indicate idempotent and non-destructive, but the description adds meaningful behavior: key-value storage, scoping by identifier, persistence differences between authenticated and anonymous sessions, and 24-hour retention for anonymous. This goes beyond annotations without contradicting them.

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

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

Three sentences, all substantive and front-loaded. Every sentence adds a distinct piece of information: purpose, usage criteria, and behavioral details, with no filler or redundancy.

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

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

For a simple two-parameter memory tool with no output schema, the description covers storage semantics, persistence, scoping, and companion tools. It doesn't mention overwriting behavior for existing keys, but the idempotent hint partially covers that, and overall this is quite 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 covers 100% of the two parameters with clear descriptions, so baseline 3 is appropriate. The description adds general context about key-value storage but no extra parameter-level detail beyond what the schema already provides.

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

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

Uses a specific verb 'Save' with a clear resource ('data the agent will need to reuse later'), and distinguishes itself from siblings by explicitly mentioning 'recall' and 'forget' as companion tools. The scope ('across this conversation or across sessions') adds further clarity.

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

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

Explicitly states when to use ('Use when you discover something worth carrying forward') and gives concrete examples. It also specifies actions to avoid redundancy by pairing with recall/forget, giving clear context and alternatives.

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

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

The description adds substantial behavioral detail beyond the read-only/idempotent annotations: it discloses graceful degradation when LEI/FIGI enrichment fails, explains that ambiguous instrument matches return figi_candidates instead of asserting a result, and states that unresolved identifiers are explicitly listed. There is no contradiction with the annotations.

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

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

The description is front-loaded with the core purpose and structured around supported types, but it is very long and packs many behaviors into dense parentheticals. Nearly every sentence carries information, yet the level of detail makes it less lean than it could 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?

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it covers input variants, return behavior, candidate disambiguation, unresolved fields, ownership relationships, and failure-mode fallbacks. An agent has enough context to invoke the tool correctly and interpret its results.

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

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

The schema already documents both parameters well and even includes the entity-name-only caveat, so the baseline is 3. The description adds value beyond the schema by introducing ISIN as an accepted company input and explaining that an ISIN resolves to the legal entity that issued the security. That materially expands the agent's understanding of what value can contain.

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: resolving user-spoken names to canonical or official identifiers that other tools require as input. It gives concrete query examples, names the two supported entity types, and clearly separates this tool from profile- or comparison-oriented siblings like entity_profile and compare_entities.

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

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

The description gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also enumerates the supported types and the kinds of inputs each accepts, plus notes that one call replaces several manual lookups. It does not explicitly name sibling alternatives or give when-not-to-use cases, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context: it probes with ai_visibility_check, ranks by score, and returns confidence and signal density per entity, which is useful beyond the annotations. No contradiction.

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

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

The description is three sentences: what it does, how it works, and when to use it, plus what it returns. There is no unnecessary repetition or filler, and it is well-structured for an agent.

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

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

The tool has 4 parameters (1 required), no output schema, and moderate complexity. The description explains the return format (ranked list with score, confidence, signal density) and the use case, while the schema covers parameter semantics. This provides a complete picture 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 description coverage is 100%, with all four parameters documented (models, _apiKey, context, entities). The description doesn't add parameter-level detail beyond what the schema provides, but it does mention the workflow (probes each entity) that ties to the entities parameter. 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 'Compare AI visibility across multiple entities side-by-side' and details that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list. This clearly specifies the verb, resource, and outcome, distinguishing it from single-entity ai_visibility_check and generic compare_entities.

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

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

It explicitly labels the tool as 'Useful for competitive AI-marketing audits' and provides a concrete example ('does Claude know about us as well as our competitors?'). While it doesn't explicitly contrast with sibling tools, the mechanism ('Probes each entity with ai_visibility_check') implies the single-entity alternative and the comparison purpose is clear.

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

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

The description discloses important behavioral traits beyond the annotations: composite nature, graceful degradation on partial failures, potential 5-30s latency for bundlephobia's first measurement, and the sources_failed field to indicate timeouts. It also lists the exact return fields, giving the agent a clear picture of what to expect.

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

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

The description is a single dense paragraph but each sentence earns its place: purpose, use cases, return fields, ecosystem limitations, and failure behavior. It is front-loaded with the core purpose. Slightly long but 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?

Without an output schema, the description takes on the burden of explaining return values (summary block fields, per-advisory detail, links, alternatives). It also covers ecosystem scope, partial failures, and latency. The description is comprehensive for an agent to decide to use the tool and interpret results.

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

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

The input schema already provides 100% coverage: 'package' is described as an npm package name and 'version' as a specific version with a default. The description adds little beyond that—it mentions the package in the context of npm but does not introduce new semantic meaning for the parameters themselves.

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: a composite 'should I add this npm package to my project' check that fans out to deps.dev and bundlephobia. It specifies the exact resources (npm package, license, advisories, bundle size) and distinguishes itself from sibling tools, which are unrelated to dependency scanning.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides exclusions and alternatives, noting that non-NPM ecosystems fall under deps.dev:version directly. This is clear guidance on when to invoke the tool versus alternatives.

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

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

Annotations declare readOnlyHint and idempotentHint, but the description goes far beyond by disclosing return format (top-N passages with offsets and similarity scores), the embedding model (BGE-base-en), 500-char overlapping windows, and 200K char cap with truncation flagged. 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?

Three dense sentences: first states core purpose and inputs/outputs, second gives use case and benefit, third adds technical details and limits. No filler, front-loaded, 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?

Despite having no output schema, the description explains what is returned (passages with offsets and scores), the cap and truncation behavior, and how it fits with sibling tools. For a 3-parameter read-only tool, 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 covers 100% of parameters, so baseline is 3. The description adds value with concrete examples (SEC 10-K body), clarifies query as natural-language, and references 'top-N' for limit. This enriches understanding beyond the schema's already decent 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 performs 'Semantic search INSIDE a fetched record' with a specific verb+resource. It distinguishes itself from siblings by emphasizing it operates on text already pulled, and explicitly mentions pairing with ask_pipeworx_grounded, making its unique role obvious.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It names a companion tool (ask_pipeworx_grounded) and explains the workflow (fetch with gateway, ground over relevant passages), giving clear alternatives and context.

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

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

Annotations already indicate non-read-only, open-world, non-destructive behavior. The description adds crucial context: OAuth account required, anonymous/BYO cannot persist, SMS verification and daily cap, webhook HMAC signing, and auto-disable after 10 failures. This goes well beyond the structured metadata.

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

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

The description is long but well-structured: purpose first, then requirements, supported types, and delivery channels. Every sentence carries useful information, though it is dense and could benefit from light formatting for AI scanning.

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, it states the return value (new subscription ID). It covers all subscription types, delivery options, account requirements, verification steps, and retrieval methods. The description is fully complete for a tool of this complexity.

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

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

Schema coverage is 100%, giving a baseline of 3. The description further enriches each parameter with concrete examples (e.g., sec_8k with items, polymarket_edge with topic, fred_series with series_id) and explains delivery channel details, including webhook signature verification. This adds significant meaning beyond the schema.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream,' which clearly states the verb and resource. It also distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and returning a 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?

The description gives clear context for when to use the tool (creating subscriptions to specific live-data event streams) and outlines required account conditions and delivery channels. It does not explicitly name alternatives, but the purpose is unambiguous and aligns with its siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context beyond this: it reveals that results are drawn from a live catalog of thousands of tools, are category-bucketed, and include exact tool calls. It also explains the behavior with no args vs a topic. No contradiction found.

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

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

The description is longer than average but front-loaded with example queries that quickly convey the tool's nature. Each sentence adds useful information: the categories, the output format, zero-arg vs topic mode, and when to use it. It could be slightly trimmed but is well-structured and purposeful.

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 thoroughly covers what to expect: category-bucketed example questions, each with tool+argument shape. It explains invocation modes, the topic values, and the tool's role as an onboarding entry point. Combined with the full schema coverage, this is complete for the tool's complexity.

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

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

Schema coverage is 100% for the single optional 'topic' parameter, so baseline is 3. The description adds value by providing concrete example values ('finance', 'pharma', 'betting') and explaining that omitting it gives a cross-category spread. This goes beyond the schema's bare type/description.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions with exact tool+argument shapes, positioned as the onboarding entry point. It distinguishes itself from siblings by asserting 'Use this FIRST' and by referring to meta-tools. This is a specific verb+resource+scope, differentiating it from siblings.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the optional topic parameter's usage. However, it doesn't explicitly name alternatives or state when-not-to-use, so it's just short of a 5.

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

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

The description goes beyond annotations by explaining ownership enforcement, that the row is deactivated not deleted, and that historical events remain available via recent_alerts. This aligns with destructiveHint=false and idempotentHint=true without contradicting them.

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

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

Three concise sentences, each adding essential information: the action, the ownership constraint, and the deactivation behavior. No filler or redundancy.

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

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

For a simple single-parameter cancellation tool, the description covers the action, prerequisites (ownership), side effects, and how to access historical data afterward. The lack of output schema is not a gap here.

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

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

Schema covers the single parameter fully (id returned by subscribe). The description adds meaning by specifying that the id is a subscription id and that ownership is enforced, reinforcing which id to provide.

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

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

The description states a specific verb and resource: "Cancel a subscription by id." It clearly differentiates from siblings like subscribe and list_subscriptions, and the deactivation detail adds further clarity.

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

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

It provides clear context on ownership (only your own subscriptions) and the consequence (deactivation, history preserved). It doesn't explicitly state when not to use it, but the context strongly implies usage for stopping alerts while retaining history.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description richly discloses internal behavior: the SEC EDGAR fast path vs grounded pipeline, the meaning of each verdict, the critical caveat that 'could_not_verify' is not evidence, and that it consolidates multiple calls. This is far more than annotations provide.

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

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

The description is lengthy but every part earns its place, covering trigger phrases, behavior, return values, and error semantics. It is well-structured, front-loaded with usage triggers, and the 'IMPORTANT for callers' section adds crucial guidance without fluff.

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

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

With no output schema, the description fully covers return values (verdicts, evidence, reasoning), edge cases (could_not_verify, unsupported), and the tool's combinatorial advantage over sequential calls. It is complete enough for an agent to 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 description adds valuable context: it shows claim examples, explains tolerance_pct's purpose for hallucination detection, and clarifies the default behavior. This exceeds the baseline 3 for high schema coverage.

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

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

The description uses a specific verb-resource combination ('natural-language claim verification against authoritative sources') and provides concrete trigger phrases, distinguishing it from sibling tools like ask_pipeworx or compare_entities. It also states it replaces multiple sequential calls, which clarifies its unique niche.

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

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

It explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the two routing paths for claim types. It doesn't name alternative tools or provide 'when not to use' guidance, but the context is clear enough to merit a 4.

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