disease

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that the tool makes external API calls to LLM providers and that using Anthropic requires a BYO key with direct billing ('you pay Anthropic directly'). It also reveals the default model and free tier, adding cost and operational context.

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

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

Three sentences cover purpose, model options, and return structure without redundancy. The most important information appears first, and every sentence adds value.

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

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

The description specifies the return payload (`per-model {score, confidence, signals, raw_response} + a combined view`), which is essential since no output schema exists. It covers the core behavior adequately, though it could mention failure modes or rate limits.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful high-level context: the default is Workers AI (free), `_apiKey` is only needed when 'anthropic' is in `models`, and `context` helps disambiguate. This aids in parameter selection beyond the raw 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 action—'Probe one or more LLMs for what they know...'—and names the resource (business/brand/product/topic) plus the output (0-100 visibility score). It clearly distinguishes this from related siblings like scan_competitor_ai_presence by describing a scored, multi-model probe.

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

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

The description states explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not name alternatives or exclusions, but the context is clear enough for an agent to select this tool for visibility assessment.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds context beyond annotations by disclosing routing behavior ('fills arguments'), the stability of citations ('stable pipeworx:// citation URIs'), and performance/tier characteristics ('works on every tier, one fast call'). This enriches the structured annotations without contradicting them. It stops short of discussing timeouts, error behavior, or what happens on unmatchable queries, but these are minor given the strong annotation coverage.

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

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

The description is a dense wall of text with some redundancy: 'PREFER OVER WEB SEARCH' appears in caps, and there's repetition between the domain list and the examples. It front-loads the key directive ('PREFER OVER WEB SEARCH') which aids the agent, and the comparison-to-siblings is placed well. However, phrases like 'authoritative structured data with citations' and the extended example list could be trimmed. It's thorough but not concise.

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

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

For a router with a single free-text parameter, this description covers a lot: return format (structured answer with citation URIs), scope of queries (huge domain list), default-vs-escalation behavior (grounded, deep_research), and relevance signals. It lacks an explicit note on out-of-scope or ambiguous questions, but given the complexity of the tool ecosystem and the absence of an output schema, the description does a strong job of preparing the 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% (question parameter plus 5 aliases), so the baseline is 3. The description itself doesn't add deep parameter semantics—it doesn't discuss max lengths, language support, or disambiguation of ambiguous input. It does imply the question is free-form natural language with domain examples, but this maps directly to the schema's own 'natural language' description. Meets the baseline but doesn't exceed it.

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

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

The description opens with a specific verb+resource: 'Routes the question to the right one of 5,564 tools... returns the structured answer with stable pipeworx:// citation URIs.' It clarifies this is the default question-answering router for factual data and explicitly differentiates from siblings (ask_pipeworx_grounded, deep_research). This goes beyond a generic statement and tells the agent exactly what problem the tool solves.

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?

Exceptionally strong coverage of when and when-not to use. It gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), concrete domain examples (SEC, FDA, FRED, patents, weather, etc.), and explicit escalation paths: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This is textbook when-vs-alternatives 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 transparently notes its experimental nature, that no candidate is currently active, and that it currently matches ask_pipeworx exactly. This complements the annotations (readOnly, idempotent, non-destructive) by explaining potential behavioral differences.

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 somewhat redundant, repeating the 'identical' and 'matches ask_pipeworx' ideas, and the final sentence about falling back to nothing is slightly confusing. It conveys the essentials but could be tightened.

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

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

The description effectively explains the current state, the purpose (experimental routing), and what to expect, including the fallback behavior. Given the complexity of a router tool, this is sufficiently complete, especially since output schema is not applicable (identical to ask_pipeworx).

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 thoroughly documents the 'question' parameter and its aliases, leaving no ambiguity. The tool description adds no additional parameter context, so a baseline score 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 it is a beta version of ask_pipeworx, an identical universal router with the same toolset and response shape, differing only in routing improvements. This distinguishes it from sibling tools like ask_pipeworx and ask_pipeworx_grounded.

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

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

It explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router. It could be improved by specifying when not to use it, but the guidance is clear.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses the exact return shape on success ({answer, evidence, confidence, source, fetched_at}) and failure ({answer:null, refusal_reason}), enumerates refusal_reason values, and reveals the extra LLM call cost. This is rich behavioral context not available in 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?

Four dense sentences: purpose, mechanism, return format, and usage guidance. Every sentence earns its place, and the key differentiator ('hallucination-resistant') is front-loaded. The length is justified given the absence of an output schema.

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 explaining both success and refusal return structures, enumerating all refusal reasons, and outlining the end-to-end routing behavior. It also covers cost tradeoffs and high-stakes use cases, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% (all parameters are aliases for the same natural-language 'question' field), so the baseline is 3. The description adds no parameter-level detail beyond what the schema already provides; the aliases are fully documented in the schema.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling ask_pipeworx by emphasizing that it extracts the answer using ONLY the tool result and returns evidence. The specific routing mechanism ('picks the right tool from 5,564 across 1462 sources') adds concrete resource 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 states when to use ('whenever an answer will be quoted, cited, or acted on') and when to avoid ('prefer ask_pipeworx for casual lookups'), citing the cost tradeoff. Also names the sibling alternative (ask_pipeworx) and describes when the alternative is preferred.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses extensive behavioral details: parallel fan-out behavior, status codes like low_confidence_match and market_closed_or_inactive, response field contracts, resolution-rule risk, and safety short-circuiting. It even warns about recurring rules losses from void settlements, going far beyond annotations.

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

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

