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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds valuable context about the tool's internal routing ('5,564 tools across 1462 verified sources'), that it fills arguments, returns citation URIs, and works on every tier. No contradictions with annotations.

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

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

The description is long but every sentence earns its place: it front-loads the critical 'PREFER OVER WEB SEARCH' directive, lists supported domains, gives concrete examples, and contrasts with siblings. A slight redundancy in examples and the tier statement could be trimmed, but overall it is efficiently packed.

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?

Considering the tool's complexity and lack of an output schema, the description fully compensates by describing the return value (structured answer with citation URIs), the routing behavior, and the alternative tools. It covers purpose, usage, and context sufficiently for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%; the 'question' parameter and all five aliases are fully described in the schema. The description adds example queries but no new parameter semantics, so it meets the baseline without exceeding it.

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 specifies a clear action: 'routes the question to the right one of 5,564 tools' and 'returns the structured answer with stable pipeworx:// citation URIs.' It also differentiates from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, making the tool's unique role unmistakable.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE', and gives trigger-phrase examples like 'what is', 'look up', 'find'. It also states when to step up to alternatives ('Step up only when needed...') and even excludes breaking news contexts, leaving no ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations by explaining that this is a live experimental variant, currently identical to ask_pipeworx, and that it is a full working router rather than a stub. This setup clarifies the experimental nature without contradicting annotations.

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

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

The description is a single paragraph but efficiently front-loads the beta status and core functionality. Each sentence adds meaningful context: the identical router comparison, current lack of active candidate, usage instruction, and safety reassurance. Slightly verbose but well-organized and free of fluff.

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

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

The description covers the tool's purpose, current runtime state, relationship to stable router, usage guidance, and response shape. It explicitly notes that there is no fallback and that it is a full working router, addressing potential concerns about beta limitations. Given the simple input schema and no output schema, this is sufficiently complete.

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

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

Schema description coverage is 100% with detailed descriptions for 'question' and its aliases. The description adds minimal parameter-level value, merely referencing 'same arguments' as ask_pipeworx, which assumes prior knowledge. Since the schema already fully defines the parameters, 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 identifies this as a beta version of ask_pipeworx, a universal router that accepts natural-language questions. It specifies the exact relationship to the stable tool and explicitly contrasts with sibling ask_pipeworx by noting the experimental routing improvements. The verb 'ask' is implied through the title and description, and the scope is unambiguous.

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

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

The description states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also provides context that results are compared against the stable router, indicating a testing purpose. It does not explicitly list exclusions or alternatives like ask_pipeworx_grounded, but the key decision between beta and stable is addressed.

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

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

The description reveals detailed behavioral traits beyond annotations: it returns {answer, evidence, confidence, source, fetched_at, refusal_reason:null} on success, or explicit refusal with specific reasons. It also discloses the extra LLM call cost. This goes far beyond the readOnly/openWorld/idempotent annotations, providing critical information about how the tool behaves and what it returns.

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

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

The description is detailed but every sentence contributes: it explains core functionality, routing, return structure, refusal reasons, appropriate use cases, and cost comparison. It's front-loaded with the essential purpose and well-organized, with no redundant phrases.

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 fully covers the tool's behavior and output structure, which is essential since there is no output schema. It details the success and refusal JSON shapes, explains that evidence is a verbatim quote, and clarifies the routing logic. It also places the tool in context with ask_pipeworx, covering trade-offs and use 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?

The input schema has 100% coverage—'question' is described with aliases (q, prompt, text, input, query). The description does not add parameter-specific semantics beyond what the schema already provides. It mentions the question concept but does not elaborate on nuances like language or formatting. Per guidelines, with high schema coverage the baseline is 3, and no extra value is added.

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 grounded, hallucination-resistant answering: it routes like ask_pipeworx but extracts answers only from tool results, with explicit refusal behavior. It also distinguishes itself from siblings (ask_pipeworx, ask_pipeworx_beta) by highlighting the grounded extraction and refusal mechanism.

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

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

Explicit usage context is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' This clearly states when to use this tool versus alternatives, including the cost trade-off (one 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 (readOnlyHint, openWorldHint, etc.) are consistent with description. Description adds extensive behavioral context: account/depth restrictions, return packet details (findings with evidence/confidence/source/gaps), no invented data, second-hop iteration, contradictions, and time expectations. 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 lengthy but well-structured: starts with critical account requirement and alternatives, then details capabilities, depth options, and limitations. Every sentence adds value, though it could be trimmed slightly without losing meaning. Acceptable 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?

Given complexity (2 params, no output schema, rich annotations), the description fully covers return format (findings packet with gaps), timing, depth behavior, source scope, citation handling, and excerpting. Leaves no critical aspect unexplained for agent decision-making.

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 both parameters, but description enriches beyond schema: depth is explained in detail (quick/standard/thorough and their hop behaviors), and question is described as flexible for broad/multi-part queries. Adds clarity on defaults and paid depth.

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?

