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 the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context beyond this: it returns stable pipeworx:// citation URIs, routes across 5,529 tools, and works as a single fast call on every tier. While it doesn't mention failure modes or latency, the added details are meaningful and non-contradictory.

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

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

The description is long but deliberately packed with actionable guidance: trigger phrases, examples, alternatives, and output details. It is front-loaded with the most important directive ('PREFER OVER WEB SEARCH'), and while the length exceeds a minimal two-sentence format, every section earns its place. A slight redundancy exists between the trigger-phrase list and the opening directive, but overall it is well-structured.

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 open-ended nature and the absence of an output schema, the description thoroughly explains what to expect (structured answer with citations), how to use it (examples and triggers), and when to escalate. It addresses the key decision points for an agent and anticipates common misconceptions by naming alternative tools. The description is complete enough to invoke the tool 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?

The schema covers 100% of parameters, including a clear description of the 'question' property and its aliases (q, text, input, query, prompt). The description adds no additional parameter-level semantics; its example questions are mirrored in the schema's own examples. Baseline 3 is appropriate when schema coverage is high and the description does not compensate further.

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: routing factual questions to the appropriate specialized tool and returning structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and positions itself as the default entry point. The examples and trigger phrases further solidify its 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 explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), when-not-to-use ('Step up only when needed'), and names specific alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). It also gives concrete example queries, leaving no ambiguity about usage.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behavioral nuances: that candidate routing improvements are 'enabled live whenever one is under test', that currently no candidate is active (matching ask_pipeworx exactly), and that results are compared against the stable router to decide merges. This experimental and state-dependent behavior is not conveyed by annotations and adds significant transparency.

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

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

The description is compact yet information-dense, with four sentences each contributing unique value: identity, current status, usage guidance, and a clarifying note about not being a fallback. No redundancy exists, and the most critical fact (beta, identical) is front-loaded.

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

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

The description is fully complete for a beta router. It covers identity, current operational state, usage instructions, and relationship to the stable version. Since the response shape is stated to match ask_pipeworx, the lack of an output schema is adequately handled. All necessary context for correct invocation is provided.

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

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

The schema already covers all parameters with descriptions, including the 'question' field and its aliases, achieving 100% coverage. The description mentions 'same arguments' but does not add any additional meaning about parameter usage beyond what the schema provides. The baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states that this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling by noting candidate routing improvements are enabled during tests. The verb 'ask' and resource 'Pipeworx' are implicit, but the description effectively communicates the tool's role as a full router.

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 instructs: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router. It also clarifies that it is not a fallback but a working router, preempting potential confusion. This provides clear when-to-use guidance and implies the stable ask_pipeworx as an alternative for non-experimental use.

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

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

The description discloses significant behavioral details beyond annotations: it performs routing across 5,529 tools, fetches data, and extracts answers using only the tool result. It also details the refusal mechanism with specific refusal reasons and mentions the extra LLM call cost. Annotations (readOnlyHint, idempotentHint) are consistent and complemented by this 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 well-structured and information-dense. It starts with the core purpose, then the process, return format, usage guidance, and cost comparison. Every sentence contributes valuable context without redundancy or fluff, making it both concise and comprehensive.

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

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

Despite having no output schema, the description thoroughly explains the success and refusal return formats with example fields and refusal reason enum values. It covers the routing behavior, cost implications, and use cases, making it complete for a complex tool that could otherwise leave agents guessing about invocation and output.

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% because every parameter is an alias for 'question' with a clear description. The description adds no parameter-specific semantics beyond what the schema already provides, but it does not need to since the parameters are self-explanatory. Baseline 3 for high schema coverage is appropriate.

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

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

The description clearly identifies this as 'Hallucination-resistant answer mode for high-stakes reads' and explains the grounded extraction process. It explicitly distinguishes itself from ask_pipeworx with the same routing but a stricter answer-extraction mechanism, and its placement among siblings like ask_pipeworx_beta and validate_claim gives it a unique 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 explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' with concrete examples. It also names the alternative ('prefer ask_pipeworx for casual lookups') and highlights the cost trade-off, making the decision between siblings clear.

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

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

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?

The description discloses rich behavioral traits beyond the annotations: it returns explicit gaps[] when data is unavailable, never invents findings, provides citation_uri only when resolvable, returns contradictions[] at standard/thorough depths, semantically excerpts large records, and gives latency expectations. It is fully consistent with the readOnly/openWorld/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 long (250+ words) but every sentence carries significant information for a complex tool. It is front-loaded with account requirements and use-case guidance. Slight redundancy with the schema's depth descriptions prevents a perfect score, but the structure is dense and organized.

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

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