The description is long but every section earns its place: purpose, usage, classifiers, fan-out examples, response shapes, resolver contract, safety, and risk. It is front-loaded with the core purpose and structured with clear section markers, making dense information 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 explains return shapes (result.market, result.analysis, result.evidence), confidence scoring, parent event extraction, news fallback behavior, and blocking statuses. It covers edge cases like wide spreads, closed markets, and cancellation rules, 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?

Schema coverage is 100%, with detailed descriptions for market, depth, and include_raw already present. The description does not introduce additional parameter-specific semantics, so it gets the baseline 3 as the schema carries the burden.

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 with a specific verb ('Research') and resource ('a Polymarket bet') in one call. It distinguishes from siblings by explicitly targeting bet research and providing usage examples that differentiate it from other Polymarket tools like arbitrage or edge tracking.

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 'Use for' guidance with clear example queries ('should I bet on X', 'what does the data say about Y'). It does not list exclusions or alternative tools, but the context is clear and actionable, making it a solid 4, 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?

Beyond the readOnly/idempotent hints, the description transparently explains data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, sorting by primary metric, and the return format (paired data + citation URIs). This adds substantial behavioral context without contradicting any 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 densely packed with useful information and front-loaded with trigger phrases, making it easy for an agent to identify matching queries. It is longer than the typical description, but every clause serves a purpose, so it earns its 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?

For a tool with no output schema, the description sufficiently explains what will be returned, how results are ordered, and the benefit over multiple calls. It covers all essential aspects for correct invocation and interpretation of results.

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

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

The schema already documents both parameters at 100% coverage, but the description enriches the 'type' parameter by explaining exactly what each enum value retrieves and provides concrete examples for 'values'. This adds practical meaning beyond the schema's plain 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 names the action ('side-by-side comparison'), specifies the resource ('companies or drugs'), and defines the scope (2–5 entities in one parallel call). It also distinguishes from sibling tools by explicitly stating it should be preferred over sequential single-pack lookups.

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

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

