airquality

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

The description adds meaningful behavioral context beyond annotations: default model (Workers AI Llama-3.3-70b, free), BYO Anthropic key with direct cost, and per-model return structure. Annotations already declare read-only/idempotent, so the description complements rather than contradicts.

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

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

Three sentences, front-loaded with the main purpose, followed by defaults, return format, and use cases. No redundant words; 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?

For a read-only probe tool, the description covers the essential aspects: what it does, defaults, cost/API key handling, return shape ('per-model {score, confidence, signals, raw_response} + a combined view'), and typical use cases. No output schema exists, so the explicit return description fills that 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?

Schema coverage is 100%, and the description adds extra semantics: it clarifies the free default model, explains the BYO key cost implication, and ties _apiKey to Anthropic probing. This goes beyond the schema's parameter descriptions, providing richer meaning.

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

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

The description states a specific action: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It clearly identifies the resource, the metric, and the output, distinguishing it from sibling tools that handle general Q&A or competitor-specific 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?

Provides clear use contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly exclude alternatives or name other tools, but the context is specific enough for an agent to decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context beyond that: it routes to a large toolset, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. No contradiction with annotations exists.

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

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

The opening is strong and front-loaded, but the description is overlong and contains a garbled, duplicated tail ('Step up only when needed: ... use get_forecast? no maybe not') that repeats alternatives already stated and adds confusion. The structure breaks down near the end, making it less concise than it should be.

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

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

For a tool with no output schema, the description sufficiently explains return behavior (structured answer with stable citation URIs), provides six concrete examples, and gives routing alternatives. The only notable gap is the misleading tail about sports scores, which conflicts with 'sports' being listed as a valid domain earlier, but overall the definition is nearly complete.

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

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

Schema description coverage is 100%, with the canonical 'question' parameter described as natural language and all five aliases explicitly noted. The description itself adds no further parameter semantics, but the schema already fully carries the burden, so the baseline of 3 applies.

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

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

The description clearly states that ask_pipeworx routes factual questions to one of 5,767 tools across 1,506 verified sources and returns structured answers with stable pipeworx:// citation URIs. It explicitly differentiates itself from web search and names sibling tools (ask_pipeworx_grounded, deep_research, get_air_quality, get_forecast), so an agent can understand exactly what this tool is for.

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

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

The description gives explicit when-to-use triggers ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and directly names alternatives for other cases ('Use get_air_quality or get_forecast instead for a direct single-source point lookup'). However, the trailing garbled sentence about real-time sports scores ('use get_forecast? no maybe not') introduces contradictory routing guidance, preventing a perfect score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful context beyond those: candidate routing improvements can be active, none are currently active, and this is a full working router rather than a fallback stub. This clarifies the experimental nature and current 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?

Four sentences and every sentence carries weight: relationship to ask_pipeworx, current candidate state, usage guidance, and an explicit statement that this is a complete working router. No filler or redundant restatement of the schema or annotations.

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 an experimental router, the description covers the essential operational facts: it is fully functional, currently equivalent to ask_pipeworx, has the same arguments and response shape, and should be used when the newest routing is desired. The schema handles parameters, so an agent has enough 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 description coverage is 100%, and the schema already documents 'question' plus its aliases with helpful descriptions. The description only says 'same arguments' without adding new parameter-level semantics, so it stays at the baseline.

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

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

Clearly identifies itself as the beta/candidate variant of ask_pipeworx, a universal router with the same 5,767 tools, arguments, and response shape, and notes it currently matches ask_pipeworx exactly. The 'newest routing' phrasing conveys its function, though it relies heavily on comparison to ask_pipeworx rather than a standalone verb+object statement.

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 tells the agent to use it 'exactly like ask_pipeworx when you want the newest routing' and contrasts it against the stable router whose results decide merges. It names the sibling and provides a clear selection condition, but it does not explicitly state when to prefer the stable router instead.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds substantial context beyond that: it discloses the exact refusal reasons, the grounded extraction constraint, the extra LLM call cost, and what happens when data is missing or confusing. 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 information-dense but each sentence serves a purpose: defining the mode, contrasting with ask_pipeworx, detailing return and refusal shapes, and stating when to use it. It is front-loaded with the most important distinction and remains scannable.

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

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

There is no output schema, yet the description fully explains the return structure and refusal semantics. Combined with complete parameter schema coverage and explicit sibling differentiation, an agent has everything necessary to invoke the tool correctly and interpret its response.

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

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

The schema fully documents all six parameters, all of which are aliases for the same natural-language question. The description adds no additional parameter-level meaning, but with 100% schema coverage 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 a grounded, hallucination-resistant answer mode for high-stakes reads, with explicit success and refusal return shapes. It also distinguishes itself from ask_pipeworx by emphasizing extraction only from tool results and the refusal behavior when data doesn't directly answer.

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

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

Provides explicit guidance: use when answers will be quoted, cited, or acted on and facts must not be invented, and prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This makes the selection decision concrete and actionable.

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 annotations already declaring readOnlyHint=true and idempotentHint=true, the description goes far beyond by detailing behavior for edge cases: low-confidence matches suppress analysis fields, closed markets skip fan-out, wide spreads get tradeability flags, and cancellation-rule parsing with ev_impact. It also discloses news fallback mechanisms (_fallback_attempted) and resolution-rule risk. No contradiction with annotations.

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

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

The description is lengthy but densely structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). Every sentence adds unique operational detail. It is front-loaded with purpose and usage, and the advanced warnings are logically grouped, making it appropriate for the tool's complexity.

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

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

