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?

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior; the description builds on this by disclosing that the tool routes internally, auto-fills arguments, and returns stable citation URIs. It adds meaningful behavior beyond the raw hints, though it does not address rate limits, failure modes, or live-news edge cases.

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 key instruction and packed with useful trigger phrases, examples, and routing rules, but it is longer than strictly necessary and repeats the 'prefer over web search' idea. Every sentence adds some value, though some trimming of the example list would tighten it.

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 trivial input contract (one required natural-language string), the no-output-schema context, and rich safety annotations, the description covers what the tool does, when to use it, what it returns, and how it differs from deep_research. It is more than sufficient for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% and the schema already documents 'question' plus all aliases. The description contributes natural-language examples and domain signals, but these are illustrative rather than additive parameter semantics, so the baseline score for a fully covered schema 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 directive ('PREFER OVER WEB SEARCH') and clearly identifies the resource: it routes factual questions to one of 5,767 tools across 1,506 verified sources and returns structured answers with pipeworx:// citation URIs. This is a concrete verb+resource statement that differentiates the tool from web search 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?

It explicitly states when to use the tool ('Use whenever the user asks...' 'START HERE for most questions') and when not to ('For a broad/multi-part question... use deep_research'). It also gives trigger phrases, contrasting examples, and notes that it should be preferred even when web search is a viable alternative.

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

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

Annotations already declare readOnly, openWorld, and idempotent behavior. The description adds valuable context beyond this: it is a full working router rather than a stub, it currently matches ask_pipeworx exactly because no candidate is active, and experimental improvements may be enabled live during tests. This is strong behavioral disclosure.

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

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

The description is compact and front-loaded with the core identity of the tool. The specific details about tool counts, dates, and fallback behavior earn their place for an experimental router, though the phrasing 'Falls back to nothing' is slightly indirect and could be clearer.

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

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

The description covers the tool's current state, its relationship to the stable router, usage guidance, and the fact that it is fully operational. With no output schema present, some return-shape detail is referenced only as 'same response shape' as ask_pipeworx, but the agent can resolve this through the sibling tool, so the description is reasonably complete.

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

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

The input schema already documents all parameters with 100% coverage, including the question parameter and its aliases. The description only restates that arguments are identical to ask_pipeworx, which adds little beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,767 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge for routing improvements, and the current inactive-candidate state makes its exact behavior concrete.

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 to use it exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router to decide merges. This gives the agent a clear decision rule and names the relevant alternative.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, and the description goes well beyond that. It discloses that answers are extracted only from tool results, returns verbatim evidence, refuses rather than invents when data is insufficient, and enumerates the exact refusal reason codes.

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

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

The description is dense but well-structured and front-loaded with the core value proposition. It covers routing, output contract, refusal behavior, use cases, and cost tradeoff without redundant fluff. Every sentence contributes useful decision-making 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, so the description correctly takes responsibility for describing return values and failure modes. It fully explains what success looks like, what refusal looks like, when to use the tool, and how it relates to ask_pipeworx. Nothing an agent needs to call it correctly is missing.

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

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

The input schema has 100% coverage and documents the question parameter plus all six aliases clearly. The description does not add parameter-specific guidance, but with full schema coverage it does not need to; 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 states a specific verb and resource: it is a hallucination-resistant answer mode that routes through Pipeworx, fetches data, and extracts answers only from the tool result. It clearly distinguishes itself from ask_pipeworx by emphasizing grounded, evidence-backed answers for high-stakes reads.

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 when to use the tool — whenever an answer will be quoted, cited, or acted on, with examples like financial verdicts, legal claims, and medical lookups. It also gives an explicit exclusion: prefer ask_pipeworx for casual lookups, and it names the cost tradeoff of an extra LLM call.

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

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

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 declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is already covered. The description adds substantial context beyond annotations: account gating and paid depth tier, parallel tool routing, verbatim-evidence output shape, gaps[] honesty, hop field, citation_uri fetchability guarantee, excerpting behavior, expected latency, and contradictions[]. No contradiction with annotations; it even explains the openWorldHint nuance by clarifying it is grounded over structured sources rather than open-web.

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?

A long description, but every sentence earns its place: each clause adds a distinct behavior, constraint, or alternative. Information is front-loaded with the account requirement, then core behavior, then use cases, then output details and latency. Minor redundancy (depth details appear in both the description and schema enum) keeps it from a 5.

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

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