Triggers and example phrasings are provided ('Compare X and Y', 'which is bigger', 'rank these companies'), and the description clearly states when to use this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives contextual details about entity types and what metrics each type retrieves.

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, destructiveHint=false. The description adds valuable context beyond annotations: account requirements, free tier limitations, parallel tool decomposition, response packet structure, citation behavior (always fetchable pipeworx:// URIs), gaps[] for unanswered facets, contradictions[] for standard/thorough, and expected latency. The only slight gap is not explicitly disclosing that results are grounded and not open-web, but the description actually states that positively. No contradiction. Given the rich annotations, a 4 is appropriate because the description meaningfully extends the safety/capability profile.

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, earning its length with multiple practical details (latency, citations, gaps[], depth semantics). It is front-loaded with the most critical caveat (account required, paid tier for thorough) and uses sentence-level structure to separate concerns. It is slightly overlong for an agent to parse quickly, but every sentence adds behavioral or selection value.

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

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

For a complex tool with 2 params, no output schema, and rich annotations, the description covers account prerequisites, sibling differentiation, expected latency, return-packet structure (findings, evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field), citation resolvability guarantees, and depth-tier semantics. This is complete enough for an agent to invoke correctly and set expectations.

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

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

Schema coverage is 100% and both parameters are documented in the schema. The description adds meaningful nuance beyond the schema: explains that question decomposition is the point, and elaborates on depth tiers' behavioral implications (gap recovery, contradiction scan, hop counts, paid plan requirement for 'thorough'). This exceeds the baseline 3 for full schema coverage, earning 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 clearly states a specific verb+resource: grounded multi-source research across Pipeworx's structured data sources. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx and clarifying this is NOT open-web search, and mentions breaking news alternatives.

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 (broad/multi-part questions over structured data), when-not-to-use (breaking/colloquial current news), and names alternatives (ask_pipeworx). Also explains depth tiers and the gap-recovery behavior, so an agent can select it correctly.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable behavior: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states each result is 'ready to call directly, no second schema lookup needed.' This is meaningful 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 three sentences with clear front-loading: purpose, usage context, and return behavior. The long list of data domains is informative but adds some length; still, each part contributes to the agent's understanding of scope.

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

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

The description covers what the tool does, when to use it, what it returns (including that results are directly callable), and the schema fully documents all parameters. With annotations providing the read-only/idempotent safety profile, there are no significant gaps for an agent to 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 has 100% description coverage, with query and its aliases (q, task, search, description) and limit all documented. The description adds no extra parameter semantics beyond the schema; the 'top-N' concept is already covered by the limit parameter's description.

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

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

The description opens with 'Find tools by describing the data or task,' which is a specific verb+resource pair. It lists concrete data domains (SEC filings, FDA drugs, etc.) and clearly positions this as a discovery tool, distinguishing it from sibling tools that perform specific tasks.

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

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

It explicitly states 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides strong situational guidance, though it does not name specific alternative tools; the 'not just one answer' clause implies when not to use it.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: parallel execution, fan-out across multiple sources, specific return fields, sorting of fundamentals, and the patents API soft-fail/fallback behavior. It also mentions the API sunset date, which is useful operational context.

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

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

The description is long but every part contributes: examples, the 'ALWAYS PREFER' guidance, source list, return fields, limitations, and input format. It is front-loaded with examples for quick understanding and uses structured lists. Not verbose enough to warrant a 3, but not as tight as a two-sentence description.

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

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

Despite lacking an output schema, the description enumerates all returned fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with specifics like 'up to 5' and 'LATEST 10-K'. It also discloses the patents API sunset and fallback. For a complex aggregating tool, this is comprehensive and sufficient for an agent to anticipate results.

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

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

Schema coverage is 100% for both parameters. The description adds value by providing concrete examples ('AAPL', '0000320193'), clarifying the zero-padded CIK format, and reinforcing that names are not supported (with a pointer to resolve_entity). It doesn't introduce new syntax beyond the schema but reinforces usage 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 as a 'full cross-source profile of a US public company in ONE parallel call' and provides concrete example queries. It distinguishes from siblings by explicitly recommending it 'over chaining single-pack SEC/XBRL/news lookups' and mentions resolve_entity for name-only inputs.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names an alternative (resolve_entity) for unsupported name inputs and notes the patents API limitation. This effectively directs the agent toward appropriate 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?

The annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate destructiveness. It adds context about clearing sensitive data and implies the memory must have been stored previously. However, it doesn't clarify edge cases like what happens if the key doesn't exist or whether the deletion is permanent beyond the annotation.

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 and well-structured: action first, then usage conditions, then sibling pairing. No unnecessary words.

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

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

The tool is simple with one parameter and rich annotations. The description covers what, when, and with which siblings. However, it does not describe the return value or behavior on missing keys, which could be helpful given no output schema. Slight gap.

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

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

The input schema has 100% coverage, describing the key parameter as 'Memory key to delete.' The description also says 'by key,' but doesn't add extra constraints or details. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' It uses a specific verb and resource, and it distinguishes from sibling tools like remember and recall by explicitly pairing with them.

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 conditions for when to use it: 'when context is stale, the task is done, or you want to clear sensitive data.' It also names the related tools (remember and recall), helping the agent choose among them.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so safety profile is covered. The description adds behavioral detail: it fetches the page, extracts specific elements, and outputs a text blob. This explains the method and output format beyond the annotations. It doesn't disclose edge cases (e.g., JavaScript-heavy pages) but provides adequate transparency given the annotation coverage.

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

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

The description is concise and front-loaded: the first sentence states the verb and resource, followed by process details and output format. The 'Useful for' list is structured and each item adds value. No wasted words, and the length is appropriate for the tool's simplicity.

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

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

The tool is simple, with schema covering parameters, annotations covering safety, and the description explaining the output format ('single text blob ready to drop at site-root/llms.txt'). It also provides use cases, making it complete for an agent to decide and invoke. No output schema needed since the output is described adequately.

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% for both url and max_links, with clear descriptions in the schema. The description itself does not add extra semantic detail beyond what's in the schema (e.g., it doesn't explain how max_links affects output). Baseline of 3 applies because the schema fully documents parameters.

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: generate a production-ready llms.txt file for any URL. It specifies the action (generate), resource (llms.txt), and the process (fetches page, extracts title/description/key links, emits markdown). This distinguishes it from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation rather than visibility analysis.

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 'Useful for' section provides concrete scenarios (getting a client's site indexed, drafting llms.txt, auditing competitor AI visibility). It implies when to use the tool but does not explicitly exclude alternatives or contrast with sibling tools. Clear context but not explicit 'when not to use' guidance.

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

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

Annotations already declare the tool safe (readOnlyHint, idempotentHint, destructiveHint). The description adds the list of returned fields (cases, deaths, etc.), but this is likely already in the output schema. It also gives example country codes, which is useful but not deeply behavioral. No additional traits like data freshness or rate limits are disclosed, so with annotations covering safety, a 3 is appropriate.

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 sentence that front-loads the purpose, provides illustrative examples, and lists the return fields. Every word 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?

The tool is simple with one parameter, a clear purpose, and an output schema exists. The description is complete enough for an agent to select and invoke the tool correctly, including examples and the type of data returned. 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?

Schema coverage is 100% and the single parameter 'country' is well described as 'Country name or ISO code'. The description reinforces this with examples (US, India, GB) but does not add significant new semantics beyond the schema. Baseline 3 is correct.

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: 'Check COVID-19 stats for a specific country'. It uses a specific verb ('check') and resource ('COVID-19 stats'), and the scope is defined by 'specific country'. The return list further clarifies the tool's function, and the example country codes distinguish it from sibling tools like get_global_stats or get_historical.

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 implies when to use the tool: when you need current COVID-19 stats for a single country. It does not explicitly mention alternatives or exclusions, but the context 'for a specific country' differentiates it from global or historical tools. This is a clear context without explicit when-not guidance, so a 4 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 readOnly, idempotent, and non-destructive hints. The description adds the specific output fields returned, providing useful context about the data snapshot 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 purpose, and every sentence adds value. No redundant or vague wording.

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 parameterless read-only tool with full annotations and an output schema, the description is complete. It explains the scope and the key returned metrics, leaving no significant gaps for an agent to select or invoke the 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 tool has zero parameters, and the schema already reflects this with 100% coverage. With no parameters to explain, the baseline of 4 applies; the description does not need to add parameter-level details.

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 retrieves worldwide COVID-19 totals, listing specific data categories (cumulative and daily cases, deaths, recovered, active). It distinguishes itself from siblings like get_country_stats by explicitly indicating the global scope.

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

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

The description implies the appropriate context—when worldwide aggregate COVID-19 numbers are needed—and the sibling names make alternatives apparent, though it does not explicitly state when not to use it or name alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, indicating a safe read operation. The description adds value by specifying that it returns 'historical progression of cases, deaths, and recoveries by date,' which clarifies the temporal nature of the data without contradicting annotations.

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

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

The description is concise, consisting of two sentences that immediately state the purpose and return content. Every word adds value 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?

The tool is simple, with only two optional parameters. The description, combined with the rich annotations and the presence of an output schema, provides sufficient context for an agent to understand what the tool does and what it returns. No additional information seems necessary.

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?

Both parameters (days and country) have descriptions in the schema, providing full coverage. The description's mention of 'for a country or globally' and 'daily' aligns with the schema but does not add significant additional meaning beyond what is already in the parameter descriptions.

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

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

The description clearly states the tool's function: 'Get daily COVID-19 timeline for a country or globally' with specific mention of cases, deaths, and recoveries. This distinguishes it from sibling tools like get_country_stats and get_global_stats, which likely focus on current statistics rather than historical progression, but it does not explicitly name those alternatives.

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 for historical timeline queries but does not explicitly state when to use this tool versus alternatives such as get_global_stats or get_vaccine_stats. It lacks explicit when/when-not guidance, so the agent must infer the use case from the word 'historical.'

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds behavioral context by specifying the return granularity (daily cumulative doses) and the 30-day window. No contradictions or further disclosures needed.

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 short sentences fully communicate purpose and scope with no redundant information. Front-loaded with the main action.

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 single optional parameter, rich annotations, and existence of an output schema (per context signals), the description covers the essential context: what it does, the scope, and time range. It lacks only explicit guidance on alternatives, but that's not critical for a simple read 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 schema provides 100% coverage with a clear description of the country parameter and the omission behavior. The description's mention of 'country or globally' mirrors the schema without adding new semantic detail, 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 it checks COVID-19 vaccination progress and specifies the return data (cumulative doses administered daily over past 30 days), which distinguishes it from general stats tools. However, it doesn't explicitly differentiate from sibling tools like get_country_stats or get_global_stats.

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 implies usage for vaccine-related queries by mentioning 'COVID-19 vaccination progress' and 'country or globally,' but provides no explicit exclusions or references to alternatives when historical or other stats are needed.

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=false, covering the safety profile. The description adds valuable behavioral context: it scopes results to the caller's subscriptions, lists the exact return fields, and implies read-only behavior. It does not contradict annotations.

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

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

The description is exactly two sentences, front-loaded with the core purpose, followed by return field details and usage guidance. Every sentence is informative and there is zero waste.

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

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

For a simple read-only list tool with no output schema, the description provides the return fields explicitly, covers scope, and gives usage context. It does not mention pagination or sorting, but given the tool's simplicity and rich annotations, it is sufficiently complete.

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

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

The input schema has one optional parameter (include_inactive) with 100% schema description coverage. The description does not mention the parameter, but the schema already explains what it does, so no additional value is needed. This meets 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 starts with a specific verb and resource: 'List the caller's active subscriptions.' It clearly distinguishes itself from sibling tools subscribe and unsubscribe by focusing on listing, and it enumerates the exact fields returned. This leaves no ambiguity about the tool's core function.

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

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

The description gives explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directs when to use list_subscriptions relative to subscribe and unsubscribe, providing actionable guidance and implied alternatives.

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

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

Beyond the annotations, the description discloses rate limits (5 per identifier per day), the claim_token flow for later status checks, that the tool is free and doesn't count against quota, and that the team reads digests daily. These are behavioral traits not captured in the structured annotations.

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

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

The description is long but every sentence adds critical information: purpose, triggers, exclusions, token mechanics, rate limit, and quota. It is front-loaded and well-structured, though denser than strictly necessary for a simple feedback 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?

Even though there is no output schema, the description explains the claim_token return mechanism and subsequent usage, covering the main return behavior. Combined with rate limits and usage guidance, it is sufficiently complete, though the exact response shape is not 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 provides 100% coverage for all 4 parameters. The description enhances this by clarifying the claim_token workflow (passing it back later to read status) and instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting user prompts, which adds practical meaning beyond schema descriptions.

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

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

The description opens with a specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates feedback types, clearly distinguishing this from sibling tools like ask_pipeworx or discover_tools. It is unambiguous about 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?

It explicitly states when to use the tool (bug, feature/data_gap, praise) and provides an exclusion: if the tool came from a different MCP server, file with that server instead. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it sources from CF analytics-engine, guarantees no PII, reveals the data shape (pack, tool, count), and discloses caching (5min-1h depending on window). This sets accurate expectations around freshness and privacy.

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

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

The description is moderately sized but every sentence earns its place: opening purpose, return types, three use cases, provenance, privacy, and caching. It is front-loaded with the core function and contains no filler.

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

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

In the absence of an output schema, the description still covers the response contents (top tools, top packs, total call volume), data source, privacy guarantees, and caching behavior. For a simple read-only trending tool, this provides complete context for an agent to select and invoke it correctly.

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

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

The schema already fully describes the 'window' parameter with enum values and semantics (shorter vs longer windows). The description repeats the window values but adds no new parameter-level meaning beyond what the schema provides. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume over a recent window. It differentiates from sibling tools like discover_tools by focusing on real-time agent usage trends rather than static tool discovery.

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

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

The 'Useful for' list provides three concrete scenarios (discovering hot data sources, confirming canonical tool choice, aligning with agent needs). This offers clear context for when to use the tool, though it does not explicitly name alternatives or provide when-not-to-use exclusions.

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

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

Despite readOnlyHint=true and no destructive annotations, the description goes far beyond by disclosing filtering behavior (PARTITION FILTER), similarity thresholds (SEMANTIC ANCHOR), and the FILL CHECK logic with the warning 'do not trade it' when realizable_edge_pp ≤ 0. This is rich behavioral context that annotations alone cannot convey.

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

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

The description is long but highly structured with uppercase section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that organize dense information. Every sentence adds value: front-loaded purpose, mode differentiation, user warnings, and output shape. No filler or repetition.

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

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

With no output schema, the description responsibly outlines the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and partition_check fields. It also covers filtering, edge cases, and trade-safety criteria, 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?

Schema coverage is 100%, but the description adds significant meaning: `event` is explained with concrete slugs ('fed-decision-may-2026') and URL acceptance; `topic` is clarified with seed question examples. It also describes the behavior triggered by each parameter, far exceeding the schema's basic 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 a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by detailing unique modes (event, topic, trending_scan) and the fill-check behavior.

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

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

Explicit guidance is provided: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also names an alternative ('For custom sizing use polymarket_fill_risk') and explains when one mode catches patterns the other misses.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses significant behavioral details: caching (1h at KV level keyed on knobs), the division of output into segments, the presence of diagnostics explaining empty segments, the exclusion of Fed bets from ranking, and the 24h-move warning. It also carefully explains that the tool is a read-only scan, reinforcing the annotations without contradiction.

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

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

The description is a long, dense block of text that could benefit from bullet points or subheadings for readability. While every sentence adds information, the sheer volume of detail (e.g., specific alpha values for sports, placeholder filter rules) makes it harder for an agent to quickly parse. The purpose is front-loaded, but the structure could be improved; it is not 'two sentences' or zero-waste.

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

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

With no output schema, the description fully bears the responsibility of explaining return values, and it does so comprehensively: by_segment structure, edge_pp_net, Kelly fractions, liquidity, diagnostics, and caveats like the reliable Fed signal warning. It covers edge cases (empty segments, stale data) and gives enough context for the complex 9-parameter tool to be used 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 100% of parameters with descriptive text. The description adds contextual semantics beyond the schema, such as how min_partition_leg_kelly applies per-leg instead of parent-level Kelly, the purpose of tradeable-edge knobs (min_liquidity/max_spread_pp), and the impact of slippage_pp on edge. This adds value beyond the schema, though the schema already carries a strong baseline.

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

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

The description opens with a clear, specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately distinguishes itself with the use case 'what should I bet on today' and positions it as a discovery tool that avoids paging through hundreds of markets, separating it from sibling tools like polymarket_arbitrage or polymarket_fill_risk.

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 'Built for' phrase explicitly states when to use the tool: quick discovery of betting opportunities. It also implies a contrast with more exhaustive search by noting agents can discover opportunities 'without paging hundreds of markets.' However, it does not explicitly name alternatives or exclusion cases, so it stops short of fully explicit when/not-to-use guidance.

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

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

Annotations already indicate a safe, idempotent read operation (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). The description adds substantial behavioral context beyond these: snapshot writes occur only on cache-miss, gaps in snapshot_dates mean no scan occurred, history is bounded by a 60-day TTL, and decay numbers come from daily closes of edge_pp_net rather than intraday data. This fully details the tool's behavior and limitations without contradicting annotations.

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

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

The description is dense and well-organized into labeled sections (RESPONSE:, LIMITS:). It packs a lot of necessary information (response fields, interpretation, data caveats) without fluff. While it is longer than a typical description, every sentence contributes functional value, and the structure aids scanning. Not a 5 because it could be slightly tightened, but it is far from verbose.

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

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

Despite having no output schema, the description thoroughly explains the response structure: tracked[] entries with time-series, first_seen, trend, decay_pp_per_day; expired[] with lifespan_days; and snapshot_dates[] with the cache-miss caveat. Limitations such as the 60-day TTL and daily-close basis are covered. Given the tool's analytical nature, this description provides complete context for an agent to understand inputs, outputs, and edge cases.

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

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

Schema coverage is 100% with clear descriptions for both days and window. The description goes further by explaining the default lookback (14, max 30), the snapshot family concept, and the response context (e.g., days is the lookback, window determines which snapshot series is read). This adds practical meaning beyond the schema's basic descriptions, so it earns above 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?

The description begins with a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers the core question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling polymarket_edges by focusing on historical persistence rather than current edge values. The term 'tracker' plus the detailed explanation make the tool's function unmistakable.

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

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

The description provides clear usage context: it is for assessing edge persistence and decay, with a concrete example comparing fresh vs. 3-week-old edges. It explains that expired opportunities reveal the competition clock. However, it does not explicitly name alternative tools for when to use something else (e.g., polymarket_edges for current snapshots only) or state when not to use this tool, so it falls short of full alternatives guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond this by detailing exact behaviors: walking the order ladder, returning verdicts, interpreting size_usd differently by mode, and warning that partial basket fills convert an arb into an unhedged directional position. This adds rich context without contradicting the annotations.

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

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

The description is long but every sentence carries unique information required for correct use. It is front-loaded with the core purpose and uses capitals to highlight mandatory mode prerequisites. While dense, the structure mirrors the tool's complexity; a slight reduction in run-on phrasing would make it perfect.

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 must enumerate return values, and it does so for both modes: single-market returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and verdict; basket returns theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg details, thin_legs, and max_clean_notional_usd. It also covers edge cases like forced_directional_risk and clamping, making it complete for a tool of this complexity.

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

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

Although schema coverage is 100%, the description substantially enriches parameter understanding. For example, size_usd is explained as 'max spend on buys, target proceeds on sells' in single-market mode and as 'settlement notional' with shares-per-leg semantics in basket mode. It also clarifies defaults, clamps, and the auto-detection for basket side selection.

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 pairing: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market vs basket) and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate its role.

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 this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains which mode to choose (market vs event) and why partial basket fills are dangerous, providing clear context for 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?