With no output schema, the description carries full responsibility for explaining return shapes, and it does so thoroughly: result.market, result.analysis, result.evidence, result.parent_event, news fields, and status codes. It also covers failure/safety paths (low-confidence, closed markets, wide spreads) and the resolver contract. This is complete 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?

The input schema already covers all parameters with descriptions (100% coverage). The description's parameter-related content (e.g., passing a slug/URL/question) mirrors the schema rather than adding new meaning. It does not explain depth or include_raw beyond what the schema already states. 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+resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It clearly distinguishes itself from siblings by focusing on full bet research (resolution, classification, data fan-out, comparison) as opposed to focused tools like polymarket_edges or validate_claim. The multiple input formats (slug, URL, question) are explicit.

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

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

The description gives explicit when-to-use guidance: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It provides concrete fan-out examples for different bet categories. However, it does not explicitly list when not to use it or name alternative tools for exclusion, 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?

The description discloses rich behavioral traits beyond annotations: it pulls data from SEC EDGAR/XBRL for companies and FAERS for drugs, handles off-calendar fiscal years correctly (AAPL Sep, NVDA Jan), sorts results by primary metric, and returns paired data with citation URIs. These details add substantial context on top of the readOnly/idempotent annotations.

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

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

The description is dense and well-organized, front-loading trigger phrases and core purpose. There is minor redundancy between 'ALWAYS PREFER over sequential single-pack lookups' and 'Replaces 8–15 sequential lookups,' but each sentence adds relevant value, so the length is justified.

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

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

With no output schema, the description still covers the return format (paired data + pipeworx:// citation URIs), sorting behavior, and type-specific data sources. For a tool with only two parameters and no nested objects, this is complete enough 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?

Even though schema coverage is 100%, the description enriches parameter meaning by explaining what each type='company' or type='drug' pulls, and provides concrete examples for 'values' (tickers vs drug names). This goes well beyond the schema's terse field descriptions.

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

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

The description explicitly states a side-by-side comparison of 2–5 companies or drugs in one parallel call, with concrete examples of user queries that trigger it. It distinguishes itself from siblings by naming 'sequential single-pack lookups' and preferring this tool for comparisons. The type-specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) clarify what the tool does.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a direct directive for when to use this tool versus alternatives. It also lists typical user phrasings like 'X vs Y' and 'which is bigger,' making the intended trigger conditions clear. This is strong guidance.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, but the description goes far beyond that by disclosing output composition (verbatim evidence, confidence, source, fetched_at, citation), the gaps[] behavior with 'never invented', contradictions[], citation resolvability, semantic excerpting, and expected latency per depth. It also exposes the account/payment constraint, giving the agent crucial operational context.

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

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

The description is dense and front-loads the most operationally critical facts (account requirement, alternative tool, structured-only scope). Every sentence contributes substantive information, but the opening paragraph is a long run-on chain of parentheticals and clauses that could be more scannable. It is appropriately sized for a complex tool, but not as crisp as it could be.

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

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

For a research tool with no output schema, the description is exceptionally complete: it covers authentication, alternative routing, depth semantics, output packet structure, citation/gap/contradiction behaviors, excerpting, and latency. An agent has enough context to select and invoke the tool correctly and to set expectations about what results will look like.

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

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

The schema already describes both parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond that: it explains how 'depth' changes the research behavior (quick/standard/thorough hop counts, gap-recovery, contradictions, paid tier) and clarifies that 'question' can be broad or multi-part. This is more than the schema alone provides, though it does not add format-level syntax for the question.

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

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

The description states a specific action — 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' — and explicitly distinguishes itself from open-web search. It also names the intended use case ('broad/multi-part questions over structured data') and contrasts with ask_pipeworx for single lookups, so an agent can tell it apart from at least the most relevant sibling without opening schemas.

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

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

The description gives concrete when-to-use versus when-not-to-use guidance: use ask_pipeworx if not signed in, use ask_pipeworx for a single lookup, and use deep_research for broad/multi-part structured-data questions. It also qualifies the account-tier requirement, so an agent can route correctly in different auth contexts.

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

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

Annotations already declare readOnly/idempotent, and the description adds that it returns top-N tools with names, descriptions, and full input schemas, and that results are callable without a second schema lookup. It also advises 'Call this FIRST' as a workflow. 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?

Three sentences starting with an action-oriented opener, followed by a domain list and return/usage details. The list is long but informative, and every sentence contributes to understanding the tool.

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

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

No output schema, but the description describes return format (top-N tools with names, descriptions, schemas, curated examples). It provides sufficient context for a discovery tool, covering purpose, usage, and 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%, with each parameter including descriptions and aliases for query. The description mentions 'top-N' but doesn't add parameter-specific details beyond the schema, so baseline 3 is appropriate.

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

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

Description starts with 'Find tools by describing the data or task,' clearly naming the verb and resource. It contrasts with sibling tools by being the meta-tool that locates them, listing specific domains to 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?

States 'Use when you need to browse, search, look up, or discover what tools exist' and explicitly recommends 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use and 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 mark this as readOnly/openWorld/idempotent/non-destructive, and the description goes well beyond that: it discloses the fan-out across multiple sources, return-field semantics, sources_used/sources_failed meaning, soft-fail behavior for the USPTO PatentsView sunset, and the fact that empty sections are real 'no data' rather than bugs. 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 it packs in necessary behavioral details, edge cases, and source lists. It is front-loaded with user intents and the main promise, and then systematically enumerates output sections. A more structured list or bullets would improve scannability, but every sentence contributes genuinely useful information.

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

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

