Okx

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive behavior. The description adds significant context: default model is free Workers AI, Anthropic probing requires a BYO key and direct payment, and the return structure includes score, confidence, signals, and raw_response. This goes beyond the annotation coverage.

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

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

Three sentences, front-loaded with purpose, then default/cost behavior, then return format and use cases. Every sentence earns its place with no redundancy or fluff.

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

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

Even without an output schema, the description reveals the return shape ('per-model {score, confidence, signals, raw_response} + a combined view') and explains all parameter roles and optionality. This is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with all four parameters described. Description adds value by specifying the default model behavior ('Default model is Workers AI Llama-3.3-70b') and clarifying the cost implication of `_apiKey` ('you pay Anthropic directly'), which the schema does not state.

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

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

The description uses a specific verb 'probe' and resource 'LLMs' with a clear outcome: 'score visibility (0-100) per model'. It distinguishes from siblings like ask_pipeworx and deep_research by focusing on AI knowledge visibility rather than factual Q&A or general research.

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 cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Explains when to pass `_apiKey` ('to also probe Anthropic'), giving clear context. It does not name alternative tools, but the guidance is sufficient for most scenarios.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavior beyond those: it routes to 5,564 tools, auto-fills arguments, returns stable pipeworx:// citation URIs, and works on every tier with one fast call. There is no contradiction with the annotations.

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

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

The description is well-structured and front-loaded with the most important decision rule: prefer ask_pipeworx over web search. It is long, but almost every sentence adds value; there is some redundancy between the 'prefer over web search' statement and the later 'use whenever' list, preventing a perfect score.

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

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

For a broad question-routing tool with no output schema, the description is very complete: it specifies domain coverage, examples, return characteristics, citation behavior, tier availability, speed, and when to escalate to sibling tools. This gives an agent enough context to choose and invoke it confidently.

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

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

Schema coverage for parameters is 100%, and the schema already documents all six aliases of the natural-language question. The description adds useful examples of accepted question types but not substantially more parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states an explicit action: ask ask_pipeworx to route a natural-language factual question to the right source/tool and return a structured answer with pipeworx:// citation URIs. It also differentiates this tool from web search and from nearby siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives strong usage guidance: prefer this over web search, use for current/historical facts across many domains, start here by default, and step up to ask_pipeworx_grounded or deep_research only when more appropriate. This is explicit when-to-use and includes named 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 (readOnly, idempotent, etc.), the description discloses the beta nature, that candidates may be enabled live, its current state (no active candidate), and that it is a full working router rather than a fallback. It does not contradict annotations and adds useful behavioral context about potential variability during tests.

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 and front-loaded with the key point about being a beta version. It is reasonably concise, though it repeats the idea of matching ask_pipeworx (e.g., 'identical' and 'matches exactly'). The additional detail about the last retired candidate is useful context but slightly verbose. Still, it earns its place.

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

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

For a tool with a simple schema and strong annotations, the description is largely complete. It explains purpose, usage, current equivalence to stable, and the experimental nature. It does not describe the return format, but references 'same response shape' as ask_pipeworx, which is reasonable given this is explicitly a beta of that tool. No output schema exists, so the description carries the burden, but it is sufficient.

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 covers 100% of parameters with descriptions, including aliases. The description adds no extra parameter information beyond saying 'same arguments' as ask_pipeworx, which is a reference rather than new meaning. Since schema coverage is high, 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 this is a beta version of ask_pipeworx with identical functionality (same 5,564 tools, arguments, response shape) but with experimental routing improvements. It explicitly distinguishes from the stable sibling by positioning itself as the experimental edge, and the verb 'use' plus reference to the universal router makes the tool's action evident.

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 guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router, implying it is for experimental use. However, it doesn't explicitly state 'do not use for stable/production' or point to ask_pipeworx as the alternative for stable use, though the beta positioning makes this implicit.

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

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

The description discloses behavioral traits beyond annotations: it uses ONLY tool content, returns explicit refusal reasons when data is insufficient or errors occur, and notes the extra LLM call cost. This is rich, specific context that annotations (readOnly, openWorld, idempotent, non-destructive) do not already provide. No contradiction.

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

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

The description is long but every sentence provides unique value: it explains the mechanism, return contract, refusal modes, when to use, and cost trade-off. It is well-structured and front-loaded with the core purpose. No 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?

Since there is no output schema, the description must explain return values, and it does thoroughly with answer, evidence, confidence, source, fetched_at, and refusal_reason. It also covers error/refusal handling, use cases, and cost implications, making it complete for an agent deciding whether and how to invoke.

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

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

Schema coverage is 100% for the 'question' parameter and its aliases, so the schema carries the burden. The tool description does not add parameter-specific meaning, but the schema already clarifies the question is natural language. Baseline of 3 is appropriate given the 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 identifies a specific, distinct mode: 'Hallucination-resistant answer mode for high-stakes reads' and explains that it routes like ask_pipeworx but then extracts the answer using ONLY the tool result. This differentiates it from the sibling ask_pipeworx and other tools by emphasizing grounding and evidence.

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 given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with domain examples. It also states when not to use it: 'prefer ask_pipeworx for casual lookups.' This is clear, with alternatives and 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?

The description extensively details behavior beyond the readOnlyHint annotation, including fan-out logic, resolver contract (market_match_confidence, alternatives, suggestions), safety short-circuiting, status codes (low_confidence_match, market_closed_or_inactive), and resolution-rule risk. This goes far beyond the annotation baseline.

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 very long and densely packed, with many sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and numerous edge cases. It is well-structured and front-loaded with the core purpose, but it is not concise and could be trimmed without losing essential 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?

Despite having no output schema, the description comprehensively explains response shapes, key fields (market, analysis, evidence), resolver contract, parent event extractor, news fallback fields, safety statuses, and resolution-rule risk. It covers a wide range of scenarios, making it highly 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?

Input schema coverage is 100%, with all three parameters already described in detail (market accepts slug/URL/question, depth enum, include_raw default/effect). The description does not add significant new parameter-level semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and distinguishes from sibling research tools like deep_research by focusing on Pipeworx data and bet resolution.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear when-to-use context, but it does not explicitly mention alternatives or when not to use the tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that bars range from 1m to 1M, but does not disclose pagination behavior or rate limits. This aligns with the annotations and provides minor additional context, meeting the baseline.

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 concise sentences: the first states what the tool does and the second states its intended use. No redundant or filler content, front-loaded with the key 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?