The description goes well beyond the readOnly/idempotent/open-world annotations by detailing the compatibility_warning conditions (matched_pairs:0 scenarios), temporal_alignment with aligned:false making spreads meaningless, and skipped_cross_type/subtype counters. It also discloses that participant pool differences can create 2-25pp price gaps, which is critical behavioral context.

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

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

The description is dense but every sentence earns its place, starting with a clear purpose, then modes, response format, and safety fields. Bold labels like 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS' improve scannability. There is minimal redundancy given the high 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?

Even without an output schema, the description fully covers what the agent needs to know: response structure (leg-by-leg raw probabilities, spread[].top_spreads_pp), safety fields and their meanings, and caveats about temporal alignment. Given the tool's complexity, this description is complete for correct invocation and expectation setting.

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 provides 100% coverage with descriptions for all three parameters, the description adds deeper semantics: the topic list with concrete enum values, the override behavior of kalshi_event_ticker and polymarket_event_slug, and how they interact with each other. This exceeds schema-only knowledge.

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

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

The description clearly identifies the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question, with specific verbs like 'Cross-venue spread' and concrete modes. It distinguishes itself from sibling tools like polymarket_arbitrage by explicitly naming both venues and emphasizing that it only reports spreads when bet shapes are equivalent.

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 describes TWO MODES: pre-mapped topic shortcuts and explicit ticker/slug overrides, with clear when-to-use guidance for each. It also warns that most pre-mapped topics currently return compatibility_warning and that pre-mapped ≠ tradeable, effectively setting expectations and exclusions for safe 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?