Given the tool's complexity, the absence of an output schema, and the many sources and failure modes, the description is remarkably complete: it names all data sources, defines each return section, discloses soft-fail behavior, explains empty results, covers input resolution, and clarifies expected behavior for private companies. Nothing critical is missing for an agent 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 coverage is 100%, but the description adds substantial meaning: it explains that type='company' and type='ticker' behave identically, that value can be a ticker, zero-padded CIK, or company name, and that names resolve via SEC EDGAR. It also documents the private-company resolved:false behavior and the exact examples ('AAPL', '0000320193', 'Moderna').

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

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

The description starts with concrete trigger phrases and states the core action: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from single-pack SEC/XBRL/news lookups and aligns with the 'profile' title while specifying scope (US public company) and expected output structure.

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

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

It gives explicit trigger conditions ('Tell me about X', 'research Acme', 'brief me on Tesla') and an explicit preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also handles edge cases like private companies returning resolved:false and empty FDA sections being expected, which prevents misuse.

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

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

Annotations already include destructiveHint=true and idempotentHint=true, so the description need not repeat those. It adds context that the memory must be 'previously stored' and that the tool is for clearing 'sensitive data', which goes beyond the structured fields. It does not describe behavior for missing keys, but the idempotentHint covers repeatability.

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 concise sentences, front-loaded with the core action ('Delete a previously stored memory by key') and then usage guidance. No fluff or redundancy; 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?

For a simple one-parameter tool with full schema coverage and annotations for destructiveness and idempotency, the description provides sufficient context: it explains when to use the tool, names related tools, and handles the key semantics. No output schema is needed for such a simple deletion 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?

Schema covers the only parameter 'key' with full description ('Memory key to delete') and an example. The description adds no additional parameter semantics, but the schema already provides complete information, so baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It distinguishes from sibling tools like 'remember' (store) and 'recall' (retrieve) by explicitly naming them in the context.

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 conditions: use when context is stale, task is done, or clearing sensitive data. It names the siblings 'remember' and 'recall' and tells the agent to pair with them, effectively distinguishing when to use this tool versus the alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: it performs a network fetch, extracts specific page elements, and emits a ready-to-drop text blob, which goes beyond the annotation safety profile without contradicting it.

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

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

The description is three sentences, front-loaded with the primary action and audience, followed by process and use cases. Every sentence earns its place; no redundancy or filler.

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

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

For a two-parameter tool with strong annotations and no output schema, the description is comprehensive. It explains what happens (fetch, extract, emit), the output nature (single text blob), and where to use it (site-root/llms.txt), leaving no critical gaps 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% with both url and max_links having descriptions. The tool description adds no additional parameter-specific details beyond the overall purpose and output format, so the schema carries the parameter documentation burden as expected.

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

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

The description clearly states the verb 'Generate' and the resource 'llms.txt file', with specific scope ('for any URL'). It details the process (fetches page, extracts title/description/key links) and output format (standard llms.txt markdown), distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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 'Useful for' context listing three concrete scenarios (client indexing, own project drafting, competitor auditing), giving clear when-to-use guidance. It does not mention alternatives or when-not-to-use, but the context is strong enough to guide tool selection.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds value by specifying the return payload (AQI, PM2.5, etc.) and noting that the data is 'current', which is not present in annotations. No contradictions exist.

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

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

The description is concise, front-loading the action and purpose in the first sentence. It provides examples and return values in a compact two-sentence structure without unnecessary fluff. This is exemplary conciseness.

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?

Though a rich output schema exists, the description adds useful operational context like 'current' and 'US AQI'. The critical gap is the unsupported city-name input, which creates a completeness issue. For a simple tool, the description is mostly sufficient but not fully reliable.

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 provides 100% coverage with brief descriptions for latitude and longitude, so the baseline is 3. However, the description actively misleadingly claims city names are accepted, while the schema requires numeric lat/long. This undermines parameter clarity, so a lower score is warranted.

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 'Check' and resource 'air quality', clearly distinguishing it from sibling tools like get_forecast. It also lists the exact pollutants returned, reinforcing the purpose. The mention of alternate location formats does not obscure the core purpose.

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

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

The description implies usage when current air quality is needed, but it does not explicitly reference alternatives or exclusions. No when-not conditions are stated. The misleading city name suggestion could lead to incorrect usage, though this is more of a parameter issue.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by specifying the return content (hourly predictions, US AQI, PM2.5, PM10) and the temporal nature of the data, 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 two sentences, front-loaded with the core action and return data, followed by a concise use case. Every sentence earns its place with no unnecessary detail.

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

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

For a simple read-only forecast tool with full schema coverage, comprehensive annotations, and an output schema, the description adequately covers purpose, return values, and usage context. No critical information is missing for an agent to select and invoke this tool correctly.

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

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

The input schema provides 100% description coverage for all three parameters (latitude, longitude, days), so the schema already documents parameter semantics. The description does not add any additional parameter details beyond what the schema provides, which meets the baseline for full 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 function: 'Get hourly air quality forecast for a location' and specifies the returned data (US AQI, PM2.5, PM10). This distinguishes it from the sibling get_air_quality tool, which likely provides current conditions rather than a forecast.

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

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

The description provides clear usage scenarios: 'Use to plan activities or alert users to upcoming poor air conditions.' While it does not explicitly mention alternatives like get_air_quality, the forecast context and focus on upcoming conditions effectively signal when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds caller scoping and return fields, but the 'active' default is redundant with the schema's include_inactive parameter description. No significant behavioral traits beyond what annotations/schema already convey.

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

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