Completeness is high for a complex research tool with 2 params, no output schema, and 5,767 underlying tools. It tells the agent what the return packet looks like, what fields each finding carries, how citation URIs behave, what happens for unanswerable facets, how excerpting works, and expected latency. The only minor gap is not detailing the exact full output envelope, but the findings-packet description plus absence of an output schema makes this 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 the baseline is 3 even though the description doesn't repeat parameter details. The description adds meaning beyond the schema by explaining depth levels ('standard=3 (default; adds a gap-recovery hop... contradictions[] scan)', 'thorough=6 (paid...)'), which is genuinely useful. It doesn't add much for 'question' beyond the schema, but that parameter is self-explanatory.

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

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

The description states a specific verb ('researches'), a resource ('Pipeworx's 1506 STRUCTURED data sources'), and a distinctive behavior (parallel decomposition across 5,767 tools, NOT open-web search). It clearly distinguishes itself from sibling ask_pipeworx and ask_pipeworx_grounded, so an agent can tell them apart without opening schemas.

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

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

Explicitly says when to use it ('broad/multi-part questions over structured data') and when not to ('single lookup' → ask_pipeworx; 'breaking/current news' → ask_pipeworx). It also names the account requirement and fallback alternative if not signed in. This is model guidance with concrete conditions and sibling names.

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?

Beyond the readOnly/opensWorld/idempotent annotations, the description discloses substantial behavior: parallel fan-out, per-source fallback (GDELT→GNews), soft-failure of the USPTO patents source after April 2025, and the semantic that an empty fda_products section is expected for non-biologic companies. It even states that empty sections are real 'no data' rather than bugs, and that sources_used/sources_failed indicate what actually returned 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 long and dense, but the length is justified by the tool's many output sections and fallback behaviors. It is front-loaded with the most important instruction ('ALWAYS PREFER over chaining single-pack lookups') and structured so an agent can quickly identify invocation rules, accepted inputs, and expected empty-section semantics. A slightly more organized layout would earn a 5.

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

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

Even with no output schema, the description enumerates every notable return field (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/sources_failed) and explains what counts as expected non-data. It also covers all accepted input forms and resolution behavior, making it complete enough for an agent to invoke correctly.

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

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

The input schema already covers 100% of the parameter meanings, including accepted value shapes and the interchangeability of type values. The description reinforces this with examples and mentions name resolution, but does not add substantial semantic meaning 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?

The description opens with concrete example queries and a definitive purpose: 'full cross-source profile of a US public company in ONE parallel call.' It also differentiates itself by explicitly recommending it over chaining single-pack SEC/XBRL/news lookups, and it enumerates exactly which data sources are fanned out across.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies expected edge cases, such as private companies returning resolved:false with an explanatory notes line rather than a bare failure, which tells the agent when the tool is still appropriate.

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

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

Annotations already 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 cover readOnly, idempotent, openWorld, and non-destructive behavior, so the description does not need to repeat those. It adds useful context by identifying the exchange (OKX) and timeframe (current), but it does not disclose behaviors like staleness, settlement-time interpretation, or any API limitations.

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 entire description is one dense sentence with no filler. It front-loads the main object and result fields while adding a concrete example. Every phrase contributes to selecting and invoking the tool.

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

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

The tool has a single parameter and an output schema, so the description does not need to spell out return structure. It supplies the name of the exchange, the instrument type, and the output categories. It is slightly thin on when to use it or how the 'current' rate interacts with settlement timing, but given annotations and output schema, it is largely complete.

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

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

With zero schema-level description coverage, the description must clarify the instId parameter. It does so by labeling the required parameter as a SWAP instrument and giving the exact expected format ('BTC-USDT-SWAP'), which is essential since the raw schema only names it as a string. This sufficiently compensates for the missing schema text.

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 resource (OKX perpetual swap funding rate) and the specific kind of instrument ('SWAP' with example 'BTC-USDT-SWAP'), while also stating the key output fields ('funding rate, next settlement time, and method'). It is distinct from the history-focused sibling tool by emphasizing 'current.'

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 conveys that this is the current-rate snapshot and requires a SWAP instrument, which implies use cases. However, it does not explicitly mention when to prefer funding_rate_history or other market-data siblings, nor any exclusion criteria such as spot instruments.

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 read-only and idempotent behavior is already conveyed by annotations. The description adds useful behavioral context beyond this: optional before/after ms-epoch cursors and limit, and the historical nature of the data. It doesn't contradict annotations, though it omits pagination direction and API limits that would be minor additions.

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, with the core purpose front-loaded, then only relevant parameter context and a use case. No filler or repetition of the tool title.

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 a simple schema, read-only annotations, and an output schema, so the description can rely on those. It covers the key inputs and use case, but would be more complete if it explicitly settled the meaning of `after` vs `before` in cursor terms or stated default result ranges.

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 compensates by explaining `before`/`after` as ms epoch cursors, `limit` as an optional numeric cap, and `instId` with a concrete SWAP example. This is meaningful but not fully exhaustive—'before' and 'after' directionality is not explicit, and default/limit behavior is unspecified.

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 resource ('OKX crypto exchange historical perpetual swap funding rates') and the exact instrument format ('SWAP', e.g. 'BTC-USDT-SWAP'). It differentiates from the sibling `funding_rate` by emphasizing historical data, making the purpose unambiguous.

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

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

It gives a clear intended use context, 'funding cost analysis', and identifies the data scope. However, it does not explicitly mention sibling alternatives (e.g., `funding_rate` for current rates) or state when not to use this tool, so it falls short of full routing guidance.

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

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

The description discloses 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond annotations: it explains the interpretation of the value ('A value above 1 means more accounts sit long'), mentions the period bucketing, and specifies the venue (OKX). This enriches understanding without contradicting annotations.

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

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

Three sentences with zero filler: definition, interpretation, and usage. The key information is front-loaded, and every sentence adds value. This is concise and well-structured.

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

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

Given the lack of an output schema, the description conveys the core return semantics (the ratio, interpretation, and bucketing). It relies on the schema for default values, which is acceptable. Minor gaps: the instId is implied to be an OKX perpetual but not explicitly described, and there is no mention of edge cases or response format. Still, the essential context is covered.

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

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

The schema already provides descriptions for period and buckets (67% coverage). The description adds the concept of the ratio and bucketing by period, but does not elaborate on the instId parameter (e.g., the specific format or contract naming) or add new details beyond what the schema gives. It neither fully compensates for the uncovered instId nor contradicts 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 precisely states the tool returns the long/short account ratio for a crypto perpetual on OKX, and defines the metric ('ratio of accounts holding longs to accounts holding shorts'). This clearly separates it from sibling metrics like funding_rate or open_interest by naming the specific resource and the sentiment interpretation.

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 an explicit use case: 'Use for positioning and crowd-sentiment reads on a perp.' It provides clear context for when the tool is appropriate, though it does not explicitly say when not to use it or compare it to alternative tools (e.g., funding_rate, open_interest).

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 establish the tool is read-only, idempotent, and non-destructive. The description adds behavioral transparency beyond that by revealing accepted symbol formats ('MASKUSDT', 'MASK', 'MASK-USDT-SWAP') and the output fields (contracts outstanding, coin size, USD notional, timestamp). It does not contradict annotations.

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

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

Three sentences, each earning its place: the first defines the data returned, the second gives input examples, the third states a use case. No filler or repetition.

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

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

With no output schema, the description covers the return fields explicitly. It also handles the primary input ambiguity (instId format). It omits details like default instType behavior (already in schema) and possible time ranges or historical depth, but for a simple snapshot tool this 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 schema only describes instType, leaving instId as a bare string. The description compensates for this gap by giving concrete example formats and clarifying that these map to perps or futures. This adds meaningful guidance beyond the schema's 'string' type, although it does not exhaustively define all possible instId formats.

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

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

The description states a specific verb and resource: it retrieves open interest for crypto perpetual swaps or dated futures contracts on OKX. It also lists the exact return contents (contracts outstanding, coin-denominated size, USD notional, timestamp), making the purpose unmistakable and distinguishing it from other market data tools like order_book or funding_rate.

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 context for use ('Use to size how much leverage is riding on a perp'), which guides when to invoke it. However, it does not name alternatives or give explicit when-not-to-use conditions, so it stops short of full discriminative 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, 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 already mark this as read-only, idempotent, and non-destructive, so the description doesn't need to repeat safety cues. It adds valuable behavioral context beyond the annotations: data comes from OKX, the response labels the venue, and symbol variants resolve to the same contract. This meaningfully informs an agent about cross-venue behavior.

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

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

The description is compact and front-loaded with the core purpose, then covers symbol flexibility and venue behavior in two additional sentences. Every sentence earns its place without redundant phrasing or filler.

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

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

For a read-only data snapshot with no output schema, the description adequately covers what the tool returns, how symbols are interpreted, and the venue caveat. The schema covers remaining parameter details, so an agent has what it needs to select and invoke the tool correctly.

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

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

The input schema covers 100% of parameters with detailed descriptions, including defaults, allowed values, and symbol normalization examples. The tool description adds no parameter-specific semantics beyond the schema, 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 names a specific action—taking a 'snapshot in one call'—and lists the exact metrics included (funding rate, open interest, taker buy/sell volume/CVD, long/short ratio). It also differentiates this combined tool from the individual metric sibling tools by emphasizing that all data comes in a single call.

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 makes the use case clear: when an agent needs multiple perp metrics at once, this tool is the one-call option. It also provides important venue guidance by explaining that OKX is the data source and that non-OKX symbols are resolved to OKX contracts, which helps avoid incorrect assumptions about venue.

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?

The description goes far beyond the read-only, idempotent, non-destructive annotations. It discloses the fee treatment (gross spreads only, no Kalshi fee model), the pairing verification caveat, compatibility codes, skipped comparisons, temporal alignment semantics, and the meaning of null fields. This is exceptionally rich behavioral disclosure.

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

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

The description is long but well-structured with labeled sections, front-loaded purpose, and dense safety warnings that justify the length. It is not perfectly concise, but every major block earns its place for a tool with this many caveats.

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

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

With no output schema, the description carries the full burden of explaining the response, and it does so thoroughly: top_spreads_pp, compatibility fields, temporal alignment, fees_note, skipped counters, and low_confidence_pairs are all described. An agent has enough to call the tool correctly and interpret results safely.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value by explaining that both modes run the same matcher, that explicit tickers override the topic-mapped side, and how the three parameters interact. This elevates it above the schema-only baseline.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, with explicit modes and a defined response shape. It distinguishes itself from Polymarket-only siblings by focusing specifically on the Kalshi–Polymarket comparison.

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 topic shortcuts versus explicit event identifiers, and warns that most pre-mapped topics are not tradeable. It does not explicitly name alternative sibling tools or say when not to use this tool, but the mode guidance and strong cautionary note give clear operational 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 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 indicate readOnly and idempotent, so the safety profile is covered. The description adds substantial behavior beyond annotations: cascades through multiple lookup endpoints, degrades gracefully when enrichment sources are unavailable, returns figi_candidates on ambiguity, and explicitly reports unresolved identifiers rather than omitting them. This gives the agent an accurate model of what to expect.

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

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

The description is long and dense, but nearly every sentence carries useful behavioral or semantic information. It is front-loaded with trigger examples and a clear mission, then supports that with type-specific details. It could be better structured with paragraphs or bullet-like separation, which prevents 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 tool with 2 params, no output schema, and notable edge cases, the description is exceptionally complete. It covers accepted values, failure/ambiguity behavior, unsupported identifier scenarios, source attribution, and fallback behavior. An agent has everything needed to invoke it and interpret the result.

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 major practical meaning beyond the schema. It provides examples ('AAPL', 'CH0038863350'), explains that the value should be the entity name only and never the full noun phrase, and details how ISINs map to legal entities via GLEIF. This level of disambiguation is essential for 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?

The description states a very specific goal: resolving user-spoken names to canonical/official identifiers that other tools require. It enumerates concrete trigger phrases, lists supported entity types, and explicitly names the identifier outputs (CIK, ticker, LEI, FIGI, RxCUI). This clearly differentiates it from sibling tools like ticker, entity_profile, or instruments, which are not name-to-ID resolvers.

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 an explicit when-to-use instruction: 'Use FIRST whenever you have a name but need an ID.' It also explains what inputs are accepted for each type and clarifies edge cases like bonds and ISINs. It does not explicitly name alternative tools or state when not to use it, but the 'when' guidance is strong enough for an agent to route 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 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 establish that the tool is read-only, non-destructive, and idempotent, so the description does not need to restate those. It adds meaningful behavioral detail by specifying exactly what is returned: per-bucket series, buy/sell ratio, and cumulative volume delta, which goes beyond the annotation metadata.

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

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

The description is a single focused sentence with no filler. It front-loads the core metric and venue, then packs the key return values and analytical use case into the closing clause without redundancy.

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

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

For a simple read-only tool with four parameters and no output schema, the description covers the essential domain context, the return shape, and the analytical purpose. It could go slightly further by noting default behavior around periods or buckets, but the schema already documents those defaults.

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 75%, so most parameters are already documented. The description adds value for the undocumented instId by clarifying that it refers to a crypto perpetual contract on OKX, and it reinforces that period controls the bucketing behavior.

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

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

The description names a precise resource and metric — taker buy versus taker sell volume for a crypto perpetual contract on OKX — and immediately differentiates it from generic volume or trade tools by stating it returns the buy/sell ratio and CVD. It clearly identifies the output series, not just an abstract 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 gives an implied use case by calling it 'the aggressor-flow input for order-flow and CVD analysis,' so an agent can infer when it is relevant. However, it does not explicitly state when to prefer this over related tools like trades, candles, or perp_metrics, nor does it name any 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 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.