Annotations already declare the read-only, idempotent, non-destructive nature. The description adds behavioral context: scoping to the user's identifier (anonymous IP, BYO key hash, or account ID) and the ability to list all keys. This goes beyond the schema and 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, each serving a purpose: defining the action, giving use cases, and placing the tool in its family. It is front-loaded with the core behavior and avoids redundancy.

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

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

For a simple retrieval tool with a single optional parameter, the description covers the main functionality, scoping, and sibling relationships. It could be slightly more complete by describing the return format or error behavior when a key is not found, but this is not a significant gap given the annotations.

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 'key' parameter with a description. The tool description adds value by explaining the omission behavior for listing all keys and providing examples of what keys are used for (ticker, address, notes). It also clarifies the scoping of keys.

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 retrieves a value previously saved via 'remember' or lists all saved keys when the key is omitted. It distinguishes itself from sibling tools 'remember' and 'forget' by naming them and contrasting save/delete operations.

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

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

It explicitly says 'Use to look up context the agent stored earlier' and gives examples (target ticker, address, research notes). It names pairing with 'remember' and 'forget', clarifying when to use this instead of 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?

The description discloses that setting mark_read:true changes the feed state ('flag returned events read so the next call only shows newer ones'), which is a mutation. This directly contradicts the readOnlyHint=true annotation, which claims the tool does not modify state. Since the description contradicts the annotations, a score of 1 is required regardless of the description's own 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 three sentences, front-loaded with the primary action, and each sentence earns its place. It covers returns, filtering, state changes, polling, and an alternative access method—all without fluff. Excellent density and structure.

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 5 parameters, no output schema, and useful annotations, the description covers essential context: what events are returned, their fields, filtering, state-change behavior, polling suitability, and an alternative feed URL. It is thorough enough for an agent to invoke the tool correctly without additional guidance.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful value beyond the schema: it gives a concrete filter example ('sec_8k'), explains that 'since' is an ISO timestamp, and elaborates on the mark_read side effect. This extra context enriches parameter understanding without being redundant.

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: 'Pull fired events from your subscription feed.' This clearly distinguishes it from siblings like `recent_changes` or `list_subscriptions`. It also specifies the return content and filtering capabilities, making the purpose unambiguous.

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

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