Two sentences with no fluff: purpose, return fields, and usage guidance all included efficiently and front-loaded.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage. It doesn't explicitly mention pagination or auth scope beyond 'caller's', but it's sufficiently complete given the tool's simplicity.

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

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

Schema coverage is 100% with a clear description for include_inactive. The tool description doesn't add parameter details beyond this, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb ('list') and resource ('subscriptions'), and distinguishes it from siblings like subscribe/unsubscribe by specifying it's for reviewing existing monitoring.

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

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

The description provides clear usage contexts: 'review what you're monitoring before adding more' and 'to find an id to cancel.' It doesn't explicitly name alternative tools or give when-not guidance, but the context strongly implies subscribe/unsubscribe 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 only say the operation is not read-only/idempotent/etc., but the description adds rich behavioral detail: filing without an account returns a claim_token that can be reused to poll status, daily rate limits of 5 per identifier, free usage, and the note that the team reads digests daily. It also warns users not to paste end-user prompts, which is valuable operational guidance. 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?

Although longer than average, the description is front-loaded with the core purpose, then branches into use cases, exclusions, claim-token behavior, and constraints. Every sentence carries actionable information; nothing is filler or repetitive.

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

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

There is no output schema, so the description itself must cover return behavior and outcome expectations. It explains the claim_token response, how to check resolution status, rate limiting, and the fact that feedback directly affects roadmap. Combined with the fully self-describing input schema, 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?

The input schema already documents all four parameters (type, context, message, claim_token) with descriptions, so the baseline is 3. The description adds extra value by explaining the claim_token round-trip workflow ('Filing without an account returns a claim_token; pass it back later...') and by advising users to frame feedback in terms of Pipeworx tools/packs, which clarifies how to fill `context` and `message`.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' giving a clear verb–resource pairing and distinguishing this from all sibling tools. It unambiguously identifies the tool as a feedback-reporting channel for Pipeworx tools.

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

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

Explicitly specifies when to use the tool (bug, feature, data_gap, praise) and, crucially, when not to use it: 'if the tool came from a different MCP server... file it with that server instead.' It also clarifies how to describe issues and how to use the claim_token later, leaving no ambiguity about invocation context.

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

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

The description discloses behavioral traits well beyond the annotations. It explains that the data is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. These details about data source, privacy, and caching are not present in the annotations and significantly enrich understanding. There is no contradiction with the readOnlyHint or idempotentHint.

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, front-loaded with the core purpose, followed by return details, use cases, and technical notes. Each sentence earns its place, and the 'Useful for' list is compact and informative. The length is appropriate for the tool's complexity, with no redundancy or fluff. It balances detail with readability.

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

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

Given the tool has only one optional parameter and no output schema, the description provides complete context. It explains what is returned (top tools, packs, call volume, and aggregated tuples), the data source, privacy, caching behavior, and use cases. With rich annotations already covering safety, the description fully covers the remaining behavioral and contextual aspects. The tool is simple, but this description leaves no gaps.

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

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

The schema already covers the single parameter (window) with a 100% description, including the tradeoff between shorter and longer windows. The tool description mentions the window options but does not add new meaning beyond what the schema provides. The return format (top tools, top packs, total call volume, (pack, tool, count)) is mentioned, but this is more about output than the parameter itself. Since schema coverage is high, 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 what the tool does: returns top tools, top packs, and total call volume over a recent window. It uses a specific verb 'returns' and identifies the resource (Pipeworx traffic), distinguishing it from siblings like discover_tools or ask_pipeworx. The scope is explicit with the window parameter and the aggregating nature. This is a precise, non-tautological statement of purpose.

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

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

The description provides a clear 'Useful for' list with three specific use cases: discovering hot data sources, confirming canonical tool choices, and aligning use cases. This gives explicit context on when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5. The guidance is practical and clear enough for an agent to decide.

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, but the description goes far beyond by disclosing internal filters: semantic anchor requires ≥0.30 Jaccard similarity, partition filter drops placeholder slugs, and fill check prices against live CLOB depth. It gives concrete thresholds (>3pp, 1000 shares/leg) and advises 'do not trade it' when realizable edge is non-positive. 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?