Clearly states it performs grounded multi-source research across Pipeworx's 1462 structured data sources, decomposing questions into facets and routing to tools in parallel. It explicitly contrasts with ask_pipeworx (single lookup vs. multi-facet), making sibling distinction strong.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data; for single lookups use ask_pipeworx; for breaking news use ask_pipeworx. Also notes account requirements and alternative for unpaid tiers. No ambiguity.

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 safe read-only annotations, the description discloses behavioral traits: it 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF' in parallel, describes the patents API sunset with soft-fail behavior, and explains the GDELT→GNews fallback. This is valuable context not available from annotations alone.

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

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

The description is dense but well-structured: it opens with user intents, then states the primary purpose, lists data sources and return fields, and closes with input constraints. Though slightly long, every sentence conveys meaningful information and the critical 'ALWAYS PREFER' guidance is placed upfront.

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 lacking an output schema, the description explicitly lists the return fields, data sources, fallback behaviors, and input limitations. For a multi-source tool, this gives the agent complete context to decide when and how to invoke it correctly.

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

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

Schema already describes both parameters with 100% coverage. The description adds further semantic detail by giving concrete examples ('AAPL', '0000320193'), specifying zero-padded CIK format, and reiterating the 'names not supported' constraint. This exceeds the baseline for high schema coverage.

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

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

The description clearly states the tool's core purpose: 'full cross-source profile of a US public company in ONE parallel call' and enumerates the exact output fields (cik, recent_filings, fundamentals, patents, news, LEI). It also distinguishes itself from sibling tools by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.'

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: 'ALWAYS PREFER over chaining single-pack... when the user asks for a holistic view' and gives specific trigger examples. It also states when NOT to use it: 'names not supported (use resolve_entity first if you only have a name)'.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, 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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing the response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and the meaning of skipped_cross_type/subtype counters. It explains exactly when warnings fire and what they imply (e.g., 'no arb exists'). This rich behavioral context is essential given no output schema exists.

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

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

The description is long and dense, but the complexity of the tool justifies the length. It is structured with clear logical sections: definition, modes, response, safety fields, and warnings. Though it could be tightened (e.g., the warning paragraph is somewhat rambling), every sentence contributes operational insight and there is no 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 tool with no output schema, the description is remarkably complete. It covers the response shape (leg-by-leg prices, spread, compatibility_warning, temporal_alignment), explains warning conditions, and describes skipped counters. It also provides examples of topic values and explicit ticker formats. This is sufficient for an agent to correctly invoke and interpret the tool without external documentation.

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

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

Although the input schema provides 100% coverage for the three parameters, the description adds substantial meaning: it enumerates the valid topic values, explains how kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and clarifies interaction semantics. The description also implicitly documents that all parameters are optional (0 required), which helps an agent decide which mode to use.

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

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

The opening sentence clearly defines the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the resource (two prediction market venues) and the operation (computes spread), and differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparisons. The two modes (topic and explicit tickers) further clarify scope.

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

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

The description explicitly explains two usage modes: 'TWO MODES: (1) `topic` — 10 pre-mapped macro shortcuts... (2) explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings.' It also provides guidance on interpreting results, including warnings about non-equivalent bet shapes and temporal misalignment, and cautions that 'pre-mapped ≠ tradeable.' It lacks explicit mention of alternative tools, but the context is sufficient for proper 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=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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds significant behavioral context: explains graceful degradation when GLEIF/OpenFIGI are unavailable, cascading internal lookups, explicit unresolved identifiers, and source-labelling for each identifier. Nothing contradicts the annotations, and the description enriches agent understanding well beyond annotations alone.

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 common query patterns and a strong purpose statement. It covers multiple entity types with dense but scannable prose. Slightly long for a lookup tool – some details (e.g., 'degrade gracefully') could be more compact – but every sentence adds value, earning a 4.

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 tool complexity (cross-source identity resolution, two entity types, multiple fallback paths), the description covers all relevant behavior: supported types, identifier sources, graceful degradation, failure behavior ('explicitly under unresolved'), and the cascading lookup strategy. No output schema exists, but the description sufficiently describes return capabilities for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the resolution logic for each type (e.g., ISIN-to-LEI mapping for company, RxNorm citation for drug) and specifying input formats like 'ticker (AAPL)' – though the schema already provides those examples. The description compensates with cross-system context that helps an agent decide which value format to use.

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

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

The description opens with specific verb-object patterns ('resolve a user-spoken NAME to the canonical/official identifiers'), immediately clarifying what the tool does. It lists example user queries and explicitly distinguishes 'company' and 'drug' types with their respective identity systems. This clearly differentiates resolve_entity from siblings like compare_entities or entity_profile, which have distinct purposes.

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 advises 'Use FIRST whenever you have a name but need an ID' and explains the tool replaces 2-3 manual lookups, giving clear when-to-use guidance. However, it does not provide explicit when-not-to-use guidance or mention alternatives among the 30+ sibling tools for edge cases.

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

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

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.