The description provides solid usage context: it explains filtering by type and since, the mark_read behavior, and explicitly notes that polling works. It also offers an alternative endpoint for scripts/dashboards. However, it does not name sibling tools as explicit alternatives, so the 'when vs alternatives' is only partially covered.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive hints. The description adds substantial behavioral context: fan-out to multiple sources, fallback logic (GDELT preferred, GNews when rate-limited or 5xx), PatentsView API sunset causing soft-fail, and the return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). 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 dense but every sentence serves a purpose: example queries, source list and fallbacks, parameter formats, return structure, and alternative tool. It front-loads the most actionable info (what the tool does, example queries) and keeps parenthetical details compact. Despite its length, it is efficiently structured for a complex tool.

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

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

For a tool with three parameters, multiple data sources, and no output schema, the description is exceptionally complete. It covers return format, parameter semantics, fallback behavior, rate-limit handling, and a clear sibling distinction. The only minor gap is the exact shape of each change item, but the summary of the return structure suffices.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining `since` accepts ISO dates or relative shorthand ("7d", "30d", "3m", "1y") and recommending "30d" or "1m" for typical monitoring. It also clarifies `value` can be a ticker or zero-padded CIK. However, this enrichment is moderate, not exhaustive, so 4 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 it provides a change feed for a company over a time window, with specific verbs like "Fans out to SEC EDGAR, GDELT→GNews fallback, USPTO." It distinguishes itself from sibling tool entity_profile by explicitly redirecting users who need a static profile. The example queries further clarify the intended use case.

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

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

The description gives explicit usage context with example queries ("What's new with X"), parameter guidance (e.g., "Use '30d' or '1m' for typical monitoring"), and an explicit alternative: "Use entity_profile instead when you want the static profile... regardless of window." It also notes efficiency ("in ONE parallel call") and fallback behavior.

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 meaningful behavioral context not in annotations: scoping by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. It does not explicitly describe overwrite semantics for existing keys, but the idempotentHint annotation already covers idempotency, so this gap is minor.

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 and front-loaded with the core action, then offers practical use cases and lifecycle notes. Every sentence contributes value: purpose, when to use, storage semantics, persistence, and related tools. No wasted words.

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

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