Despite being long, every section earns its place: the first sentence states core purpose, then each paragraph is labeled (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and adds critical decision-making detail. The response format is explicitly described, so the agent knows what to expect. The structure is front-loaded and highly scannable.

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

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

With no output schema, the description fully compensates by listing the response fields (opportunities[], gap_pp, partition_check details, etc.). It covers all edge cases: placeholder slugs, low-similarity pairs, and thin order books. Given the tool's complexity, the description is complete enough for an agent to invoke it correctly in all modes.

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

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

Although the schema has 100% parameter coverage, each parameter description is minimal ('Single-event mode...'). The tool description greatly enriches semantics: it explains what 'event' slugs look like (with examples) and that full URLs are accepted, and clarifies that 'topic' is a seed question for cross-event scanning. It also clarifies the behavioral difference between the two parameters, going far beyond the schema.

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

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

The description opens with a clear verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It further distinguishes between the three invocation modes (no args, event, topic), which sets it apart from any sibling tools. The description also names an alternative for custom sizing (polymarket_fill_risk), ensuring the purpose 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?

Explicit guidance is given for each mode: 'Call with NO args for a trending_scan...' and 'event (recommended for a specific market)' with concrete slug examples. The description explains when to use cross-event (topic) mode and how it catches patterns single-event misses, and even tells the agent when not to trade (realizable_edge_pp ≤ 0). This is model when-to-use/alternative guidance.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It discloses response structure (by_segment, fed_candidates, _diagnostics), model family details, placeholder-slug filters, exception handling (e.g., 'Fed bets surface here, excluded from ranking'), a 24h-move warning, and 1h caching behavior. This provides rich context about how the tool behaves, complements the annotations, and contains no contradictions.

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

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

The description is long but information-dense with no filler. It is structured top-down: core purpose, model families, response fields, knobs, diagnostics, and caching. Every sentence carries meaningful detail, and the text is organized with clear section markers and examples. This level of detail is justified given 9 parameters and complex output logic.

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 the absence of an output schema, the description fully specifies the top-level response structure, including segment names, nested diagnostics, and special notes (e.g., fed_candidates exclusion). It covers all model families, filter knobs, and edge cases (placeholder filters, funnel counters). The description is self-sufficient for an agent to understand what the tool returns and how to interpret it.

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

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

Although the input schema already has 100% description coverage, the tool description adds value by grouping parameters under 'TRADEABLE-EDGE KNOBS' and explaining the reasoning behind defaults (e.g., slippage rationale, 'Polymarket has zero trading fees as of 2024'). It also clarifies tricky semantics like min_partition_leg_kelly applying to per-leg Kelly rather than the parent basket level. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb (scan/return), a clear resource (Polymarket markets), and differentiates itself from siblings by emphasizing discovery of opportunities without paging hundreds of markets. The multi-model structure is outlined, distinguishing this from other Polymarket-related tools.

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

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

The description explicitly frames the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains what to expect and some tuning knobs. However, it does not explicitly state when NOT to use this tool or name alternatives (e.g., polymarket_arbitrage for a different purpose), so it stops short of a 5.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true), the description details history limits ('60-day snapshot TTL'), data gaps ('snapshots are written when polymarket_edges runs on a cache-miss'), and the signed meaning of edge_pp_net ('negative = SELL YES'). It also clarifies decay is computed from 'daily closes' not intraday. 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 lengthy but structured with Args/RESPONSE/LIMITS sections, and every section carries essential information. The response-format detail (_tracked[]/expired[]/snapshot_dates[]_) is necessary given no output schema, though the 'competition clock' metaphor is optional color.

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 telemetry tool with no output schema, the description covers purpose, args, response structure, trend categories, decay calculation, data availability caveats, and history bounds. It is fully self-contained and leaves little ambiguity 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 already documents both parameters with defaults/clamps (100% coverage). The description adds 'max 30' and 'snapshot family' context, but these merely restate or lightly elaborate the schema, so it stays at 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 opens with 'Edge persistence and decay telemetry' and explicitly states the question it answers ('how long has this edge existed and is it shrinking?'), clearly distinguishing it from sibling tools like polymarket_edges (raw edges) or polymarket_arbitrage. The verb 'answers' plus the resource ('daily polymarket_edges snapshots') makes the tool's specific value 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?

It positions itself as the historical/persistence counterpart to polymarket_edges ('built from daily polymarket_edges snapshots') and frames the key scenario: 'a fresh wide edge and a 3-week-old wide edge are different trades.' While it doesn't name alternative tools explicitly, the context makes when-to-use clear without being misleading.

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 indicate read-only and idempotent behavior, the description adds substantial depth: it explains that the tool 'walks the ladder,' returns specific metrics like vwap_fill_price and slippage_pp, and warns that partial basket fills 'convert an arb into an unhedged directional position.' These details go far beyond the annotations and clarify the tool's operational and risk behavior.

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

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

The description is long but information-dense; each sentence earns its place by covering modes, parameters, outputs, or risk rationale. However, the single-paragraph structure is less scannable than it could be; dividing into bullet points or sub-sections would improve readability without losing 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 takes on the full responsibility of explaining return values, which it does thoroughly for both modes (listing top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and basket-specific fields). It also covers the risk context and usage thresholds, making it complete for a complex tool.

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

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

While the schema covers 100% of parameters, the description enriches each one: it explains side values in both modes, notes the default for side in basket mode ('auto from partition sum'), and clarifies size_usd semantics ('max spend on buys, target proceeds on sells' vs 'settlement notional'). This is more nuanced than the schema's descriptions.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which clearly states what the tool does with a specific verb and resource. It distinguishes itself from siblings by framing the tool as a pre-trade validation step and explicitly naming polymarket_arbitrage and polymarket_edges as tools it should be used before. The two modes (single-market and basket) are also well described.

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 instructs to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' giving a clear trigger. It also explains the rationale ('theoretical overround on thin books is not capturable') and describes when basket mode is appropriate, making the usage context unmistakable.

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

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

Annotations already mark the tool as read-only, idempotent, open-world, and non-destructive. The description adds extensive behavioral context beyond that: compatibility_warning and compatibility_codes semantics, temporal mismatch and alignment-unknown meanings, the gross-versus-net spread fee disclosure, skipped leg-pair counters, and the explicit note that null temporal_alignment does not mean aligned. No contradiction with annotations.

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

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