With annotations covering safety and an output schema present, the description covers the main purpose and use cases. It lacks explicit parameter explanations, but the schema and examples partially compensate. For a market data tool, this is reasonably complete, though not exhaustive.

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 0%, so the description must compensate. It mentions 'Bars 1m through 1M,' hinting at the 'bar' parameter, but does not explain 'instId', 'after', 'before', or 'limit'. The examples give some inference, but the description itself adds minimal parameter detail.

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

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

The description clearly identifies the tool as providing OHLC candles for OKX instruments, specifying spot/perp/futures. This distinguishes it from sibling tools like ticker, trades, and order_book by stating the exact resource and data type.

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 for charting and backtesting OKX instruments,' which gives clear context for when to apply the tool. However, it does not provide explicit when-not-to-use guidance or name alternative tools, so it falls short of a 5.

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

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

Beyond read-only and idempotent annotations, the description reveals data sources (SEC EDGAR/XBRL, FAERS/FDA), handling of off-calendar fiscal years, sorting by primary metric, and citation URI output. This is substantial 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?

Dense and front-loaded with natural-language triggers, covering all key aspects in one paragraph. Minor redundancy in example phrasings, but overall efficient and well-organized.

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

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

With no output schema, description specifies return shape (paired data + citation URIs) and ordering. It covers both entity types with clear data sources, making the tool fully understandable for an agent.

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

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

Schema covers both params, but description adds crucial semantics: what type='company' vs 'drug' actually return, acceptable value formats (tickers/CIKs vs drug names), and how values array is used. This exceeds schema descriptions.

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

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

Description clearly states it does 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and gives trigger phrases. It distinguishes itself from sequential single-pack lookups, making its 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving a clear when-to-use rule and naming the alternative pattern. It also differentiates company vs drug 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 indicate readOnly and non-destructive, and the description adds significant behavioral context: depth tiers, hop/gap recovery, contradictions array, expected latency (15-90s), citation guarantees, and the account requirement. There is no contradiction with annotations; instead, it enriches 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?

Although long, every sentence is informative and necessary. The description is structured logically: account requirements first, then core function, usage guidance, depth behavior, timing, and citation details. It is dense but well-organized and front-loaded.

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

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

The description is exhaustive for the tool's complexity: it explains what the findings packet includes (verbatim evidence, confidence, source, fetched_at, gaps, contradictions), performance expectations, and how citations are guaranteed to be fetchable. There is no output schema, but the description covers return behavior comprehensively.

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

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

Schema covers 100% of parameters, and the description goes beyond: it explains the implications of each depth tier (paid plan for thorough, number of facets, hop behavior) and clarifies that question accepts broad/multi-part input. This adds meaning well beyond the schema's enum and basic 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 what the tool does: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and explains its decomposition/parallel-facet behavior. It distinguishes from sibling tools like ask_pipeworx for single lookups and breaking news, making its 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 gives explicit usage guidance: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also states what it is best for and provides examples, giving clear when-to-use and when-not-to-use instructions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds value by specifying the exact return format: 'full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This is useful behavioral detail beyond the structured data.

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

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

The description is front-loaded with the core verb and resource, but contains a somewhat redundant list of synonyms ('browse, search, look up, or discover') and a long enumeration of domains. While all sentences have purpose, the verbose list prevents a 5. Score 4.

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

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

With no output schema, the description adequately covers return values ('top-N most relevant tools with names, descriptions, and full input schemas') and the first-use scenario, making it sufficiently complete for a meta-tool. However, it omits any mention of error behavior or pagination, so not a 5.

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's mention of 'describing the data or task' adds minimal semantic value over the schema's query description ('Natural language description of what you want to do'). No additional syntax or parameter behavior is disclosed, so a 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 'Find tools by describing the data or task,' which is a specific verb+resource. It further distinguishes itself from the large sibling set by positioning as a meta-tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

The description explicitly states when to use ('Use when you need to browse, search, look up, or discover what tools exist') and advises calling it first. However, it does not explicitly name alternatives or state when not to use, so it falls short of the 5 anchor.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant context beyond these: it discloses the parallel fan-out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), mentions the USPTO API sunset and soft-fail behavior, and describes the GDELT→GNews fallback. These are behavioral traits not captured 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?

The description is densely informative but every sentence adds unique value: example queries, cross-source fan-out details, return fields, source fallback, and parameter constraints. It is front-loaded with concrete use cases and avoids fluff. Despite its length, it is well-structured and earns each sentence.

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

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

Given the tool's complexity (multiple data sources, several return components) and the absence of an output schema, the description thoroughly explains what is returned: CIK, company name, recent filings with URIs, fundamentals (with specific metrics), patents, news, and LEI. It also covers limitations (names not supported, patent API sunset). This provides an agent with a complete mental model for invoking the tool correctly.

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

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

The input schema has 100% description coverage: both 'type' and 'value' are fully described with examples and constraints. The description repeats the same parameter guidance ('Pass ticker "AAPL" or zero-padded CIK "0000320193" — names not supported') without adding new meaning beyond the schema. Therefore, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs like 'profile' and 'research' and distinguishes from siblings by explicitly preferring it over chaining single-pack lookups. Examples like 'Tell me about X' and 'company profile for Microsoft' make the intent unmistakable.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names a specific alternative: 'use resolve_entity first if you only have a name.' This clearly delineates when to use this tool versus siblings.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, and the description's 'Delete' aligns with these. The description adds valuable context about why deletion might be needed (stale context, task completion, sensitive data), which goes beyond the annotations and helps the agent understand the operational context. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the primary action, and every phrase earns its place. It efficiently conveys purpose, usage timing, and related tools without fluff.

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

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

This is a simple one-parameter tool with no output schema, and annotations already cover destructive and idempotent behavior. The description fully covers purpose and usage context, making it complete for agent decision-making. The pairing with remember and recall also situates it within the memory workflow.

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

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

The input schema provides 100% coverage for the single parameter 'key' with description 'Memory key to delete.' The description's 'by key' adds no additional semantic detail beyond what the schema already specifies. Baseline of 3 is appropriate given full schema coverage.

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

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

The description opens with 'Delete a previously stored memory by key,' which is a specific verb+resource statement that clearly distinguishes this tool from siblings like remember and recall. It unambiguously communicates the action and 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 provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names companion tools (remember and recall), effectively guiding the agent on when this tool is appropriate relative to alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool is for SWAP instruments and returns specific fields. However, it does not disclose behavior like error handling for invalid instId, rate limits, or the discrepancy between the description example (SWAP) and schema example (PERP). It adds some value but not deep 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 a single, well-structured sentence that front-loads the key details (exchange, instrument type, data returned). No unnecessary words 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?