With no output schema, the description takes full responsibility for explaining return behavior. It covers the findings packet format (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), the hop field, citation_uri availability, semantic excerpting, and latency. It also addresses edge cases and alternatives, making it 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 provides 100% coverage with detailed descriptions for both 'question' and 'depth', including depth-level semantics. The description largely reiterates this information (e.g., re-angles gaps, chases leads) without adding new parameter-level meaning. Therefore, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: grounded multi-source research across 1,455 structured data sources, decomposing questions into facets and routing to 5,529 tools in parallel. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, stating it is best for broad/multi-part questions over structured data.

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

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

The description provides explicit when-to-use/when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also names alternatives and explains the account requirement, giving clear direction.

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

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

Annotations already 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?

The description discloses substantial behavior beyond annotations: it fans out to multiple sources (SEC, XBRL, USPTO, news, GLEIF), mentions the patents API sunset and soft-fail behavior, GDELT→GNews fallback, and returns specific fields. Annotations already indicate read-only, open-world, idempotent, non-destructive, and the description adds rich contextual details without contradicting them.

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

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

The description is a single dense paragraph that is front-loaded with the core purpose and example queries. Every sentence adds value (sources, return fields, limitations, fallback behavior), and there is no fluff or repetition. The length is justified by the tool's complexity.

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

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

Given the absence of an output schema, the description thoroughly explains return values: cik, company_name, recent_filings (with URIs), fundamentals (specific fields and sort order), patents (with sunset note), news, and LEI. It also covers limitations (names not supported, patents soft-fail), making it fully self-contained for an agent.

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

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

Schema description coverage is 100%, with both parameters (type, value) already documented in the schema including examples and the note about names. The description repeats these requirements but does not add significant new meaning 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 clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists example queries and explicitly differentiates from alternatives (e.g., 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'), making it distinct from sibling tools like resolve_entity or 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?

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies input requirements and fallback: 'Pass ticker ... or zero-padded CIK ... names not supported (use resolve_entity first if you only have a name).' This is clear 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?

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?

The description provides rich behavioral context well beyond the read-only annotation: it explains compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and skipped cross-type/subtype counters. It also discloses that pre-mapped is not synonymous with tradeable, setting clear expectations. 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 long but information-dense block, organized with bold labels (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence contributes to understanding the tool's behavior, though it could be slightly trimmed without loss. The structure aids readability despite the length.

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

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

With no output schema, the description fully compensates by spelling out the response format: leg-by-leg prices, matched spread, top_spreads_pp, compatibility warnings, temporal_alignment, and skipped counters. It covers edge cases and limitations, making the tool self-explanatory 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?

The description adds substantial meaning beyond the schema by explaining the two modes (topic vs explicit tickers), the full list of topic shortcuts, and how explicit parameters override mapped defaults. It clarifies the interaction between the three parameters and the response structure, which the schema alone does not convey.

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

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

The description explicitly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, naming the specific resource and operation. It clearly distinguishes itself from sibling tools by focusing on cross-venue comparison rather than single-venue analysis, and details two distinct modes (topic shortcuts vs explicit tickers).

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

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

The description explains when to use the tool by outlining two usage modes and providing a list of pre-mapped topics. It also warns that most pre-mapped topics are not tradeable and that real cross-venue spreads are rarer than expected, which guides appropriate use. However, it does not explicitly compare against sibling tools like polymarket_arbitrage, though context signals imply differentiation.

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?

Annotations declare read-only, idempotent, non-destructive, open-world. The description enriches this with operational details: identifiers are labelled by source, unresolved identifiers are explicitly listed, LEI/FIGI enrichment degrades gracefully when external services are down, and internal cascading replaces multiple lookups. This goes well beyond the provided hints.

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

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

The description is dense but effective, opening with query examples and a clear directive before organizing details per type. At ~180 words it carries a lot of necessary information; it could be slightly more structured (bullets), but no sentence is wasted.

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

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

There is no output schema, so the description must explain return behavior. It does so thoroughly: what identifiers are returned, how sources are labelled, how unresolved lookups appear, and what happens on partial external failure. The degradation behavior and internal cascade give an agent the full picture needed to set expectations without an output schema.

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

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

Schema already fully documents both parameters, so the baseline is 3. The description goes substantially further: it maps the enum value 'company' to accepted input forms (ticker, CIK, name) and enumerates the returned identifiers (CIK, ticker, LEI, FIGI), while 'drug' is tied to RxCUI/ingredient/brand and citation behavior. This adds meaning beyond the schema's one-line definitions.

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 realistic user queries and states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input,' naming a specific verb and resource. It enumerates supported types (company, drug) and the identifier systems (CIK, LEI, FIGI, RxCUI), clearly separating this from sibling tools like entity_profile or 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?

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also clarifies what input forms are accepted and notes that the call 'replaces 2-3 manual lookups.' However, it doesn't explicitly state when NOT to use the tool or name alternative tools, so not a 5.

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

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

Annotations already declare 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.