The description is well-structured with labeled sections and front-loaded core definitions, but it is very long and somewhat repetitive. For example, temporal_alignment_unknown is explained both in the safety-fields code list and again in the top_spreads flags section. It is comprehensive rather than concise.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does so thoroughly: top_spreads_pp flags, skipped_unclassified, low_confidence_pairs, temporal_alignment semantics, fees_note, and skipped_cross_type/subtype counters. An agent has enough context to call the tool correctly and interpret its results safely.

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 examples and descriptions for all three parameters, so the baseline is 3. The description adds useful relational semantics: topic auto-fetches a pre-mapped event, explicit ticker/slug overrides the mapped side, and both modes run the identical matcher with the same disclosures. This goes beyond the schema's per-field comments.

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's resource and action: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also enumerates the two invocation modes. However, it does not explicitly differentiate itself from sibling tools like polymarket_arbitrage or polymarket_edges, leaving some of that distinction to inference.

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 strong in-tool usage guidance: two modes, how to choose between topic shortcuts and explicit tickers, and a clear warning that pre-mapped topics often return compatibility warnings and are not automatically tradeable. However, it never states when to use this tool versus sibling alternatives, so the when-vs-alternatives guidance is incomplete.

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 destructiveHint=false; the description adds scoping context ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual retrieve/list behavior, which goes beyond the safety attributes already provided.

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 serving a distinct purpose: action, usage rationale, and scoping/relations. There is no filler or redundancy, and the description is front-loaded with the primary behavior.

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-optional-parameter read-only tool with solid annotations, the description covers purpose, usage, scope, and relationships to siblings. Return values are implied by 'Retrieve a value' and listing behavior is explicitly explained, so no critical information 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?

Input schema covers the 'key' parameter with 100% description coverage. The description adds examples of key content (user's target ticker, address, research notes) and clarifies the omission behavior ('omit the key argument' to list), reinforcing and enriching the schema's meaning.

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

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

The description uses specific verbs 'Retrieve' and 'list all saved keys', clearly states the resource (values saved via remember), and distinguishes from siblings by referencing remember and forget. Concrete examples (target ticker, address, research notes) make the tool's function unambiguous.

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

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

It says 'Use to look up context the agent stored earlier' and provides a pairing workflow: 'Pair with remember to save, forget to delete.' This explicitly indicates when to use and names alternatives, giving clear guidance without 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?

The description explicitly states that setting mark_read:true 'flag[s] returned events read' and changes future call results, which is a state mutation. This directly contradicts the annotation readOnlyHint=true (and arguably idempotentHint=true when mark_read is used). This is an annotation contradiction.

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

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

Front-loaded with the action, and each sentence adds something (return payload, filtering, mark_read semantics, polling/endpoint note). Some redundancy between 'Pull' and 'Returns' and the extra endpoint URL are minor, so not quite a 5.

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

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

For a 5-param optional-parameter tool with no output schema, the description covers the return item shape, filter usage, mark_read behavior, and polling/alternate endpoint. It is largely complete, though the annotation contradiction undermines trust in its behavioral accuracy.

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

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

Input schema has 100% description coverage for all 5 parameters. The description adds examples and the mark_read side effect, but those are already present in the schema; it does not meaningfully reduce ambiguity beyond the baseline.

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

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

Opens with a specific verb and resource ('Pull fired events from your subscription feed') and explicitly describes what is returned (source, citation_uri, raw event payload). This clearly distinguishes it from siblings like list_subscriptions and recent_changes.

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

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

Gives clear usage context: it is for polling fired alerts, supports filtering by type/since, and notes that the same feed is available at a URL for scripts/dashboards. It does not explicitly exclude alternatives or mention sibling tools, but the context is sufficient.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds substantial behavioral detail: fan-out to three sources, GDELT-to-GNews fallback conditions ('rate-limited or 5xx'), USPTO soft-fail due to API sunset, and the output shape ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). No contradiction with annotations.

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

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

The description is a single dense paragraph, but it is front-loaded with natural-language invocations, then flows logically through sources/fallbacks, parameters, return shape, and alternative tool. Every sentence contributes new information without redundancy, making it appropriately sized for the tool's complexity.

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

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

Despite having no output schema, the description specifies the exact return structure and includes important context like source-specific failure modes (GDELT→GNews fallback, USPTO soft-fail). It also covers parameter usage and suggests when to use a sibling tool, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with each parameter described. The description adds value beyond schema by elaborating on `since` values ('Use "30d" or "1m" for typical monitoring'), providing ticker and CIK examples for `value`, and noting that `type` is only 'company'. This lifts the score above the baseline 3.

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

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

The description uses a specific verb phrase ('change feed for a company in the last N days/weeks/months') and anchors with common queries like 'What's new with X'. It explicitly distinguishes from the sibling 'entity_profile' by stating the difference between change feed and static profile, satisfying sibling differentiation.

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 a clear when-to-use context via example queries and explicitly states the alternative: 'Use entity_profile instead when you want the static profile...'. It also explains fallback behavior between GDELT and GNews, giving the agent context for expected results. This exceeds minimal 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?

The description adds valuable behavioral context beyond the annotations: key-value scoping by user identifier, persistent memory for authenticated users vs. 24-hour retention for anonymous sessions. This complements the idempotentHint and readOnlyHint annotations without contradiction.

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

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

The description is three sentences that efficiently cover the main purpose, usage context, and related tools. Every sentence earns its place with no redundancy or filler.

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

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

For a simple two-parameter tool with strong annotations, the description fully covers purpose, when to use, persistence behavior, and sibling relationships. No output schema is needed, and the description is complete enough for an agent to invoke confidently.

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 clear parameter descriptions ('Memory key', 'Value to store'). The description reinforces the key-value nature but adds no new syntax or format details beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Save data') with a clear resource ('data the agent will need to reuse later') and scope ('across this conversation or across sessions'). It also distinguishes the tool from siblings by naming its counterparts recall 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?