For a simple one-parameter tool with an output schema, the description is fairly complete. It specifies the instrument type, returns fields, and provides an example. However, it lacks an explicit mention of when to use this tool instead of funding_rate_history, and the example inconsistency slightly undermines completeness.

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

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

The schema has zero description coverage for instId, so the tool description must compensate. It explains that instId should be a SWAP instrument like 'BTC-USDT-SWAP'. This provides format guidance. However, the schema example uses 'BTC-USDT-PERP', which contradicts the description's example and could confuse the agent. Overall, it adds significant meaning beyond the bare schema.

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

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

The description clearly states the tool's purpose: retrieving the current perpetual swap funding rate from OKX for a specific SWAP instrument. It includes a concrete example (BTC-USDT-SWAP) and lists the returned data (funding rate, next settlement time, method). This distinguishes it from siblings like funding_rate_history and mark_price.

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 by saying 'current' funding rate, but it does not explicitly state when to use this tool versus alternatives. For instance, it does not mention funding_rate_history for historical data or note that this is only for current rates. The guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds context about OKX and historical data, plus cursor-based pagination. However, it does not disclose potential rate limits, data availability windows, or behavior for invalid instrument IDs.

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 concise sentences that front-load the core action and instrument type. No redundant information; every phrase 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?

With an output schema present, return values need no description. It covers purpose, input format, and use case. It could mention why to use this over funding_rate, but the 'historical' label 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 description coverage is 0%, so the description carries the burden. It explains 'before/after (ms epoch) cursors' and 'limit', adding meaning beyond bare schema. The example 'BTC-USDT-SWAP' clarifies instId format, though schema examples use 'PERP' inconsistently.

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 historical perpetual swap funding rates from OKX, using the verb 'historical' and specifying instrument type (SWAP). This distinguishes it from sibling tool 'funding_rate' which likely provides current rates.

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

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

It provides the use case 'Use for funding cost analysis' and mentions optional before/after cursors and limit, guiding pagination. It does not explicitly mention alternatives, but the 'historical' label implies the distinction from funding_rate.

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 the tool 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', which adds behavioral context beyond the readOnlyHint, openWorldHint, and idempotentHint annotations. It explains the fetch-and-extract process and the output format. 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 a single sentence followed by a concise 'Useful for' list. It front-loads the core purpose and maintains relevance throughout. The list of use cases adds practical value but makes the description slightly longer than strictly necessary. Still, it is well-structured and efficient.

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 only 2 parameters and no output schema, the description provides sufficient context: it explains the process, the output format ('standard llms.txt markdown format', 'single text blob'), and typical use cases. It does not mention edge cases or failure behavior, but given the annotations and simplicity, the description is complete enough for an agent to select and invoke the tool effectively.

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

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

The input schema already provides 100% coverage with detailed descriptions for both 'url' and 'max_links'. The tool description does not add additional parameter-level details beyond what the schema already states. It mentions 'any URL' but that is just a generic reference. Baseline 3 is appropriate given the schema already does the heavy lifting.

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

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

The description clearly states the tool's action: 'Generate a production-ready llms.txt file for any URL'. It specifies the resource (llms.txt), the target (any URL), and the purpose (AI crawlers can index the site cleanly). This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on visibility analysis rather than file generation.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'. This gives clear context for when to use the tool. However, it does not mention when not to use it or explicitly reference alternative tools, so it falls short of a perfect score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds that it returns current price and 24h change and supports filtering, which is useful but does not go beyond annotations to disclose rate limits, pagination, or other behavioral traits. No contradiction is present.

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

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

The description is two sentences, front-loaded with the core purpose, and every word contributes. It is efficient and free of filler, making it easy for an agent to parse quickly.

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 (2 optional params, read-only, output schema present), the description covers purpose, parameters, and data source. It omits explicit behavior when no filters are provided, but that is reasonably implied. The output schema handles return details, so this is largely complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains both parameters: quoteCcy for filtering by currency (with 'USD' example) and instId for a specific instrument. This adds meaning beyond the bare schema and clarifies intended usage, though it is concise and does not elaborate on edge cases or mutual exclusivity.

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

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

The description clearly states the tool provides current index price and 24h change for OKX index instruments. It distinguishes from generic ticker tools by explicitly mentioning 'index instruments', but unlike the high-scoring example, it does not name a sibling tool or explicitly contrast with 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 index instruments and explains filtering by quote currency or instId. However, it does not provide explicit when-to-use versus alternatives, such as the regular 'ticker' or 'tickers' tools, nor does it state exclusions or prerequisites. Usage guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful context by enumerating the accepted instType values and the return fields, which goes beyond the 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?

The description is a single sentence that fronts the core purpose ('list instruments by type') and immediately provides the key allowed values. It is concise with 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?

The description covers the main purpose, enumerates the type filter, and lists the return fields. Since an output schema exists, return value details are covered. The main gap is the lack of explanation for optional filter parameters, but the tool's overall context is sufficiently clear.

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 0%, so the description must explain parameters. It does explain instType by listing its allowed values, but it says nothing about uly, instId, or instFamily, which are also parameters. With 4 parameters and no schema descriptions, this is a notable gap.

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

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