For a simple two-parameter tool with no output schema, the description covers all necessary context: purpose, usage, scoping, persistence, and integration with recall/forget. The agent has enough information to decide when and how to invoke the tool correctly, including authentication implications.

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 descriptive examples for both key and value parameters. The description adds little beyond the schema, only reinforcing the key-value concept and providing usage examples in the 'Use when' clause. Since the schema already defines parameter semantics, a 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 action ('Save data'), the resource (key-value pairs), and the context (across conversations or sessions). It distinguishes from sibling tools by mentioning recall and forget as counterparts, making the tool's role unambiguous.

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

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

Explicitly provides when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and explains the benefit (avoid looking it up again). It also names the complementary tools (recall, forget) and notes the persistence difference for authenticated vs anonymous sessions, shaping 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 provide readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: it cascades through multiple lookup endpoints, degrades gracefully when external sources are unavailable, and explicitly states that unresolved identifiers are listed under 'unresolved' rather than omitted. 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 somewhat verbose (multiple paragraphs) but well-structured: it starts with common query patterns, then states the purpose, then provides usage guidance, and finally details each type. Every sentence adds value, though a minor trim could improve 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?

The tool has no output schema, so the description must cover return values. It does so comprehensively: for company, it lists identifiers, sources, ownership, and unresolved field; for drug, it lists RxCUI, ingredient, brand, and citation. It also explains graceful degradation, making it complete for a 2-parameter tool.

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

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

Schema coverage is 100% with reasonable descriptions. The description adds substantial meaning: for 'company' type, it details the returned identifiers (CIK, ticker, LEI, FIGI, ownership info) and input types (ticker, CIK, ISIN, name). For 'drug' type, it specifies RxCUI, ingredient, brand, and citation. This goes well 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 verb 'resolve' and the resource 'entity names to canonical identifiers'. It provides multiple example queries that illustrate the purpose. It distinguishes from sibling tools like compare_entities by specifying that it is for resolving names to IDs, not for comparing 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 explicitly says 'Use FIRST whenever you have a name but need an ID', which is strong usage guidance. It also explains the supported types and what they return. However, it does not explicitly state when not to use this tool or mention alternatives among the sibling tools.

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, openWorldHint, idempotentHint, and destructiveHint=false, the description adds significant behavioral context beyond these: it reveals the tool probes each entity via ai_visibility_check, ranks results by score, surfaces the most/least recognized, and returns a ranked list with score, confidence, and signal density. This gives the agent a clear mental model of the tool's execution and output, 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 compact and front-loaded, with the primary purpose in the first sentence. It efficiently covers mechanism, use case, and return format in four short sentences, with zero filler or redundancy. Every sentence earns its place, making it easy for an agent to quickly parse the essential information.

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

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

Given the tool has 4 parameters, no output schema, and strong annotations, the description is remarkably complete. It explains what the tool does, how it works (probing with ai_visibility_check), what results it returns (ranked list with score, confidence, signal density), and provides a concrete use case. The only details not in the description are in the schema (e.g., entity count limits, _apiKey requirement), so the description fully satisfies the contextual needs.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add substantial parameter semantics beyond the schema, though it clarifies the expected entity composition ('your brand + N competitors') which aligns with the schema's note about the first entry being the subject. Overall, the schema already carries the parameter details, and the description adds minimal extra value here.

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

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

The description clearly states a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling tools like ai_visibility_check (single-entity) and compare_entities (generic comparison) by explicitly focusing on AI visibility and mentioning the internal mechanism of probing with ai_visibility_check. The use case 'does Claude know about us as well as our competitors?' adds concrete 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?

The description provides clear context for when to use this tool ('Useful for competitive AI-marketing audits') and implies it is for multi-entity comparisons, contrasting with ai_visibility_check which likely handles single entities. However, it does not explicitly name an alternative or state when not to use it, leaving some room for inference. The example query effectively communicates the intended scenario.

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 critical behavioral traits beyond the read-only/idempotent annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and a 'sources_failed' field is included on timeout. This sets realistic expectations for latency and resilience, adding substantial value over 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 but every sentence earns its place: purpose, usage triggers, output fields, ecosystem limitation, and failure behavior are all covered efficiently. It uses clear structural cues (em dash, parenthetical lists) to organize information without unnecessary fluff.

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

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

Despite lacking an output schema, the description enumerates the summary block fields, per-advisory details, links, and alternative versions. It also covers partial failures and timeouts, making the tool's behavior fully understandable for an agent. This is a complete description for a 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?

Schema coverage is 100%: both 'package' and 'version' are described, including defaults and scoped package support. The description adds npm-specific context but does not go beyond the schema's parameter details, aligning with the baseline score of 3 for high schema coverage.

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

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

The description clearly states the tool's purpose: a composite check to decide 'should I add this npm package to my project', aggregating data from deps.dev and bundlephobia. This specific verb+resource phrasing distinguishes it from all sibling tools, none of which overlap with npm dependency analysis.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states a clear exclusion—'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'—helping agents know when NOT to use it.

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?

While annotations already indicate a safe read-only operation, the description adds valuable behavioral context: BGE-base-en embeddings, 500-char overlapping windows, a 200K character cap with truncation flagging, and the return format (passages with offsets and similarity scores). This goes 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 information-dense but well-organized: it front-loads the core purpose, then provides usage context, and concludes with technical details. Every sentence contributes value without redundancy or fluff.

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

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