The description explicitly states when to use the tool ('Use when you discover something worth carrying forward') and provides alternatives ('Pair with recall to retrieve later, forget to delete'). This gives clear contextual guidance for tool selection.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description discloses important behavioral traits: ambiguity handling ('when a name matches more than one instrument it asserts nothing and returns figi_candidates'), explicit unresolved reporting ('an identifier that could NOT be resolved is stated explicitly under unresolved'), graceful degradation when GLEIF/OpenFIGI is unavailable, and internal cascading across lookup endpoints. It also explains the ISIN-to-LEI resolution path and non-equity coverage, giving the agent a full model of how resolution may behave.

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 appropriately structured with a front-loaded purpose, example phrases, SUPPORTED TYPES breakdown, and specific behavioral notes. Each sentence carries useful information for a complex tool, so the length is earned. It loses one point because the density could overwhelm an agent looking for a quick summary, and a brief 'what this returns' line at the top would improve scannability.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so exceptionally: it lists identifiers returned, labels by source, reports unresolved values explicitly, details ambiguity handling (figi_candidates), and covers graceful degradation. For a tool with this complexity, two parameters, and no output schema, everything an agent needs to call it correctly and interpret results is present.

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

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

Schema description coverage is 100% and the schema already provides strong guidance for both parameters, including the entity-name-only warning. The description adds meaning beyond the schema by mentioning additional acceptable inputs (ISIN), explaining cross-source resolution semantics (CIK + ticker + LEI + FIGI), and specifying what identifiers are returned for each type. This is more than the baseline 3 for fully covered schemas, but not maximal since some detail duplicates 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 concrete user phrasings ('What's the ticker for…' / 'find the CIK for…') followed by a precise statement of purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names the resource classes (company, drug) and the specific identifiers (CIK, LEI, FIGI, RxCUI), and the directive 'Use FIRST whenever you have a name but need an ID' clearly differentiates it from sibling tools like entity_profile and compare_entities.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID' and clarifies that this tool replaces 2-3 manual lookups. It also explains supported input forms and the entity-name-only rule for bonds. However, it does not explicitly name alternatives or state when NOT to use this tool (e.g., if you already have an identifier), leaving that inference to the agent.

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

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

Annotations already declare read-only and idempotent hints. The description adds behavioral context beyond that: it reveals that the tool internally calls ai_visibility_check, treats the first entity as the 'subject,' and returns a ranked list with specific fields (score, confidence, signal density). No contradiction with annotations.

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

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

The description is three sentences, front-loaded with the core purpose. Every sentence earns its place: method, use case, and return value. No fluff 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 no output schema, the description adequately explains what is returned (ranked list with score, confidence, signal density) and the context of use. It doesn't specify ordering direction or how to interpret confidence, but for a tool wrapping another check, the level of detail is sufficient and close to complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the semantic role of the first entity in the entities array (subject vs. competitors) and by framing the overall purpose. This extra nuance lifts it to a 4.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It further distinguishes itself by stating it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized, which clearly differentiates it from siblings like ai_visibility_check and compare_entities.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' with a concrete example question. It implies when to use this over single-entity tools, but does not explicitly state exclusions or alternatives, so it stops short of a 5.

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

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

Even with annotations declaring readOnly/openWorld/idempotent hints, the description adds significant behavioral context: it fans out across two services, degrades gracefully on partial failures, and warns that bundlephobia's first measurement can take 5-30 seconds with sources_failed listing timeouts. It also discloses the return structure and NPM-only limitation, going 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 dense and information-rich, with a logical flow: composite purpose, use case, return fields, ecosystem scope, failure handling. It is not as terse as the calibration high example, but every sentence serves a purpose and there is no repetition or fluff. The front-loading is excellent, starting with the core 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?

Given the absence of an output schema, the description thoroughly covers return values by listing the summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable) as well as per-advisory detail, links, and alternative versions. It also addresses latency, failure behavior, ecosystem scope, and version defaults, making it complete for this complex composite tool.

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

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

The input schema already provides 100% coverage with clear descriptions for both 'package' and 'version'. The tool description does not add further parameter-level meaning beyond what the schema states, so the baseline of 3 applies. The mention of 'new version' while describing latency is tangential and does not substantially enrich parameter semantics.

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

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

The description states exactly what the tool does: a composite 'should I add this npm package' check that fans out to deps.dev and bundlephobia. It uses specific verbs ('fans out', 'returns') and clearly identifies the resource (npm packages) and the data collected. It also distinguishes itself from siblings by highlighting its composite nature and NPM-only 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?

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', giving clear triggers. It also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This tells the agent when not to use this tool and what to use instead, satisfying the when/when-not/alternatives 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?

Discloses detailed behavior beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging, and return of character offsets and similarity scores. This gives the agent a clear model of what the tool does internally.

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 an immediate, clear purpose and every sentence provides distinct value—usage condition, pairing with a sibling, return format, and technical processing details. No filler or redundant restatement.

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 explains what is returned (top-N passages, character offsets, similarity scores), the input constraints (200K char cap), processing behavior (overlapping windows), and how it relates to a grounded workflow. This is complete for an agent to select and invoke the tool correctly.

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

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

The schema already covers all three parameters with 100% coverage, so the baseline is 3. The description adds contextual examples (SEC 10-K body, article, long tool result) and clarifies 'text you already pulled,' adding helpful meaning beyond the bare 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?

Description opens with 'Semantic search INSIDE a fetched record' and clearly identifies the resource (a fetched text) and action (semantic search). It explicitly distinguishes itself from ask_pipeworx_grounded by describing the scoped, passage-level search vs. whole-document grounding.

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 an explicit use condition: 'Use when the record is too big to cram into the prompt.' It also names a pairing with ask_pipeworx_grounded as an alternative workflow. However, it does not explicitly state when not to use the tool, so it stops short of a 5.

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

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