The description clearly states the tool lists instruments from OKX by type, with a specific verb ('list') and resource ('instruments'). It enumerates valid instType values, distinguishing it from sibling tools like tickers or candles that serve different data needs.

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 when to use this tool (when you need instrument IDs, tick sizes, lot sizes, or trading rules) and gives clear context by listing instrument types. However, it does not explicitly mention alternatives or exclusion scenarios, so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is established. The description adds the scope (caller's own subscriptions) and a precise return-field list, going beyond the annotations. It does not mention edge cases like empty results or inactive behavior, but that 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?

Two sentences with no fluff: purpose and return fields are front-loaded, followed by a practical usage scenario. Every sentence earns its place.

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

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

For a simple list tool with one optional parameter and no output schema, the description sufficiently covers what it does, what it returns, and when to use it. It relies on the schema for include_inactive, which is a reasonable division of labor.

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

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

Schema coverage is 100% with a clear description of include_inactive, so the baseline is 3. The description does not mention this parameter but also does not contradict it. The listed return fields give useful context that aids understanding the parameter's effect.

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 listing the caller's active subscriptions and enumerates the exact return fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from subscribe/unsubscribe by framing this as the review step before adding or canceling subscriptions.

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

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

Explicitly states when to use the tool: to review what you're monitoring before adding more and to find an id to cancel. This strongly implies alternatives (subscribe/unsubscribe) without naming sibling tools, but the context is clear.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the list of returned fields but does not disclose any additional behavioral traits (e.g., timezone, data freshness, or exact rolling window definition).

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 concise sentences that front-load the tool's purpose and provide a practical use case. No unnecessary 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?

For a simple one-parameter tool with an output schema and comprehensive annotations, the description covers purpose, usage, and data fields. The only minor gap is ambiguity about what 'rolling' means (e.g., exact time boundary), but this is acceptable for 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 schema provides zero description for instId, so the description must compensate. 'for an instrument' hints that instId is an instrument identifier, but it doesn't specify the format or give examples. The schema's example 'BTC-USDT' covers some of this gap, but the description could be more explicit about what to pass.

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

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

Clearly states it retrieves OKX 24-hour rolling stats for an instrument and enumerates the exact fields (open, high, low, last, volume, vol-ccy). It differentiates from sibling tools like 'ticker' or 'candles' by focusing on a rolling 24-hour aggregate.

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

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

Provides an explicit use case: 'Use for daily summary on OKX.' This gives context for when to select this tool. However, it does not mention alternative tools or exclusions, so it's not a full when/when-not statement.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context by explaining that the returned mark price is used for unrealised P&L and liquidation calculations, giving the agent insight into the significance of the returned value beyond the basic safety 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 two sentences, front-loaded with purpose, then usage, then the return's significance. Every sentence earns its place with no redundant 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?

The tool has an output schema, so return values are covered externally. Annotations cover safety. However, the description is not fully complete because it omits definitions for 'uly' and 'instId', which are essential for correct invocation. It also doesn't mention any constraints or edge cases (e.g., what if both are provided).

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

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

With 0% schema description coverage, the description carries the full burden for parameter semantics. It states that instType is required and uly/instId are optional, but it does not explain what 'uly' or 'instId' mean. The schema examples provide some hints, but the description itself fails to define these terms, leaving a significant gap.

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 returning the OKX mark price for derivatives, with a specific verb ('Returns') and resource ('OKX crypto exchange mark price for derivatives'). It distinguishes from sibling tools like 'ticker' by noting its use for unrealised P&L and liquidation calculations.

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

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

It gives direct invocation guidance ('pass instType (e.g. 'SWAP') and optionally uly or instId'), making clear which parameters are required and optional. It does not explicitly mention alternatives or exclusions, but the context is sufficiently clear for use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds 'live depth-of-book' and 'bids + asks' as behavioral context, but does not disclose potential limitations such as pagination, depth limits, or data freshness guarantees. With annotations carrying the safety burden, this is adequate but not rich.

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 long, front-loaded with the core purpose, and contains no filler. Every word contributes to understanding the tool's function and usage.

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 an output schema, so return values are covered. However, the description omits parameter semantics for sz and only implicitly covers instId. Given the simplicity of the tool and strong annotations, the description is minimally viable but has clear gaps in parameter explanation.

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 0%, and the description fails to explain the two parameters, instId and sz. While instId can be inferred from 'OKX-listed instruments,' sz is entirely unexplained. The description adds no meaning beyond the schema's bare names and types.

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: retrieving the OKX order book (bids + asks) for spot/perp/futures instruments. It specifies the resource (OKX crypto exchange) and scope (live depth-of-book), distinguishing it from sibling tools like candles, trades, and ticker.

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 for live depth-of-book on OKX-listed instruments,' providing direct guidance on when to use the tool. However, it does not name alternative tools or explicitly state when not to use it, so it falls short of a 5.

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

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

Annotations are all false, so the description carries the full burden. It discloses rate limiting ('5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), the claim_token workflow ('Filing without an account returns a `claim_token`; pass it back later...'), and how feedback is used ('team reads digests daily and signal directly affects roadmap'). This substantially exceeds what annotations convey.

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

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

The description is about 180 words and fairly dense, but each sentence earns its place: scope, exclusions, claim_token flow, rate limits, quota, and guidance. It is front-loaded with purpose and use cases. Minor trimming of motivational phrases like 'signal directly affects roadmap' would tighten it, so 4 rather than 5.

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

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

For a tool with conditional usage (claim_token vs filing) and no output schema, the description explains both operation modes, what the response contains (claim_token, status once resolved), and constraints like rate limits and quota. This is fully complete for the tool's complexity.

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

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

Schema description coverage is 100%, and the tool description largely restates schema parameter semantics (e.g., claim_token's 'with no other arguments' is already in the schema). It adds no new parameter meaning beyond what structured fields provide, so the baseline of 3 applies.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature/data_gap, praise) and explicitly scopes to 'ONLY for tools served by this Pipeworx connection,' distinguishing it from sibling data/research tools.

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

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

States outright 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead,' and offers helpful guidance like 'don't paste the end-user's prompt.'

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

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

Annotations already cover safety hints; description adds valuable context beyond them: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' No contradiction.

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

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

Front-loaded with the core purpose, then structured 'Useful for' bullets, and final data/caching details. Slightly longer than minimal, but every sentence earns its place and the layout aids scanning.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers return content (top tools, packs, count, format) and behavioral nuances like caching and data source. Sufficient for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% for the single optional 'window' parameter, including enum values and explanatory text. Description reinforces window choices but adds no new semantics beyond what the schema already provides.

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

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

Description states a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' It clearly distinguishes from siblings like discover_tools by focusing on AI agent usage trends.

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

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

Provides an explicit 'Useful for' list with three concrete scenarios, giving clear context on when to use. Does not mention when-not or alternative tools, so it stops short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description reveals significant behavioral traits: the algorithm (monotonicity violations + partition-sum), thresholds (>3pp deviations emit signal), semantic anchor (Jaccard ≥0.30), placeholder filtering (>20% placeholder fraction returns null), and the fill check (realizable_edge_pp ≤ 0 means do not trade). It also discloses response structure and skipped_low_similarity counts. This goes far beyond what annotations provide, and nothing contradicts 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 exceptionally dense with valuable information. It front-loads the core purpose and then methodically explains each mode, filters, and fill check. Every sentence earns its place, though the wall-of-text format could benefit from bullet points or section breaks. Given the tool's complexity, the length is appropriate rather than wasteful.

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

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

With no output schema, the description carries the burden of explaining return values. It does so for event mode (partition_check details), the general opportunities[] array, and the fill check output. However, the trending_scan (no-args) response is only implicitly covered by the generic opportunities[] mention, and some response fields like skipped_low_similarity are described but not fully structured. Still, it is largely 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?

Although the input schema already describes both parameters (event and topic) with usage examples, the description adds substantial meaning: it explains the mode-specific behavior, gives example slugs and seed questions, and clarifies the underlying methodology (e.g., ordering checks, partition sums). This goes beyond the schema's baseline and fully compensates with rich contextual detail.

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

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

The description opens with a clear statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This uses a specific verb and resource, and immediately distinguishes the tool from siblings like polymarket_edges or polymarket_fill_risk by focusing on arbitrage detection. It also outlines distinct modes (trending_scan, event, topic) that clarify scope.

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

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

The description provides explicit usage instructions: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'topic for a themed cross-event scan'. It even recommends event mode for a specific market and directs users to polymarket_fill_risk for custom sizing, effectively explaining when to use this tool versus alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description goes far beyond this by disclosing caching ('Cached 1h at the KV level keyed on all knobs'), the detailed edge computation (slippage, Kelly cap at 0.25, 24h-move warning), response diagnostics for why segments are empty, and the Fed candidates caveat. This is exceptionally transparent.

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

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

The description is long and dense, but it is front-loaded with the primary purpose and logically structured into model family segments, response details, and knobs. Every sentence carries meaningful information for a complex tool. However, some details (e.g., exact per-sport α values) could be considered excessive for tool selection, so it is not maximally 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?

With no output schema, the description fully explains the return structure: by_segment{model_driven, structural_arbitrage, concentrated_longshot}, fed_candidates/fed_note, and _diagnostics with funnel counters. It also covers edge cases like empty segments, stale markets, and the Fed data unreliability note. The description is self-sufficient for an agent to know what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds high-level meaning by grouping knobs as 'TRADEABLE-EDGE KNOBS' and explaining their effect (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable'), and clarifies that edge_pp_net is after slippage. This adds value, but the schema already documents each parameter thoroughly, so it does not warrant a 5.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes itself by naming the three model family segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and stating it allows agents to 'discover opportunities without paging hundreds of markets,' which separates it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description clearly states the intended use case: 'Built for "what should I bet on today"' and contrasts with the alternative of paging through hundreds of markets. It also provides guidance on knobs like min_liquidity and max_spread_pp to filter for tradeable edges. However, it does not explicitly name sibling tools as alternatives or state when not to use this tool, so it stops short of a 5.

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

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

The description thoroughly discloses limitations and behavior: 60-day snapshot TTL, data gaps when no scan occurred, and that decay is computed from daily closes of edge_pp_net, not intraday. This goes well beyond the annotations, which only declare read-only, idempotent, and open-world hints.

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

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

The description is structured with clear sections (Args, RESPONSE, LIMITS) and every sentence adds substantive information. It is dense but not wasteful, front-loading the core question and then detailing response fields and constraints.

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

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

Given there is no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and their semantics, plus history limits. This makes the tool's behavior complete and predictable for 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?

The schema already describes both parameters (days clamp 2-30, window enum). The description adds useful defaults and clarifies 'window' as a snapshot family, but since schema coverage is 100%, the incremental value is limited, though still helpful.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry, answering the specific question of how long an edge has existed and whether it is shrinking. It distinguishes itself from the sibling tool polymarket_edges by focusing on time-series behavior across snapshots rather than current edges.

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

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

It provides clear usage context (e.g., differentiating fresh vs. 3-week-old wide edges) and explains what questions it answers. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of a 5.

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

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

Annotations already mark it read-only/idempotent; description adds behavioral detail: 'walks the ladder,' return metrics, per-leg fill detail, and forced_directional_risk. It also documents the 'one of market/event' requirement and distinguishes single-market vs basket behaviors.

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?

Though long, it is structured with labeled sections (SINGLE-MARKET, BASKET, USE THIS) and every sentence carries operational detail. The all-caps REQUIRES and USE THIS signals prioritize critical constraints without fluff.

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

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

No output schema exists, but description enumerates all return fields for both modes, explains the verdict values, and flags the risk of partial fills. It also names sibling tools to disambiguate, making the tool self-contained for an agent.

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

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

Schema descriptions cover each parameter, but the description adds mode-specific semantics: side defaults and meanings for basket vs single, size_usd as max spend vs target proceeds vs settlement notional, and clamp range. This meaningfully exceeds schema, giving the agent everything needed to invoke correctly.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource that clearly distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges. It also enumerates two modes and their outputs, leaving no ambiguity about its 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?

Explicitly instructs to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' and explains the rationale (partial fills convert arb into unhedged directional position). This is textbook when-to-use guidance with named alternatives.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description goes far beyond these by disclosing compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the caveat that pre-mapped topics may not be tradeable. There is no contradiction with annotations.

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

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

The description is quite long but well-structured with clear sections (intro, modes, response, safety fields, temporal alignment, counters, caveat). Every sentence conveys essential information, but it could be slightly trimmed without losing meaning.

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

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

There is no output schema, so the description must explain return values and edge cases. It covers leg-by-leg prices, spread calculation (Kalshi − Polymarket), compatibility_warning conditions, temporal_alignment, and skip counters. Combined with rich annotations, this description makes the tool fully understandable and usable.

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 all three parameters described. The description adds value by explaining the relationship between topic and explicit tickers (overrides), the auto-fetch behavior for shortcuts, and the meaning of explicit pairings. This is more than just a baseline 3 but not a 5 since the schema already carries most parameter detail.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly states the tool's verb (cross-venue spread) and distinct resource (Kalshi and Polymarket). It sufficiently distinguishes from sibling tools like polymarket_arbitrage by explicitly naming both venues and describing two modes.

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

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

The description explains when to use each mode (pre-mapped topic shortcuts vs explicit tickers) and warns that 'pre-mapped ≠ tradeable' and most pre-mapped topics return compatibility warnings. This gives clear usage context, though it doesn't explicitly name alternative tools for non-Kalshi spreads or when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds valuable context beyond those: scoping to the agent's identifier and the dual behavior of retrieving vs listing. No contradiction with annotations, though it doesn't disclose return format or error behavior, which are minor for this simple read operation.

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

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

Three sentences, front-loaded with the action, and every sentence earns its place. Examples are illustrative without being verbose; no filler or redundancy.

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

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

For a tool with one optional parameter, no output schema, and strong annotations, the description covers purpose, usage context, scoping, and relationship to sibling tools. Nothing essential is missing for an agent to correctly select and invoke it.

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

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

Schema coverage is 100% and the schema already describes the 'key' parameter, including the 'omit to list all' behavior. The description restates this but adds no new parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb ('Retrieve') and resource ('value previously saved via remember'), and explicitly distinguishes the listing behavior ('or list all saved keys'). It differentiates from sibling tools by naming remember and forget, making clear this is the retrieval counterpart.

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 to look up context the agent stored earlier' with concrete examples (ticker, address, notes). It also names the paired operations ('Pair with remember to save, forget to delete') and explains the alternative of omitting the key to list all keys.

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

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

Annotations already declare read-only/idempotent safe, but the description adds crucial behavioral detail: the mark_read:true side effect mutates read state, and return contents are described (source, citation_uri, raw payload). This goes beyond annotations without contradicting them.

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

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

Four sentences, each packed with useful information: purpose, return payload, filtering/side effects, and alternative endpoint. No fluff, fully front-loaded.

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

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

With no output schema, the description compensates by explaining return attributes and behavior. It covers filtering, pagination implication (limit via schema), side effects of mark_read, and a script-friendly alternative. Very complete for a 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?

Schema coverage is 100%, so all parameters are already documented. The description adds a concrete type example ('sec_8k'), explains the effect of mark_read, and clarifies the 'since' format, providing value beyond the schema.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly identifies this as the tool for reading recent alerts, distinguishing it from sibling tools like list_subscriptions and recent_changes.

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

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

Provides clear context on polling ('Polls work fine') and an alternative for scripts/dashboards via a REST endpoint. It doesn't explicitly contrast with sibling alert tools, but the usage context is strong enough for an agent to select appropriately.

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

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

Discloses the multi-source fan-out to SEC EDGAR, GDELT→GNews with fallback conditions, and USPTO with a soft-fail due to API sunset. This adds value beyond the readOnly/idempotent annotations by explaining exactly what happens on each source and potential failure modes.

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: query examples, source fan-out, parameter formats, return structure, and alternative tool. It is well-structured and front-loaded with the core purpose.

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

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

Despite lacking an output schema, the description clearly states the return format (changes[] by source, total_changes, citation URIs). It also covers fallback behavior and soft-fail conditions, 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 coverage is 100%, with detailed per-parameter descriptions already in the schema. The description largely repeats the parameter info, adding only minor context like 'one parallel call' and the typical monitoring window recommendation. Therefore the description does not add substantial semantic value beyond the schema.

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

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

Clearly defines the tool as a change feed for a company over a time window, with common query phrasings. Explicitly distinguishes from entity_profile by noting the static profile use case. The verb-phrase 'change feed' and resource 'company' are specific and accurate.

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 strong usage guidance: tells the user to use entity_profile when a static profile is needed regardless of window. The description also clarifies the tool's parallel call behavior and the kinds of questions it answers, making it easy to select among siblings.

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

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

Description discloses important traits beyond annotations: 'scoped by your identifier,' 'authenticated users get persistent memory; anonymous sessions retain memory for 24 hours,' and the key-value storage model. This adds context about data retention and scoping that annotations do not provide. No contradictions with the given annotations (idempotentHint=true, destructiveHint=false, readOnly=false).

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 purpose, then usage, then storage details and sibling references. Every sentence earns its place with no fluff or redundancy. It is concise yet information-dense.

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, the description covers purpose, when to use, persistence behavior, scoping, and how it relates to sibling tools (recall, forget). No output schema exists, and the description does not need to explain return values for a save operation. It is sufficiently 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% with descriptions for both key and value parameters. The description reinforces parameter semantics by giving domain-specific examples of keys ('resolved ticker, target address, user preference') and values ('findings, addresses, preferences, notes'), adding value beyond the schema's generic examples.

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: 'Save data the agent will need to reuse later.' It specifies the action (save), resource (data/key-value pair), and scope (across conversation or sessions). It also distinguishes itself from siblings by mentioning recall and forget as complementary tools for retrieval and deletion.

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

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

Explicit guidance is provided: 'Use when you discover something worth carrying forward' with concrete examples like 'a resolved ticker, a target address, a user preference, a research subject.' It also gives a clear exclusion by telling the agent to pair with recall for retrieval and forget for deletion, preventing misuse.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive, but the description adds valuable behavioral context: it explains internal cascading lookups, graceful degradation of LEI/FIGI enrichment, and that unresolved identifiers are explicitly listed under an 'unresolved' field. No contradiction with annotations.

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

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

The description packs a lot of detail into multiple paragraphs, making it comprehensive but somewhat verbose. While the opening example queries are effective hooks, the later paragraphs contain technical specifics (source names, duplicate prevention) that could be more concise. It earns its place but could be tighter without losing clarity.

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 compensates by detailing what identifiers are returned (CIK, ticker, company_name, LEI, FIGI) and how they are structured (labeled by source, unresolved entries). It covers edge cases like graceful degradation and ISIN mapping. Slight gaps: no explicit mention of pagination or response format, but sufficient for a resolve tool of this complexity.

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

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

Schema coverage is 100% but the description adds extensive meaning beyond the schema: it clarifies that 'value' accepts ticker, CIK, ISIN, or company name for 'company' type, and brand or generic name for 'drug' type. It provides examples ('AAPL', '0000320193', 'ozempic') and explains special behavior (ISIN resolves to legal entity via GLEIF). This far exceeds the schema's minimal 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 starts with concrete example queries ('What's the ticker for...'), clearly states the action ('resolve a user-spoken NAME to the canonical/official identifiers'), names the resource ('entity'), and lists supported types ('company', 'drug'). It also instructs to 'Use FIRST whenever you have a name but need an ID', distinguishing it from sibling tools that require IDs already.

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,' providing clear guidance on when to invoke the tool. It also details that it replaces 2-3 manual lookups, implying efficiency. While it does not explicitly list when not to use it or name alternatives, the strong directive to use it first when lacking an ID is sufficient given the context.

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

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

Annotations already provide readOnly, idempotent, and openWorld hints. The description adds meaningful behavioral detail beyond that: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. It also notes that the first entity is treated as the subject. This enriches the agent's understanding of what the tool actually does, going 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 four sentences, each adding value: purpose, mechanism, usage context, and return format. It is front-loaded with the primary function and avoids redundancy with the schema. The phrasing is tight and readable with 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?

Given the lack of an output schema, the description properly discloses the return format (ranked list with score, confidence, signal density). It also covers the tool's core mechanics and use case. Since the schema already documents parameters well and annotations cover safety, the description is reasonably complete. It could have explicitly contrasted with single-entity tools, but that is not a significant 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 with descriptive text for all four parameters, including the distinction that the first entity is the subject and the rest are competitors. The description reinforces this but adds minimal new semantic detail—just the notion of 'your brand + N competitors.' Given the schema already handles parameter meaning fully, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility across entities), and scope (multiple entities), and distinguishes it from sibling ai_visibility_check by emphasizing side-by-side comparison across entities. This makes the purpose unmistakable.

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' with a concrete example. It implies when to use this tool (comparing multiple entities) versus ai_visibility_check (single entity), but does not explicitly state exclusions or name alternatives directly. This fits the 'clear context, no exclusions' level.

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 readOnlyHint/idempotentHint annotations. It discloses degradation behavior (partial failures, sources_failed field), performance caveats (bundlephobia first measurement can take 5–30s), and the NPM-only limitation. No contradiction with annotations.

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

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

Though lengthy, the description is tightly structured and front-loaded. The first sentence gives the composite purpose, followed by usage guidance, return fields, ecosystem scope, and failure behavior. Every sentence earns its place with specific, non-redundant 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?

There is no output schema, but the description enumerates the full return block (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable, plus details and alternatives). It also covers error handling, performance, and ecosystem constraints, making the tool fully self-explanatory for an agent.

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

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

The input schema already provides 100% descriptive coverage for both parameters (package and version, including scoped package handling and default-latest behavior). The description adds no new parameter-level meaning beyond what the schema states, so the baseline of 3 applies.

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

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

The description uses a specific verb ('check') and clearly defines the composite scope: a one-call evaluation of whether to add an npm package, fanning out to deps.dev and bundlephobia. It names concrete data points (license, advisories, bundle size, tree-shaking) and the intended question ('is X safe / popular / small'), distinguishing it from sibling tools focused on other domains.

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 trigger: 'Use whenever an agent asks...' with concrete example phrasings. It also gives clear exclusions and alternatives: NPM only in v1, with other ecosystems falling under deps.dev:version directly. This tells an agent exactly when to choose this tool over simpler 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?

While annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral context: mentions BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, the 200K character cap, and that longer inputs are truncated and flagged. It also discloses that results include character offsets and similarity scores, which 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 compact but dense: the opening sentence states the core action, the middle explains usage, and the final sentence covers technical limitations. Every sentence provides unique value, with no filler or tautology. It is appropriately front-loaded with the most important purpose information.

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

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

Despite no output schema, the description tells the agent exactly what to expect: 'top-N passages with character offsets and similarity scores.' It covers input constraints (character cap), algorithmic nuances (overlapping windows), and integration with sibling tools. The tool's complexity is fully addressed, making it nearly self-contained for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical semantics by framing 'text' as content already pulled (e.g., SEC 10-K body) and clarifying that 'limit' yields 'top-N passages.' It reinforces the natural-language nature of 'query' with concrete examples, and explains that the text parameter is subject to a 200K truncation cap, adding meaning 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 'Semantic search INSIDE a fetched record,' a specific verb+resource pairing that clearly distinguishes this from sibling tools like ask_pipeworx. It further differentiates by emphasizing that it operates on text already retrieved, in contrast to question-answering tools, and describes the exact output (passages with offsets and scores).

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 when the record is too big to cram into the prompt.' It also provides a direct alternative/complement: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document,' giving clear guidance on how it fits into a workflow.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful context about the specific content returned (operational state, maintenance windows) without contradicting annotations. This extra context goes beyond the annotations, earning a 4.

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, front-loaded sentence that immediately states the tool's subject ('OKX exchange system status') and its key details. Every word serves a purpose, 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?

Given the tool has no parameters, is read-only, and has an output schema (per context signals), the description adequately covers the essential purpose and content. It does not need to explain return values because the output schema exists. The description is complete for this simple 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, so the description does not need to explain parameter semantics. Per the guidelines, a tool with no parameters receives a baseline score of 4. The schema coverage is trivially 100%.

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 reporting OKX exchange system status, including operational state and maintenance windows. It distinguishes this from sibling tools like ticker or candles, which focus on market data. However, it lacks an explicit verb like 'get' or 'retrieve', so it is not a 5.

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 this tool should be used when checking exchange operational status, but it does not explicitly state when to use it over alternatives or provide any exclusion criteria. There is no direct guidance on usage timing, so it earns a 3.

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

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

The description adds substantial behavioral context beyond the annotations: OAuth requirement, phone verification for SMS, 10/day SMS cap, webhook auto-disabled after 10 consecutive failures, and signing secret returned only once. Annotations only cover readOnly, openWorld, idempotent, and destructive hints, so the description carries significant extra weight and does so well.

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

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

The description is dense and front-loaded with the core purpose, then covers requirements, supported types, and delivery options. It is long but every sentence adds necessary information. A more structured bullet layout could slightly improve readability, but the current format is efficient for the complexity involved.

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 explicitly mentions the return value (new subscription id) and the one-time webhook secret. It covers all required parameters, optional delivery channels, authentication prerequisites, and edge-case behaviors (verification, caps, auto-disable). The tool has nested objects and multiple subscription types, and the description is fully adequate for an agent to use 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?

While the schema already provides 100% parameter coverage, the description enriches the schema with concrete examples: sec_8k items, polymarket_edge topic, fred_series series_id, and detailed delivery channel semantics (verified phone, 10/day cap, webhook HMAC signature). This goes well beyond the schema's terse property 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 action: 'Create a proactive monitoring subscription to a live-data event stream' and lists supported subscription types with examples. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and returning the new subscription id.

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

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

The description provides clear context: requires a Pipeworx OAuth account, anonymous/BYO cannot persist, and explains the always-on feed versus optional email/SMS/webhook delivery channels. It mentions pulling alerts via recent_alerts as an alternative for consumption, but does not explicitly mention alternative tools like list_subscriptions or unsubscribe for managing subscriptions.

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 it read-only, idempotent, open-world, and non-destructive. The description adds valuable behavior details: it returns category-bucketed questions, each with tool and argument shape, and pulls from a live catalog, which helps the agent understand what to expect.

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

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

The description is dense but well-organized, front-loading example queries and clearly explaining categories, parameter usage, and onboarding value. It's a single block of text that could be more structured, but every sentence contributes meaning.

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

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

Despite no output schema, the description fully explains what the tool returns, the categories covered, how to call it, and its relationship to meta-tools. This is sufficient for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% and the parameter description already enumerates focus areas. The tool description reinforces the topic parameter with examples but adds no new semantic information beyond what the schema provides.

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

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

The description clearly states what the tool does: it returns category-bucketed example questions with the exact tool and argument shape. It distinctly positions itself as the onboarding entry point, differentiating it from sibling tools like discover_tools or ask_pipeworx.

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

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

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to use the optional topic parameter. It lacks an explicit 'when not to use' statement but provides strong contextual 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 readOnly, idempotent, and non-destructive behavior, so the description only needs to add context beyond that. It adds the data fields returned and instrument examples, but no further behavioral caveats (rate limits, auth, etc.). This is limited additional value.

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

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

Two sentences, front-loaded with the tool's identity and scope. Every sentence provides distinct information (what it is, what it returns, when to use it). No fluff 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?

The tool is simple (one parameter, read-only, has an output schema). The description covers purpose, usage, and parameter format adequately for an AI agent to select and invoke it correctly. Sibling differentiation is implicit and sufficient.

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 only defines instId as a string with no description (0% coverage). The description compensates with concrete examples ('BTC-USDT', 'BTC-USD-SWAP') and the OKX context, adding meaningful semantics for parameter values 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 this is a single instrument ticker for OKX, with a specific verb 'Returns' and lists the data fields (bid/ask, last, 24h vol/change). It distinguishes from sibling tools like 'tickers' by explicitly saying 'single instrument' and gives concrete examples.

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

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

It explicitly advises 'Use for current pricing of an OKX-listed instrument,' providing clear usage context. It does not name alternatives or exclusions, but the 'single instrument' phrasing contrasts with the plural 'tickers' sibling, implying scope.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds context about bulk enumeration and OKX scope, which goes beyond the 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?

Two sentences, front-loaded with the core function, followed by usage and an exclusion. Every word earns its place with no redundancy.

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

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

The description, combined with strong annotations and an output schema, covers purpose, usage, and constraints. The main gap is under-explained optional parameters, but this does not critically hinder selection or invocation.

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

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

Schema description coverage is 0% and the description only explains instType by listing allowed values. The optional parameters uly and instFamily are not clarified, leaving their meaning and usage ambiguous.

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 returns OKX bulk tickers by instrument type, with explicit types listed. It distinguishes from a general stock-ticker search and from the sibling 'ticker' tool by focusing on bulk enumeration.

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

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

Explicit guidance is given: 'Use to enumerate all spot or all perp instruments' and 'NOT a general stock-ticker search — use polygon-io/tickers for that.' This provides both positive use cases and an alternative for a different 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?

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds context beyond those hints by specifying the return value (Unix milliseconds) and the source (OKX server), improving the agent's understanding of what to expect. 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 two concise sentences. It front-loads the core function, then adds practical usage guidance. No wasted words or repetition of schema info.

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 zero-parameter scope, clear annotations, and presence of an output schema, the description sufficiently covers the tool's purpose and behavior. It is complete for an AI agent to select and invoke correctly.

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

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

The tool has zero parameters, so the baseline score is 4. The description does not need to explain parameters, and the empty input schema aligns with the tool's simplicity.

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: 'OKX exchange server time in Unix milliseconds.' This identifies the specific resource (OKX exchange server) and output format, setting it apart from sibling tools that deal with market data or other 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?

The description provides explicit use cases: 'Use to synchronise request timestamps or verify API connectivity.' It tells when to use the tool but does not explicitly mention alternatives or exclusions, which is acceptable given that this is the only time-related tool among siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read. The description adds that it returns price, size, side, and timestamp, implying individual trades. It doesn't cover limit behavior or ordering, but with annotations the bar is lower.

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 concise sentences with front-loaded purpose and zero filler. The first sentence states what it is, the second adds returns and use case.

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 market data tool with output schema and rich annotations, the description covers purpose, return fields, and use case. However, the undocumented 'limit' parameter is a gap, preventing a perfect score.

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 has no descriptions (0% coverage). The description mentions 'an instrument' which maps to instId, but does not explain the 'limit' parameter at all. Examples in the schema show usage, but the description itself adds little for 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?

Clearly states 'recent trade tape for an instrument' on OKX and lists returned fields. This distinguishes it from siblings like order_book and candles by focusing on trades.

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?

Says 'Use for tick-level execution analysis on OKX,' giving a concrete use case. It does not explicitly name alternatives or when-not-to-use, but the context 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 the annotations, the description reveals that ownership is enforced and that the row is deactivated rather than deleted. This explains side effects and why historical alerts remain accessible via recent_alerts, providing valuable behavioral context for a mutation tool.

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-loads the action, and every clause adds meaningful information. No filler or redundancy.

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

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

For a single-parameter tool with no output schema, the description covers the operation, ownership constraints, the soft-delete behavior, and downstream effects on recent_alerts. This is fully sufficient for an agent to predict outcomes.

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

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

The input schema already documents the 'id' parameter fully ('Subscription id (uuid) returned by subscribe') with 100% coverage. The description adds no additional parameter-level detail, 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 opens with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing on the cancellation action.

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 communicates when this tool is appropriate—cancelling a subscription—and adds ownership constraints. It does not explicitly list alternatives or say 'use list_subscriptions first,' but the context is clear enough for an agent to invoke 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, idempotentHint=true, and destructiveHint=false. The description adds crucial behavioral disclosures beyond annotations: the precise meaning of 'could_not_verify' (check did not happen, must not be interpreted as evidence, includes verification_error payload) and 'unsupported' (no source found). It also explains return structure with verdict set, citation, and reasoning. This is significant value-added 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?

Description is long but every sentence adds essential information. It front-loads the purpose, then flows through routing, return values, and critical caller-facing warnings ('IMPORTANT for callers'). The use of paragraph breaks and structured enumeration helps readability. No filler or repeated annotation content.

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

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

Even without an output schema, the description fully covers what the agent needs to interpret results: complete verdict enum, distinction between 'could_not_verify' and 'unsupported', citation format, and the dual-pipeline behavior. It also addresses edge cases and explicitly states what not to do with a verdict type. For a complex tool with only 2 parameters, this is highly self-sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description enriches both parameters substantially: for 'claim' it provides concrete examples; for 'tolerance_pct' it explains how it overrides implied tolerance, gives a default behavior ('capped at 5'), and recommends 1–2 for hallucination detection. This goes beyond the schema's minimal descriptions and aids correct invocation.

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

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

Description clearly states the tool's core function ('natural-language claim verification against authoritative sources') with strong verb-resource pairing. It provides concrete query examples and distinguishes itself from generic search by explaining the structured SEC/XBRL fast path for company financials versus the grounded pipeline for all other claims. This sets it apart from sibling tools like ask_pipeworx or deep_research.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies that it replaces 4–6 sequential calls, implying efficiency advantage over alternatives, but does not explicitly name sibling tools or provide 'when-not-to-use' guidance. The dual-path routing gives context on internal decision logic.

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