Despite lacking an output schema, the description fully prepares the agent by explaining return values, edge cases (truncation), and how it integrates with other tools. It covers enough context for correct invocation and interpretation of results.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description reinforces the 'text' parameter with a concrete example and provides example queries for 'query', but it does not add significant new meaning beyond what the schema already offers. The baseline of 3 is appropriate.

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

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

The description opens with 'Semantic search INSIDE a fetched record', clearly stating the verb, resource, and scope. It distinguishes the tool from siblings by emphasizing that it operates on already-fetched text, and even contrasts with ask_pipeworx_grounded for the grounding workflow.

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 when the record is too big to cram into the prompt', providing a clear when-to-use criterion. It also names an alternative workflow (ask_pipeworx_grounded) and explains how they pair, offering actionable guidance on 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 readOnly=false, destructive=false, and idempotent=true. The description adds substantial context: auth requirement, SMS verification and 10/day cap, always-on feed with pull endpoints, and webhook auto-disable after 10 failures (in schema). 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 length, every sentence carries information: purpose, output, auth, types with examples, delivery channels with rules. The description is well-structured and front-loaded, with no filler or redundancy relative to the schema.

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 3 params, nested objects, enums, and no output schema, the description covers return value, prerequisites, all supported types with examples, and delivery behavior. It is complete enough for an agent to 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?

Schema coverage is 100%, but the description adds meaningful real-world examples (e.g., items:['5.02']=officer change, topic:'fed') and delivery gotchas (phone must be verified, webhook secret shown once). This enriches the schema's baseline parameter descriptions enough to exceed 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?

Description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the return value ('Returns the new subscription id') and distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 usage context and prerequisites ('Requires a Pipeworx OAuth account...'), and gives examples per subscription type. However, it does not explicitly state when to prefer subscribe over alternatives like list_subscriptions or recent_alerts, so usage guidance is implied rather than directly contrasted with sibling tools.

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, and the description adds that it draws from the 'live catalog of thousands of tools' and provides output details. This goes beyond the structured annotations without contradicting them.

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

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

While longer than some, the description is front-loaded with the tool's purpose and natural-language triggers, then covers output structure, parameters, and usage guidance. The opening example queries earn their place by helping an agent recognize when to suggest this tool.

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

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

For a tool with no output schema, the description adequately describes what is returned (category-bucketed questions with tool+argument shape), the single optional parameter, and the recommended use context. No critical gaps 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?

The input schema fully describes the `topic` parameter (coverage 100%), but the description adds examples like 'finance', 'pharma', 'betting' and explains that omitting gives the full spread. This reinforces and extends 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 identifies the tool as 'the onboarding entry point' that returns category-bucketed example questions with the exact tool + argument shape. It distinguishes from siblings by focusing on discovery and explicitly referencing meta-tools like ask_pipeworx and entity_profile.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and describes how to learn to call meta-tools. This gives a direct when-to-use directive and implies that more specific tools should be used when the user already knows their goal.

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=false, destructiveHint=false, idempotentHint=true), the description adds critical behavioral context: ownership is enforced, the row is deactivated not deleted, and historical events remain accessible via recent_alerts. This discloses the soft-delete semantics and permission constraints, significantly enriching the agent's understanding of side effects.

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 with no fluff. The action is front-loaded, and each sentence earns its place: action, ownership rule, and data-retention implication. This is a model of concise, structured tool documentation.

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

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

Given the tool's low complexity (single param, no output schema, annotations present), the description is complete. It covers the purpose, the mutation's effect (deactivate, not delete), a key usage constraint (ownership), and the downstream availability of historical events. No critical gaps are evident.

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

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

The schema already provides 100% coverage for the 'id' parameter ('Subscription id (uuid) returned by subscribe'). The description adds the additional constraint that the id must belong to the caller ('you can only cancel your own subscriptions'), which is a meaningful semantic beyond the schema's basic type/format description.

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

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

The description clearly states the action: 'Cancel a subscription by id.' The verb 'Cancel' and resource 'subscription' are specific, and it distinguishes from siblings by adding ownership enforcement and the deactivation behavior. This is a precise, unambiguous purpose statement.

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

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

The description implies usage context by noting ownership enforcement and the soft-delete behavior, but it does not explicitly mention alternatives or state when not to use the tool. It effectively conveys that you should use this tool to cancel your own subscriptions, but lacks explicit exclusions or sibling references.

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?

Goes well beyond the annotations by explaining the full verdict set, the two execution paths, and the critical distinction that 'could_not_verify' means the check did not happen and is NOT evidence for or against the claim. It also reveals that the tool replaces 4–6 sequential calls, adding significant behavioral context.

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

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

The description is dense but well-structured: it front-loads natural-language triggers and when-to-use, then details behavior and error semantics. Every sentence adds value, though it is longer than strictly necessary for a two-parameter tool.

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

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

With no output schema, the description fully explains the return value: the six possible verdicts, the grounded/structured actual value with pipeworx:// citation, and reasoning. It also covers error semantics and the two execution paths, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100%, and both parameters' descriptions are already detailed (e.g., tolerance_pct's range, default, and hallucination-detection usage). The tool description itself adds no parameter-level info beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description clearly identifies the tool's specific verb and resource: 'natural-language claim verification against authoritative sources.' It distinguishes itself from Q&A siblings by focusing on producing a truth verdict, and provides example user phrasings to eliminate ambiguity.

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

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

Provides explicit when-to-use guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and explains routing between company-financial claims (SEC EDGAR/XBRL) and all other claims (grounded pipeline). However, it does not explicitly name alternative tools or state when not to use it, so it misses the highest bar.

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