Annotations already cover safety/idempotency, but the description adds substantial behavioral context: account requirements, return of the subscription id, delivery channel details (always-on feed, optional email/sms), SMS verification and 10/day cap, and webhook behavior including the signing secret. This goes well beyond what annotations provide, giving the agent a clear picture of side effects and constraints.

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

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

The description is dense and front-loaded with the core action and return value. It uses compact examples and lists supported types and delivery options efficiently. However, it's a single long paragraph that could be structured into bullet points or separated into clearer sections, so it loses a point for readability.

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 three parameters, nested objects, and no output schema, the description covers all essential aspects: required authentication, supported subscription types with parameter examples, delivery channels with verification/caps, and how to retrieve fired alerts. It also mentions the return value (subscription id) and webhook signing secret, making it self-sufficient for an agent to invoke correctly.

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

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

The input schema already provides 100% parameter coverage with detailed descriptions for type, params, and delivery. The description adds some clarifying examples (e.g., item codes, topic, series_id) but most of that information is duplicated from the schema. Baseline of 3 is appropriate because the description adds marginal value beyond the schema.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream,' and even states the return value (new subscription id). This clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe, which handle viewing and canceling subscriptions.

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

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

The description clearly states when to use the tool (creating a subscription) and gives concrete prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist). It also explains how to consume the feed via recent_alerts or a public endpoint, but it does not explicitly contrast with list_subscriptions or unsubscribe for viewing/canceling, so it stops short of a full alternatives 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond these by detailing the output structure (category-bucketed example questions with tool + argument shapes), the live catalog data source, and the behavior with/without the topic argument. 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 longer than a simple one-liner, but every clause earns its place: example queries, core purpose, output details, argument usage, and prioritized guidance. It is front-loaded with user-oriented phrasing ('What can I ask Pipeworx?') and maintains a logical flow. Slightly verbose but well-structured, not tautological.

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

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

Given the tool has no output schema, the description fulfills the burden of explaining return values: category-bucketed example questions with exact tool+argument shapes. It also covers the key behavioral nuances (no-arg vs. topic arg, live catalog source, relation to meta-tools). The context signals (1 optional parameter, no output schema) are fully addressed; nothing important is left unexplained.

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 fully documents the 'topic' parameter with all possible values and the effect of omitting it. The description adds only a few redundant examples ('finance', 'pharma', 'betting') and the phrase 'to focus', which do not materially enhance the schema's already complete coverage. Per the rubric, a score of 3 is appropriate when schema coverage is high and the description adds minimal extra meaning.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point for users/agents who want to know what Pipeworx can do, returning category-bucketed example questions with the exact tool and argument shape. It uses a specific verb ('suggest questions') and resource ('Pipeworx'), and distinguishes itself from siblings by framing itself as the 'FIRST' tool to use when unfamiliar with the system.

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 and contrasts with the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.), giving a clear sense of when this tool is appropriate 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=false, destructiveHint=false, and idempotentHint=true. The description adds critical nuance: ownership enforcement ('only cancel your own subscriptions') and the non-destructive deactivation behavior ('deactivated, not deleted'). This explains the side effects beyond what annotations alone convey and aligns with them, with 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?

Two sentences, perfectly front-loaded with the action first, then constraints and side effects. Every sentence earns its place with no redundancy or filler.

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

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

For a single-parameter tool with no output schema, the description covers purpose, ownership, side effect, and points to recent_alerts for historical data. It is complete for the tool's complexity, and the absence of return value details is acceptable given the simple context.

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

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

Schema coverage is 100% with a clear parameter description ('Subscription id (uuid) returned by subscribe'). The description adds an ownership constraint on the id, reinforcing that the id must belong to the caller. This goes slightly beyond the schema, providing additional semantic meaning.

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

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

The description opens with 'Cancel a subscription by id', providing a specific verb (cancel) and resource (subscription), and immediately clarifies the input mechanism. This distinguishes it from sibling tools like subscribe (creation) and list_subscriptions (listing), 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?

It gives clear usage context: ownership is enforced and cancellation is by id, implying you should only use this for your own subscriptions. It also indicates the alternative for historical events (recent_alerts), though it doesn't explicitly state when NOT to use this tool versus alternatives. This is strong guidance but not fully explicit.

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

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

The description goes well beyond the annotations by explaining the two execution pipelines, the exact verdict values, the meaning of could_not_verify vs. unsupported, the presence of verification_error{stage,detail}, the pipeworx:// citation, and the performance benefit of replacing 4–6 calls. It also emphasizes that could_not_verify must not be treated as evidence, which is critical for callers.

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

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

The description is longer than average but well-organized: examples first, then routing, then return format, then critical caller warnings. Every sentence adds value, though some redundancy exists with the schema's parameter descriptions.

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

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

With no output schema, the description carries the full burden of explaining return values, which it does: verdicts, actual value with citation, reasoning, and error semantics. It also covers the two sub-paths and the open-world behavior, making the tool's behavior fully specified.

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 offers 100% coverage with detailed descriptions for claim and tolerance_pct, including the default cap and hallucination-detection guidance. The tool description adds only marginal context (e.g., exact percent-delta math) but does not materially expand parameter semantics beyond schema, so baseline 3 is appropriate.

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

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

The description explicitly frames the tool as natural-language claim verification against authoritative sources, with concrete query phrasings and a defined verdict set. This clearly distinguishes it from sibling Q&A tools by focusing on truth/falsity of claims.

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

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

It states when to use it ('whenever the agent needs to check whether something a user said is factually correct') and describes the dual routing for financial vs. other claims. However, it does not explicitly name alternative tools or state when NOT to use it, so it earns a 4 rather than a 5.

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