Degenscan Intel

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

Annotations already cover safety (readOnly, idempotent, openWorld, non-destructive), and the description adds materially beyond them: an explicit price of $0.005/call, the full result shape, and the comparison output structure. It does not mention failure behavior for unreachable or non-HTTPS URLs, but the paid-call cost disclosure is a genuine value-add.

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?

Purpose and output shape are front-loaded and dense, which is good, but the final 'Use to audit whether...' clause largely repeats the opening sentence and its parenthetical list. One redundant sentence against an otherwise efficient block keeps this at adequate rather than exemplary.

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 describing returns and does so by naming score, grade, checks[], fixes[] and the comparison fields. The eight check identifiers are listed but not individually explained, a minor gap for an agent deciding whether this audit covers what it needs.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by specifying what passing peer actually produces — comparison {score_gap, behind_on[], ahead_on[], fix_first[]}. That tells an agent the comparative semantic payoff of the optional parameter, which the schema alone does not.

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

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

Opens with a specific verb and resource — 'Audit a public HTTPS API for AI-agent discoverability and payability' — then enumerates the concrete outputs (score 0-100, grade, checks[], fixes[]). No sibling in the provided list audits agent-readiness, so the tool is unmistakable against neighbors like ai_adoption or product_brief.

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 closing sentence 'Use to audit whether a public API can be found and paid for by AI agents' restates purpose rather than giving selection criteria. The peer parameter is the only conditional guidance ('Add peer=... to compare'), and there is no statement of when not to use it or which sibling to pick instead.

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

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

Annotations already cover readOnly, idempotent, non-destructive and openWorld, so the safety profile is settled. The description adds material context the annotations do not carry: the $0.003/call price and the exact metric set (last_7d, prior_7d, wow_pct). It stops short of describing return shape or any rate/refresh cadence, which is the main remaining gap given there is no output schema.

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 dense sentences, metrics and filter values front-loaded, price disclosed without preamble, and no filler. The parenthetical value list is long but each token is load-bearing, so the density is justified.

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

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

For a read-only, single-optional-parameter metrics tool whose safety traits are already in annotations, the description supplies everything needed to invoke it correctly: what it measures, the accepted filter values, and the per-call cost. Only the omission behavior for 'kind' and the exact response shape are unstated, and the latter is partly implied by the named metrics.

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 schema has no enum, so the description carries the whole burden for the single 'kind' parameter — and it delivers by enumerating all eight accepted values (model_sdk, framework, agents, rag, serving, vector_db, models, agent_payments). It does not say what happens when 'kind' is omitted, but the value list is the critical piece an agent needs.

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 concrete resource and metrics ('weekly npm + PyPI downloads... and GitHub stars for AI SDKs and frameworks'), so an agent knows exactly what data comes back. It does not explicitly distinguish itself from nearby siblings such as ai_models or ai_cost, but the ecosystem-adoption framing is specific enough to be 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 states a clear use case: 'Use to see which AI SDKs/frameworks are growing (downloads, stars).' That tells the agent when to reach for it, but there is no explicit exclusion or named alternative for adjacent questions like pricing or model capability.

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, open-world behavior, so the safety profile is covered. The description adds useful context (per-call price of $0.001 and the ranking methodology), but with no output schema it still never describes what the response contains, which is a real gap for a lookup 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 lead sentence is well front-loaded, but the trailing 'Use to pick the cheapest LLM that supports what you need (tools, vision, json, context)' largely restates the opening, repeating the same capability list rather than adding new 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 no output schema and 0% param coverage, the description carries the full burden but leaves return structure, 'limit' behavior, and 'provider' filtering undefined. An agent could invoke it but cannot predict the result shape or how to use several parameters.

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 0%, so the description must define all four params, but it only addresses two. 'needs' gets example values (tools, json, vision, reasoning, audio, pdf) and 'min_context' is named, yet the syntax of 'needs' and the roles of 'limit' and 'provider' are completely undocumented.

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 purpose: return the cheapest models that satisfy capability needs, ranked by blended USD per 1M tokens with a stated 3:1 in:out ratio. This distinguishes it from generic cost tools (ai_cost) and listing tools (ai_models), though it never explicitly names those siblings.

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 affirmative usage cue ('Use to pick the cheapest LLM that supports what you need'), but provides no when-not guidance, no alternatives, and no prerequisites. The agent must infer that ai_cost or ai_models cover other needs.

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/non-destructive/openWorld, and the description adds real value on top by describing the return payload (per-item fields plus a cheapest field) that no output schema provides. It gives a sample cost ("$0.002/call"), though it doesn't state whether models outside the list error out or are skipped.

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 return shape and squeezed into a few dense sentences with no filler. The telegraphic style ("items[] {id, usd_per_call...}") is efficient, if slightly cryptic on first read.

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 does the work of explaining the return shape, which is a genuine strength. However, for a 4-parameter tool with only 25% schema coverage it leaves the token-definition parameters unexplained, so an agent cannot confidently construct a workload.

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?

Only 'models' is covered by the schema description; the 25% coverage leaves calls, input_tokens, and output_tokens undocumented. The description gestures at N calls and 'workload' but never explains that workload is defined by input_tokens/output_tokens, or what happens if they are omitted, so it does not compensate for the 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?

States a specific verb and resource: computes cost per call and for N calls across a listed set of models, and returns items[] with id, usd_per_call, usd_total, fits_context, plus cheapest. It does not differentiate itself from the ai_cheapest or ai_models siblings, which keeps it off 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?

"Use to estimate what a workload costs on several LLMs before choosing one" gives a clear use context and timing. It names no exclusions and doesn't point to ai_cheapest or ai_models as alternatives, so the routing guidance is incomplete.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world. The description adds the material fact annotations cannot carry: '$0.002/call', which is essential for a metered tool. It also discloses the return payload structure, which helps the agent decide before paying. It stops short of stating catalog freshness or result truncation 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?

Dense, front-loaded, and every clause carries information: item shape first, then filters, then sort, then price, then purpose. The telegraphic style leans on shorthand but remains parseable. No filler sentences.

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's item field list is doing necessary work and it delivers the fields an agent needs to compare models (per-1M input/output pricing, context, max_output, capability flags). Cost, filters, sorting, and usage are all covered; only `limit` is missing, which is minor.

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

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

Schema description coverage is 0%, so the description carries the burden and largely meets it: it enumerates the accepted `needs` values (tools, json, vision, reasoning, audio, pdf) and the `sort` modes, plus provider and min_context intent. The `limit` parameter (1-100, the only bounded param) is never mentioned, which is a real omission for result sizing.

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?

States the specific resource and scope precisely: '~450 LLMs' with a defined item shape (id, provider, context, max_output, input_per_1m, output_per_1m). It does not differentiate itself from siblings ai_cheapest and ai_cost, which cover overlapping price-comparison ground, so an agent can't tell from the description alone which to 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?

'Use to list or filter LLMs by price, context and capabilities' gives implied usage, and the sort/filter options hint at when it's appropriate. But with ai_cheapest and ai_cost in the sibling set, the description never says when this catalog tool is preferred over those narrower price tools, leaving the routing decision to inference.

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, open-world, non-destructive, so the safety profile is covered; the description adds genuinely new context by disclosing the cost ($0.002/call) and the exact 30-day window behind the downloads ranking. It does not mention pagination, empty-result behavior, or failure modes for unknown task strings.

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 single dense paragraph that front-loads the return shape and ranking options, then the task list, cost, and use case. It is efficient with no filler, though the comma-spliced sentences and trailing ellipses make it slightly harder to scan than it could be.

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

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

With no output schema, the description usefully enumerates the returned item fields (id, url, downloads_30d, likes, trending_score, license, library) and states the price, which is enough to call the tool confidently. The only real gap is the undocumented limit/pagination behavior for a tool that can return up to 50 items.

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 carry parameter meaning and it only partly does: it enumerates plausible task values and implies the enum behind sort ('most downloaded (30 d), liked or trending'), and mentions license as a selection basis. The limit parameter (1–50) is never explained, and the license filter's matching semantics are left vague.

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?

States a specific resource (open models for a task) plus the source (Hugging Face Hub API) and the three ranking modes (downloads 30d, likes, trending). The phrase 'for a task' plus the task list differentiates it from the general sibling ai_models, so an agent can route between them without opening the schema.

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

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

Explicitly says 'Use to pick an open model for a task (speech-to-text, OCR, image classification, embeddings…) by real downloads and license', giving clear positive guidance with concrete scenarios. It stops short of naming when-not-to-use conditions or pointing to the ai_models sibling as the alternative for non-task-based lookups.

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 read-only, idempotent, open-world, non-destructive, so the safety profile is settled. The description adds valuable non-structured context: a per-call price ($0.002/call) and a 'not legal advice' disclaimer. It does not say what happens when jurisdiction is omitted (0 required params) or how 'status' is expressed, so coverage is partial.

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 useful jurisdiction/statute mapping, which is good. But 'Not legal advice' appears twice and 'Use for AI law dates and status' restates the opening clause, so roughly a third of the text is 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 does the work of indicating returns (dates, status, sources, next_milestone) and adding cost and disclaimer context. The only gap is behavior when jurisdiction is omitted, which matters for a 0-required-param 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 0%, so the description must carry the burden — and it lists all three enum values (eu, us_colorado, brazil) mapped to the specific laws they refer to, which is genuine meaning beyond the bare enum. It still doesn't state that jurisdiction is optional or what the default scope is.

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 resource (AI law dates, status and sources) and enumerates the three covered jurisdictions with their statutes (EU AI Act after Omnibus 2026/1744, Colorado SB 26-189, Brazil PL 2338/2023), plus the next_milestone field. It is clear what the tool returns. It doesn't differentiate from siblings, though none of the listed siblings are AI-law tools, so confusion risk is low.

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 the use case: 'Use for AI law dates and status (EU AI Act, Colorado, Brazil); not legal advice.' That gives a clear trigger and an explicit exclusion (not for legal advice). No alternative tool is named, but no sibling overlaps this domain, so the guidance is adequate.

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, non-destructive behavior, so the safety profile is covered. The description adds useful context beyond annotations: the arXiv data source, the 7/30-day windows, the weekly_pace_vs_30d metric, and the $0.002/call cost.

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: data source and metrics first, then valid topics, then cost, then usage guidance. Every sentence adds useful information without 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 data query with rich annotations and no output schema, the description gives enough context to understand the data source, time windows, metric, cost, and likely topics. It still omits the default behavior when topic is absent and does not describe the response shape in any detail.

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 0%, so the description must carry parameter meaning; it does so by enumerating valid AI topics such as rag, agents, fine_tuning, mcp, and reasoning. However, it does not clarify that topic is optional or what happens when it is omitted, leaving 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?

States a specific resource and measurement: new arXiv papers per AI topic over 7 and 30 days, plus weekly_pace_vs_30d. The topic list and use case make it clearly distinct from finance-oriented siblings such as ai_cost, ai_models, and ai_regulation.

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 to use it to see which AI research topics are accelerating on arXiv. It gives a clear use context but does not name when to choose a sibling instead or when not to use it.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive. The description adds two things annotations can't: the cost ($0.001/call) and the shape of the response including the block number. That is real added value beyond the structured fields, though pagination/rate-limit behavior is unstated.

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?

One dense sentence that front-loads the resource and return shape, then tacks on cost and use case. No wasted clauses.

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 the description enumerates the return fields (eth, usdc, token object with address/symbol/decimals/balance, block), which covers the main completeness burden. Missing only edge-case behavior such as errors for unverified tokens or unsupported chains.

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

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

Schema coverage is 100% and both params are documented in the schema, so baseline is 3. The description only clarifies that the token param maps to an optional ERC-20 result, adding little beyond what the schema already says.

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?

States a specific verb+resource with scope: the Base (8453) balance of one address, covering ETH, USDC and arbitrary ERC-20s. The chain ID and enumerated assets make it unmistakable against siblings like price_for or coin_snapshot.

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?

"Use to read a Base wallet's ETH, USDC or any ERC-20 balance now" gives a positive use case, but never names an alternative (e.g. price_for for quotes vs. this for holdings) or any condition for choosing otherwise. Usage is implied rather than routed.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds a genuinely useful non-annotation fact: the $0.1/call cost and the fact that it collapses ~6 calls into one. It stops short of stating auth needs, rate limits, or latency characteristics.

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 claim, but the payload list is a comma-choked run-on and the 'replaces ~6 calls' claim is stated twice, once mid-list and again in the final sentence. Trimming the duplication would make it materially tighter without losing 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 carries the full burden of explaining return contents, and it does so comprehensively (pressure/drivers, headlines, filings, exposure map, Polymarket odds, 7d catalysts, venue status/tradable_now). It also discloses cost, which is the other thing an agent needs before invoking a premium call.

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

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

Schema coverage is 100% and both parameters are documented in the schema, so baseline 3 applies. The description only echoes the 24h scope and the single-asset constraint already implied by asset_id; it adds no format or edge-case semantics beyond that.

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?

States a specific verb and resource ('One-call briefing for ONE asset') and then enumerates exactly what the briefing contains (net pressure, headlines w/ sentiment, SEC filings, exposure map, Polymarket odds, catalysts, venue status). It also distinguishes itself from siblings by naming events_since and impact_for as the many-asset alternative.

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 cadence guidance ('ideal once per asset per session or pre-open') and an explicit routing rule: use this for everything about ONE asset, use events_since + impact_for for many assets. Both the when-to-use and the when-not-to-use alternative are named.

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 this as a safe, idempotent read. The description goes beyond them usefully by disclosing the data sources/venues (Mercado Bitcoin, BCB PTAX, Coinbase) and the per-call cost ($0.002/call), which affects invocation decisions. It stops short of describing latency or response shape.

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 dense sentences with zero filler; the core comparison is front-loaded and the cost and usage boundary are appended compactly. Every clause carries distinct 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?

For a no-parameter, no-output-schema tool the description conveys the sources and the comparison basis well. It never says what the returned value looks like (premium in percent, bps, or a raw spread), which is the one remaining gap an agent might want before calling.

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 parameters there is nothing to document, so the baseline is 4. The description correctly spends no space on parameter syntax and instead clarifies the comparison basis, which is the only input-like ambiguity.

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

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

The description names the exact resource and scope: USDT/USDC-BRL on Mercado Bitcoin vs BCB PTAX, and BTC-BRL vs BTC-USD at both PTAX and the on-exchange USDT rate. This is specific enough that an agent can distinguish it from any sibling FX or pricing tool without opening a schema.

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

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

It states the use case explicitly ("Use for Brazil's crypto-dollar/BTC premium vs the official PTAX") and adds a negative boundary ("not for other FX"), which is genuine routing guidance. It does not name a specific sibling to use instead, so it falls short of a full 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds value beyond them: per-call cost ($0.002/call), the fact that coverage is limited to events 'seen in the feed', that times are ET, and that each event carries the assets it usually moves. It stops short of stating window truncation or empty-result behavior, which keeps it off a 5.

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 what is returned, then use cases, then cost, then routing. The closing clause ('Use for upcoming scheduled macro/earnings catalysts') partially repeats the opening and the earlier use-case sentence, so there is some redundancy, but each sentence still carries weight.

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, and the description compensates by naming the returned content (event times, affected assets). Cost, scope, and the sibling boundary are all present. A hint about the maximum 60-day window or behavior when no events match would make it fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's enumeration of event families loosely maps to the `types` filter and 'next N days' maps to `days`, but it says nothing about `min_impact` or how `universe` scopes earnings, so no real meaning is added 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?

States a specific verb+resource ('Upcoming scheduled catalysts for the next N days') and enumerates the exact content classes (macro prints, FOMC, auctions, earnings) with their timing basis (ET). It explicitly separates itself from the Treasury-auction sibling, so an agent can choose between them without opening a schema.

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

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

Gives two concrete use cases ('avoid holding through a print', 'schedule polling') plus an explicit routing rule: for Treasury auction details use treasury_auctions. That is when-to-use, why-to-use, and when-to-use-something-else in one place.

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/non-destructive, so the safety bar is low; the description adds genuinely useful context the annotations lack, namely that calls are billed ('$0.005/call or Carry key'), which implies an auth/key requirement. It does not disclose pagination, default lookback, or return volume for a historical scan.

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 tight sentences, front-loaded with the useful part (the metric list) and no filler. Minor redundancy between 'Past extreme episodes' and 'what happened after past funding extremes'.

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 usefully doubles as a return-value spec by naming the five metrics. However, for a parameterized historical scan it leaves the most decision-relevant facts unstated: what coin defaults to, what lookback window is used, and how 'extreme' is defined by min_abs_apr.

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% across three parameters, and the description explains none of them: 'coin' scope, 'days' (3–120 lookback window) and 'min_abs_apr' (the extreme-defining threshold) are left entirely opaque. The '4/12/24 h' horizons in the text are fixed output offsets, not the 'days' parameter, so they may even mislead.

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?

States a specific resource ('past extreme episodes') and enumerates exactly what is returned: onset, hours above threshold, half-life, price return and funding accrued at 4/12/24h. The word 'past' implicitly separates it from the sibling carry_extremes, which scans for current extremes.

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 second sentence gives a clear use case: 'Use for what happened after past funding extremes (price, funding accrued, half-life).' It does not name the alternatives (carry_extremes, carry_history, brief) or state when not to use it, so routing still requires the agent to compare 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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond annotations: default slippage assumptions (0.2% taker, 0.1% maker), the taker/maker1/maker2 mode distinction, and pricing ($0.001/call or Carry key). It still does not cover auth requirements, rate limits, or output format details.

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: it leads with the three computed outputs, then states modes, defaults, pricing, and intended use. Every clause carries information relevant to invocation, with no wasted prose.

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 rich safety annotations and no output schema, the description carries the burden of explaining returns and behavior. It names the three return metrics, default slippage values, mode options, and pricing, which is enough to invoke the tool with only the required spread_apr. The remaining gap is the unexplained lev parameter and lack of return-format detail, which are minor.

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 only 20%, so the description must compensate for the four undocumented parameters. It adds semantics for mode (taker/maker1/maker2) and for slippage via default values (0.2% taker, 0.1% maker), but it never explains the lev parameter or its role in net return on margin. This is partial compensation, not full coverage.

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

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

The description states a specific computational purpose: round-trip cost, break-even days, and net return on margin for a funding spread. It names the modes and slippage assumptions, so an agent can identify it as a fees/slippage break-even calculator. However, it does not explicitly distinguish itself from sibling carry_* tools, leaving sibling routing to inference.

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

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

The final sentence, 'Use to compute fees/slippage break-even for a funding spread,' gives an explicit use case. But it offers no conditions for choosing this over sibling tools such as carry_aftermath or carry_depth, and no when-not-to-use guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower. The description adds genuinely non-structured facts: pricing at $0.003/call or a Carry key, and that binning is by UTC weekday. It stops short of explaining what the response actually contains beyond the cryptic 'collapses_on_weekend' token.

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 compact sentences with the core output dimensions front-loaded and no filler. The only weakness is unexplained internal jargon ('collapses_on_weekend') that reads like a leaked field name rather than prose.

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 and 0% parameter documentation, the description is the only source of truth, yet it omits the meaning of 'days', the shape of the returned calendar (per-weekday rows? APR units?), and any differentiation from the many sibling carry tools. Pricing and timezone are covered, but key calling details are not.

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 carry parameter meaning. It clarifies the dex-vs-coin choice ('per dex (or one coin)') but leaves 'days' (integer, 7–120) entirely unexplained — the agent cannot tell whether it is a lookback window, a bucket count, or a limit.

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?

Names the specific resource and dimension: funding APR binned by UTC weekday, per dex or per single coin, plus a weekday-vs-weekend comparison and a 'collapses_on_weekend' flag. That is concrete enough to distinguish it from generic siblings like 'calendar', though it never explicitly contrasts itself with carry_funding_matrix or carry_history.

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 closing sentence 'Use for weekday/weekend funding patterns per dex or coin' gives a usage trigger, but there are no exclusions or named alternatives despite many adjacent carry_* tools (carry_funding_matrix, carry_history, carry_regime) that an agent could confuse it with.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds genuinely non-redundant context: per-call pricing ($0.002/call or Carry key) and a universe restriction to the top 40 traded perps, both of which affect whether an agent should call it at all.

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 compact sentences: payload first, usage second. Only minor waste is the third clause which largely restates the opening resource description.

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

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

For a simple two-parameter read tool with no output schema, the description covers what the data is and its cost. It omits the shape of the return (hourly series?), valid coin identifiers, and the default/limit for `hours`, leaving real gaps for correct 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%, so the description must carry the load, and it explains neither parameter. It never says what format `coin` takes (Hyperliquid perp ticker?) nor what `hours` means, despite the schema capping it at 2160 (90 days) — a constraint an agent would want surfaced.

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?

States the specific resource with precise granularity and units: hourly order-book depth in USD at 5/10/20/50 bps per side plus spread. That clearly separates it from the funding-oriented carry_* siblings, though it never names an alternative tool to contrast with.

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 closing sentence 'Use for order-book depth history of a Hyperliquid perp' gives an implied use case, and the '40 most traded perps' clause sets a coverage boundary. There is no guidance on when to prefer a sibling (e.g. coin_snapshot or carry_history) or when this tool is the wrong choice.

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 read-only, idempotent, non-destructive, open-world, so the safety profile is settled. The description adds genuinely non-structured behavior: cost ($0.003/call or Carry key) and the default threshold semantics. It does not explain result-set size behavior (the limit parameter) or ordering.

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 definition and threshold, then the routing hint. The "|APR| ≥ min_abs_apr, default 2 = 200 %" clause is dense but decodable; the pricing note 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 2-parameter lookup with no output schema, the description covers the filter and the returned metrics adequately, but the undocumented limit parameter is a real hole for an agent deciding what arguments to pass and how many extremes it will get back.

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 carry both parameters. It does a good job on min_abs_apr (absolute-value predicate and the "default 2 = 200 %" unit convention) but never mentions limit, leaving result-count behavior undocumented in both places.

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?

States a specific resource and predicate: funding extremes where |APR| >= min_abs_apr, plus the realized 24h/7d/14d averages and hours-in-extreme it returns. It also names the sibling it differs from (carry_aftermath), so an agent can separate it from carry_history/carry_calendar without opening any schema.

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?

"Use for funding extremes with realized averages; for history after extremes use carry_aftermath" gives an explicit use case and routes the adjacent case to a named alternative. It stops short of stating exclusions relative to the other carry_* siblings (breakeven, regime, naked), so it is strong but not exhaustive.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive. The description adds real context beyond them: an auth requirement (Carry Oracle key, US$100/month), the factual 'data, not a signal' framing, and the returned fields. Return format details (pagination, refresh cadence) remain unstated, keeping it from a 5.

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 tight sentences, front-loaded with scope and contents, then the cost/auth caveat, then the routing rule. 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?

With no output schema, the description compensates by naming the returned fields (funding, OI, 24h volume, spot mark) and the access requirement. An agent has enough to decide and call 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%, so both dex and min_vol are fully documented in the schema. The description implies dex filtering ('every dex', 'filter to one dex' lives in schema) but adds no syntax or default detail beyond it, so baseline 3 is correct.

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

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

States a specific resource (annualised funding) and scope (every perp on every Hyperliquid dex: main + HIP-3), with a clear verb-like framing. It separates itself from price_for and carry_history explicitly, so an agent can route 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?

Explicit when-to-use ('ALL perps on ALL Hyperliquid dexes at once') and names the alternatives for the narrower case ('for one coin use price_for or carry_history'). Nothing is left to inference.

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

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

Annotations already declare readOnly/IDEMPOTENT/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful non-annotation context: the authentication requirement (Carry Oracle key) and the retention property of the data source (beyond the 500 h window). It stops short of describing rate limits or pagination, hence a 4 rather than 5.

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 tight sentences, no filler, with the data scope and the 'beyond 500 h' constraint front-loaded ahead of the alternative-tool routing. Slightly dense but every clause carries 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?

For a two-parameter read tool with no output schema, the description covers what is needed to call it correctly: coin format, hourly granularity, retention window, auth requirement, and the sibling to use instead. Return-field specifics are implied by the enumerated metrics but never laid out, which is the only minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of the HIP-3 prefix convention (xyz:NBIS) and the hourly granularity restates what the schema already documents for coin and hours, adding no new syntax or format 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?

States a specific verb (retrieves) and resource (hourly funding/premium/mark/OI/volume for one coin) with an explicit scope qualifier: history retained beyond Hyperliquid's 500 h window. It also names the sibling it is not, so an agent can distinguish it from carry_funding_matrix without opening either schema.

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

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

Gives both the when-to-use condition ('one coin's hourly history beyond 500 h') and the alternative with its selecting condition ('for the current snapshot of all coins use carry_funding_matrix'). The key prerequisite ('Requires a Carry Oracle key') is stated up front, leaving nothing to inference.

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 the safety profile (read-only, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful context beyond them: it requires a Carry Oracle key, and it is 'Raw data, not a call', which tells the agent not to treat the output as a recommendation. It does not describe return shape, but that gap is minor here.

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 dense sentences with no filler. The defining filter condition is front-loaded, and the routing rule comes last where an agent deciding between siblings will look for 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?

For a single-parameter, no-output-schema read tool the definition covers what is needed: the filter semantics, the auth prerequisite, the nature of the output ('raw data'), and sibling routing. Only a brief note on the returned data shape is absent, which is acceptable given there is no output schema.

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

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

Schema coverage is 100%, and the single parameter is documented in the schema with its default of 0.5. The description restates the default (50%) and the threshold semantics, but adds no syntax or nuance beyond the schema, so baseline 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?

States a specific resource (perps), a precise filter condition (|annualised funding| above a threshold, no hedge leg on Hyperliquid) and the mechanism (no spot, no same-ticker HIP-3 listing). It explicitly distinguishes itself from named siblings, so an agent can route correctly without opening a schema.

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

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

Gives an explicit when-to-use case ('funding extremes that cannot be hedged on Hyperliquid') and names the alternatives for the excluded case (carry_xdex, carry_spot_perp). Both the positive and negative routing conditions are stated.

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 the read-only, idempotent, non-destructive profile, so the description adds value by disclosing the concrete thresholds (funding at 0.0 for ≥4h, a z-score for divergence) and a per-call price of $0.003 or a Carry key. Cost disclosure ahead of invocation is genuinely useful. It does not describe how much data is returned or how the flags are ranked.

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 short sentences, front-loaded with the flag inventory, then the commercial note, then the use case. Nothing is padded. The cost sentence interrupts the technical flow slightly, but overall it is tight and scannable.

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

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

There is no output schema, and the flag names plus thresholds do a reasonable job of implying what comes back. However, a diagnostic tool with two free-form parameters and no required fields should say what an unfiltered call defaults to and what 'dex' expects, and it omits that.

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 neither parameter is explained in the description. 'dex' presumably scopes the market and 'hours' (12–720) presumably sets a lookback window, but the description never says so—the '4 h' figure refers to the flag threshold, not the hours parameter. With both params undocumented in both places, the description fails to compensate for the coverage 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 states exactly what the tool reports: three named flags (frozen_funding, stale_oracle, divergent_vs_peer) with their detection logic. That is a specific diagnostic resource, not a restatement of the name. It stops short of distinguishing itself from adjacent oracle siblings such as oracle_board or oracle_track_record.

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 final sentence gives explicit context: use it to check frozen funding, stale oracles, or diverging HIP-3 legs 'before trusting a market'. That is a clear trigger condition. No exclusion rules or named alternatives are provided, which keeps it at 4 rather than 5.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds real context annotations don't: per-market vs single-coin scope, the N-day window, and pricing ($0.002/call or Carry key). It does not describe output shape or latency, so not a 5.

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 but front-loaded: metric list first, then cost, then the routing hint. Terse telegraphese phrasing costs a little readability but every clause carries 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?

No output schema exists, and the description enumerates the returned quantities (floor/premium/negative/zero percentages, current regime, dex counts), which is sufficient for an agent to know what it gets. Missing only explicit default value for days.

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 50%: coin is documented in the schema, days carries only min/max bounds. The description supplies meaning for days ('over N days') and clarifies the coin scope, but adds no format or default guidance beyond that, matching the baseline for partial 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?

States a specific verb-less but precise analytical product: percent of hours at the 10.95%/yr floor, in premium/negative/zero over N days, regime now, counts by dex, per market or single coin. It also names the sibling (carry_funding_matrix) it differs from, so an agent can distinguish it without opening either schema.

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 when-to-use clause ('how often a market sits at the funding floor vs premium') paired with an explicit alternative for a different need ('for current levels use carry_funding_matrix'). No inference required.

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?

Adds substantial context beyond the annotations: auth requirements (Carry key via X-API-KEY, free trial key, or x402 per-call payment), the sort order ('sorted by 14-day funding'), and a full enumeration of returned fields. With no output schema, this field disclosure is genuinely load-bearing. Rate limits or pagination behavior are not mentioned, keeping it short of a 5.

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-loads the scope, then returns, then auth, then routing. The long field enumeration is verbose but justified because no output schema exists to document the response. Slightly dense but nothing wasted.

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

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

Given two optional params fully documented by the schema and no output schema, the description compensates by listing the return fields, noting the sort order, stating access/auth modes, and naming the sibling alternative. An agent has everything needed to 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 description coverage is 100% for both parameters, including their defaults (limit=50, min_vol=100000), so the schema carries the parameter documentation. The description adds no parameter-level detail, so baseline 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?

States a precise verb/resource scope: 'Hyperliquid main-dex perps that also have a Hyperliquid spot market,' with concrete examples (HYPE, PURR, BTC via UBTC). It immediately distinguishes itself from the sibling carry_xdex, which covers cross-dex HIP-3 pairs.

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 routes the agent: 'Use for main-dex perp vs its spot market; for cross-dex HIP-3 pairs use carry_xdex.' It also sets expectations with 'Data, not a signal,' telling the agent this returns raw data rather than a trade recommendation.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond that: it names the authentication requirement (Carry Oracle key), scopes the output to every perp market and dex, and lists concrete return fields including 7-day changes and risk flags. It stops short of covering pagination, rate limits, or response format, so a 4 is appropriate.

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

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

The description is three tight sentences that are front-loaded with the returned data, then the auth requirement, then the usage guidance. Every sentence earns its place, and there is no redundant or vague language.

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 listing tool with no input parameters and no output schema, the description provides a complete picture: what it returns, the required key, and exactly when to use it versus funding-related tools. Annotations already cover the safety profile, so nothing essential 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?

There are zero parameters, so the schema has no parameter semantics to document. Per the rules, zero parameters yields a baseline of 4; no additional meaning can be added beyond what the empty 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 states a specific resource (every Hyperliquid perp market and dex) and the exact data categories returned (status, OI and volume with 7-day change, growth mode, risk flags). It explicitly distinguishes from sibling tools by saying 'not for funding levels', which separates it from carry_funding_matrix and funding_alerts.

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 use case ('market and dex health (delistings, OI drops)'), a prerequisite ('Requires a Carry Oracle key'), and an explicit exclusion ('not for funding levels'). The agent has enough to decide when to call this versus the funding-focused siblings without inferring.

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/non-destructive. The description adds meaningful context beyond them: auth requirements, 'Data, not a signal' framing, the main-dex exclusion rule, and the sort order. Pagination/rate-limit behavior is not mentioned, keeping it short of 5.

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-loads the core definition and example; the output-field enumeration is dense but informative given there's no output schema. Slightly long, but nearly every clause carries useful information.

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

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

With no output schema, the description usefully enumerates the returned fields (legs, spread_apr_now/14d, basis_pct, min_leg_vol24_usd) and sort order. Auth and scope are covered; only edge-case behavior like empty results or rate limits is absent.

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 only two optional params, both documented in the schema (limit, min_vol). The description doesn't add syntax or semantics beyond defaults, so the baseline 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?

States a specific resource (assets listed on 2+ Hyperliquid HIP-3 dexes) with a concrete example, and explicitly excludes main-dex tickers. The sibling differentiation is explicit: 'for perp vs spot use carry_spot_perp'.

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 names when to use it ('the same ticker priced on 2+ HIP-3 dexes') and the alternative for the adjacent case ('for perp vs spot use carry_spot_perp'). It also states access prerequisites (Carry key, trial key, or x402 per 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?

Annotations already establish read-only, idempotent, non-destructive, open-world safety, and the description adds real behavioral context beyond that: null blocks when data is unavailable, options coverage limited to BTC/ETH, and a $0.01/call cost. It doesn't discuss latency or caching, but the disclosure of conditional availability and pricing is substantive.

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 claim and cost, then the field map, then the usage rule. The dense field enumeration is long but is the tool's actual value proposition; a minor trim of redundant block braces would improve it without losing 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 no output schema, the description carries the full return-shape burden and does so completely: block names, key fields, nullability, symbol-conditional blocks, and price. Nothing an agent needs to decide to call this 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?

Only one parameter, symbol, and schema coverage is 100% with inline examples (BTC, ETH, SOL, HYPE). The description adds a symbol-conditional constraint (options only exist for BTC/ETH), which is meaningful semantic value the schema lacks.

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 resource (one coin) and enumerates every returned block with its fields, so the agent knows exactly what this call produces. It also distinguishes itself from siblings by positioning itself as the aggregate 'full picture' call versus the 'specific 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?

It gives an explicit ordering rule: use this first for the full picture, then drill down with the specific tools. The alternatives are described only as a category ('the specific tools') rather than named, which keeps it just 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 establish readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new context: the $0.003 per-call cost, that results include a DefiLlama outlier flag, and an explicit caveat that this is not a risk rating. That is meaningful interpretation and cost context beyond the structured fields.

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 return contents are front-loaded, which is good, but the phrase "Not a risk rating" appears twice, the second time redundantly redundantly tacked onto the usage sentence. That repetition wastes space and slightly muddies an otherwise tight definition.

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 and five zero-coverage parameters, the description should carry more weight than it does; chain, limit, and the boolean flag semantics are unaddressed. It does describe returned fields and cost, which helps, but an agent still lacks enough to fully configure the call.

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% across five parameters, so the description must compensate. It implicitly covers stable_only ("stablecoin or all") and min_tvl ("TVL floor") and touches the outlier flag, but chain and limit are undocumented anywhere, leaving half the parameters unexplained.

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 gives a concrete verb-and-resource picture: it returns DeFi pools filtered to a TVL floor, with APY, 30-day mean APY, reward-token share, and an outlier flag. That is far more than a restatement of the name. It stops short of explicitly differentiating from siblings such as stablecoin_supply or the carry_* family, so it is clear but not fully self-routing.

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?

"Use for stablecoin pool APYs; not a risk rating" gives a positive usage cue and a boundary (not a risk assessment), which is useful. However, no alternative or sibling tool is named for when this is the wrong choice, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the description's job is to add operational context — and it does: per-call cost ($0.002/call), the conditional behavior that funding_history is only populated when exactly one symbol is requested, and the sortable dimensions. It stops short of describing pagination or defaults when no arguments are supplied, so it isn't exhaustive.

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 core routing and field list are front-loaded, but it's delivered as one dense run-on with parenthetical asides and a legal disclaimer ("Not affiliated with Coinbase or Deribit") that doesn't help an agent decide or invoke. The pricing line earns its place; the disclaimer and duplicated sort enumeration do not.

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 usefully documents the items[] return shape and the funding_history sub-object, and cost is disclosed. But for a four-parameter tool with no required args and thin schema coverage, the absence of any statement about defaults, limit/pagination, or min_volume_usd filtering leaves a real gap for correct 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 only 25%, so the description must carry parameter meaning, and it largely does not: it recites the sort enum values verbatim without explaining neg_funding, abs_funding, or gap, and never mentions limit or min_volume_usd at all. Only the single-symbol funding_history behavior adds real parameter-level meaning 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 names the exact resource and scope ("Every Deribit perpetual") and frames the venue (Coinbase Advanced international perps), enumerating the returned fields so the agent knows precisely what data class this supplies. It also explicitly differentiates itself from hl_basis and derivs_for for Hyperliquid-only queries, so selection is unambiguous without opening the schema.

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 clause ("Use for Deribit / Coinbase Advanced international perps ... funding, OI, premium, gap vs Hyperliquid") and an explicit when-not-to-use alternative ("for Hyperliquid only use derivs_for or hl_basis"). The routing decision is fully spelled out with named 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on behavior they cannot express: no API key required, $0.003/call cost, data freshness/join semantics ('joined with our primary-source event pressure when covered'), and an explicit exclusion ('Liquidations are not included').

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 purpose and the data inventory are front-loaded in a single dense sentence, and the routing/alternatives follow. It is long and field-heavy, but the enumeration is justified because there is no output schema; only minor tightening is possible.

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 2-param read tool with no output schema, the description enumerates the returned fields (funding, OI, mark/oracle/mid, premium, volume, flags), notes the event-pressure join, and states what is excluded — everything an agent needs to decide and call 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%, so symbol and since are already fully documented in the schema, including case-insensitivity and the 24h default. The description adds only an example ticker list and the notion of hourly funding resolution, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb+resource: perpetual-futures microstructure for ONE coin from Hyperliquid's public API. It explicitly distinguishes itself from price_for (price only) and carry_funding_matrix (every perp), so an agent can route without opening sibling 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?

Gives concrete trigger scenarios ('before sizing a perp position', 'detect crowded funding', 'market-structure leg next to events_since') and names two alternatives with the condition that selects each: price_for for price only, carry_funding_matrix for all perps.

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 cover safety (readOnly, idempotent, openWorld), and the description adds genuinely non-structured context: cost ($0.005/call), a free quota (100 calls/day), the scoring model (direction −1/0/+1, confidence 0..1, horizon), and the tradable_now / next_open fields. That is real behavioral disclosure 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?

Front-loaded with purpose and use cases, then filters, then pricing; minimal waste. The dense parenthetical enumerations of event kinds and impact fields make it long, but each clause carries information an agent needs.

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

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

For an 8-parameter, zero-required read tool with no output schema, the description supplies the return shape, filtering defaults, cost/rate limits, and sibling routing. 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?

Schema coverage is 100%, so the baseline is 3; the description still adds usage-level semantics by framing universe=["NVDA","BTC"] with min_confidence≥0.4 as the configuration for acting, and by tying `since` to backtesting. Some of this (past `since`) restates the schema, so it falls short of full compensation.

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?

States a specific verb and resource ('List market-moving events since a point in time'), enumerates the event kinds covered, and describes the per-asset scored output shape. It explicitly differentiates itself from siblings impact_for (one asset's scored impacts) and brief (one-call asset summary).

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

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

Gives concrete when-to-use scenarios ('what happened in the last N hours that affects my book'), a backtesting case with a past `since`, and explicit alternatives with their selecting conditions (impact_for, brief). It also names the default filter that makes results actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful non-annotation context: a cost of $0.02/call and a detailed preview of the returned reasoning (why each asset got its direction/confidence, the exposure-graph path, source links, corroborating sources). It does not mention auth or rate limits beyond cost, but the added transparency is meaningful.

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 purpose and output details, then usage guidance, then cost and a sourcing constraint. It is efficient overall, but the two sentences 'Takes the event id from those tools' and 'Use only with an event_id returned by events_since or impact_for' are partially redundant, slightly hurting conciseness.

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

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

For a simple read-only tool with one required string parameter, no output schema, and annotations that fully cover safety semantics, the description is complete: it says what the tool returns, when to use it, how it relates to sibling tools, the required input source, and the cost. Nothing an agent needs in order to invoke 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?

Schema description coverage is 0% for the single event_id parameter, so the description must carry the burden. It specifies where the event_id must come from ('returned by events_since or impact_for') and uses it to scope the tool to exactly one event. This adds essential semantic meaning beyond the bare string type in the schema, though it does not describe the id format itself.

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 ('Plain-language explanation') and resource ('ONE event's impacts'), and details exactly what the explanation contains (direction/confidence reasoning, exposure-graph path, source document link, corroborating sources). It also distinguishes this from sibling tools impact_for and events_since by framing itself as the 'reasoning' layer rather than the raw impact data.

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

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

It gives explicit when-to-use criteria: 'when an impact from events_since/impact_for is surprising and you need the reasoning before acting, or to log a rationale.' It also states a hard prerequisite and restriction: 'Use only with an event_id returned by events_since or impact_for.' No ambiguity remains about the appropriate context or the required input source.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds real value beyond that with per-call cost ($0.002/call) and the scope of what the graph returns, though it says nothing about response size or traversal limits beyond depth.

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?

Efficient and front-loaded: it leads with the resource, then use cases, then cost, then exclusions. The opening is a fragment and the enumeration is dense, but every sentence carries information and none is wasted.

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

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

For a two-parameter read tool with a complete schema, the description adequately conveys what the graph contains so the agent doesn't need an output schema. It could go slightly further on result shape or breadth, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, with both asset_id and depth fully documented in the schema (including hop semantics and the `universe` cross-reference). The description adds no parameter-level meaning beyond that, 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 states a specific resource (an asset's exposure graph) and enumerates its contents: suppliers, customers, countries, input commodities, regulators, indices, correlated assets, and facilities with coordinates. It clearly distinguishes itself from siblings like price_for, news_for, and events_since, which it explicitly rules out.

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 concrete when-to-use cases (finding second-order trades like TSM → NVDA/AAPL, or knowing which regulators/countries to watch) and an explicit when-not-to-use clause ('not for prices or events'). This routes the agent away from wrong 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 readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds value beyond that: it discloses the cost ($0.002/call), the public-domain source, and the shape of the returned content (summary, impact direction, link). It stops short of describing pagination or per-call rate behavior, keeping it at a strong 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?

Front-loaded with the resource and scope, then triggers, then the cost, then the sibling disambiguation. Every sentence carries information. The '$0.002/call' clause sits mid-description and momentarily interrupts the flow, a minor structural blemish.

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 the description explains what comes back (summary, impact direction, link), and covers the forms, window and issuer dimensions. For a filtered, read-only lookup tool this is nearly complete, with only limit/pagination behavior left unstated.

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% (forms, since, ticker documented; limit is not). The description still adds meaning by spelling out the form categories (8-K items, Form 4, 13D/G, S-1/424B, bankruptcy) and the notion of a time window, reinforcing how 'forms' and 'since' behave. It adds context over the schema rather than merely restating it.

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

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

States a specific resource (SEC EDGAR filings) with explicit scope ('touch ONE US issuer in the window') and enumerates the covered form types (8-K by item, Form 4, 13D/G, S-1/424B, bankruptcy). It also names the sibling it is not (news_for), so an agent can distinguish it without opening either schema.

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

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

Gives concrete when-to-use triggers ('before earnings', 'when a stock moves without news') and states the routing rule explicitly ('Use for SEC filings of one issuer; for headlines use news_for'). Both the use case and the alternative are named, leaving nothing to inference.

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/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful context the annotations don't: a $0.001/call cost and the 5–15 min refresh cadence, plus what is returned (annualized %, which side pays, OI, predicted next funding per venue).

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 but front-loaded: purpose, then cadence, then the routing alternative. Every clause carries information, though the single long sentence would read better split. 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?

No output schema exists, so the description appropriately enumerates the return fields (hourly/annualized rate, paying side, OI, predicted next funding across venue). Combined with the alternative-tool routing, an agent has almost everything needed, with only the limit parameter left unexplained.

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

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

Schema coverage is 50%: min_abs_rate_1h is documented in the schema (threshold semantics and default), but limit has no description anywhere. The description's mention of sorting by |hourly rate| implies a threshold notion but never explains limit, so it only partially compensates for the gap. Baseline 3 is appropriate.

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

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

Opens with a specific verb+resource+scope: which perps have extreme funding right now on Hyperliquid, sorted by |hourly rate|. It explicitly distinguishes itself from carry_funding_matrix for every Hyperliquid dex incl. HIP-3, so an agent can route without opening either schema.

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

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

Gives an explicit cadence and purpose ('Use every 5–15 min to detect crowded positioning or to pick a side to receive funding') and names the alternative tool plus the condition that selects it (carry_funding_matrix for every dex incl. HIP-3). Nothing is left to inference.

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/non-destructive, so safety is covered. The description adds genuinely new behavioral context: the $0.001/call price and the intended decision workflow (pick fees, estimate USD cost). It says nothing about data freshness or rate limits, keeping it out of the 5 band.

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 a compact field inventory, then the cost and usage note. It is dense and jargon-heavy (gwei, EIP-1559, p10/p50/p90), but every clause carries information for an agent deciding whether to call it. Slightly list-like rather than flowing.

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

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

There is no output schema, so the description carries the full burden of describing returns, and it does so field-by-field with units (gwei, ETH, USD) plus the price of the call. An agent knows exactly what it will get and what it costs.

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 takes zero parameters, so there is nothing to disambiguate; the description correctly focuses on outputs instead. Baseline for a no-param tool.

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?

States the exact resource (Base chain 8453 gas) and enumerates the concrete outputs: base_fee_gwei, next_base_fee_gwei, priority fee percentiles, suggested EIP-1559 tiers, and L2 execution costs. No sibling tool competes with this gas-fee role, so it is unambiguous.

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

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

Explicitly says when to use it: 'Use before sending a Base transaction to pick fees and estimate cost in USD.' That is a clear trigger. It does not name when-not-to-use or an alternative (e.g., a chain-specific gas sibling), so it stops short of the top band.

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, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuinely new behavioral context: a per-call price of $0.001/call and a precise picture of the payload, including that hours triggers an added funding_history block. That cost disclosure is exactly the kind of context annotations cannot carry.

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?

It is dense and telegraphed, but every clause carries information: field names, nested shapes, the hours effect, cost, and the sibling redirect. Nothing is padded. The only cost is readability — the field list is packed into one run-on opening clause rather than front-loading the purpose first.

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

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

There is no output schema, so the description must carry the full return shape, and it does down to nested funding fields and the conditional funding_history block. Cost, parameter effect, and the coin_snapshot alternative are all present. Nothing an agent needs to call this 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?

Schema coverage is 100%, so the baseline would be 3. The description exceeds that by explaining the consequence of the hours parameter — 'hours=N (≤168) adds funding_history' with its stats and hourly array — which tells the agent what it gets for the extra parameter rather than just its range. Coin semantics are left to the schema 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 names a specific resource (one Hyperliquid main-dex perp) and enumerates exactly what comes back: mark_oracle_premium_bps, impact_premium_bps, funding, predicted_funding, open_interest_usd. The closing clause 'Use for one Hyperliquid perp's premium vs oracle...' states the purpose plainly. It only loses polish because the lead is a field dump rather than a verb-led statement of purpose.

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

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

It gives a positive use case (premium vs oracle, predicted funding vs Binance/Bybit) and names the alternative explicitly: 'for the full coin picture use coin_snapshot.' That is real routing guidance. It does not cover other plausible alternatives among the many siblings (carry_spot_perp, br_premium, impact_for), so it falls short of a full when/when-not map.

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/destructive, so the description's real value-add is the $0.001/call price disclosure and the response shape (candles[] and summary fields). It does not state default interval/limit behavior or pagination/truncation at the 500 cap, which is the remaining gap.

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 compact sentences: output shape, cost, usage routing. Every clause earns its place and the routing constraint is front-loaded.

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

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

For a simple read-only 3-param tool with no output schema, the description sketches return values and cost well. Missing defaults for interval/limit and any hint about candle ordering or partial data at range edges keeps it short of complete.

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

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

Schema coverage is only 33% – only 'coin' is documented (with an example). The description does not explain what 'limit' means (max 500, default?), nor clarify interval semantics beyond the enum's self-evident values. With low coverage, the description should compensate and does not.

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?

States the specific verb+resource (OHLCV candles for one Hyperliquid perp, main or HIP-3) and even enumerates the return fields. An agent can distinguish it from the many carry_, oracle_, and polymarket_ siblings without opening the schema.

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 scopes usage: 'Use for price history (OHLCV) of one Hyperliquid perp; for price now use price_for.' It names the alternative and the condition that selects it, leaving nothing to inference.

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, non-destructive behavior, so the safety profile is covered. The description adds value beyond that: a per-call cost ($0.001/call), the tracked metric names (longs_near_liq_usd, shorts_near_liq_usd), and a 24h confirmation window. Return pagination is not addressed, but the cost disclosure is meaningful 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?

Front-loaded with the ranking rule, followed by metrics, cost, and use case — information ordered by importance. Faint redundancy between the opening clause and 'Use to scan...' but no padding.

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 helpfully names the returned fields and the liquidation window. However, for a two-parameter tool it omits any explanation of n, and it never clarifies how it relates to the sibling hl_liquidations, which is a real gap for an agent choosing between them.

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 50%. The description references within_pct ('within within_pct% of liquidation'), reinforcing the schema's existing description, but the n parameter is undocumented in both schema and description — an agent cannot tell it is the result-count cap. The description does not compensate for the coverage 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 states a specific verb and resource: Hyperliquid coins 'ranked by tracked notional within within_pct% of liquidation', and names the two output fields. The scan is clearly distinguishable from a generic listing. However, it does not distinguish itself from the sibling hl_liquidations, which appears to overlap on liquidations data.

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

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

'Use to scan which Hyperliquid coins have the most positions close to liquidation' gives a usage context, so intent is implied rather than absent. But there is no explicit when-not guidance and no mention of hl_liquidations as the alternative, leaving overlap with that sibling unresolved.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety bar is met. The description adds real behavioral context beyond them: 15-minute refresh cadence, an explicit "sample, not the whole book" caveat, a $0.002/call cost, and that liquidations_24h are confirmed by Hyperliquid's liquidation marker.

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 resource and source, then the returned fields, then the usage line. Dense but largely justified given there is no output schema; the enumerated field list is doing real work rather than padding.

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 usefully enumerates the return shape (longs/shorts, liquidation_bands, nearest_long/short_liquidation, liquidations_24h, coverage_pct_of_oi) and discloses cost, freshness, and sampling limits. Only the invalid-coin/error behavior and the relationship to hl_liq_near are left unaddressed.

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?

Only one parameter (coin) with 100% schema description coverage, so the schema already carries the semantics. The description restates the scope as "one Hyperliquid main-dex coin" but adds no format, casing, or validity detail beyond the schema's own example.

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?

States a specific verb+resource: a liquidation map for one Hyperliquid main-dex coin, with the data source (most active accounts on the public leaderboard) named. It is clear what the tool does, but it fails to differentiate from the obvious sibling hl_liq_near, which appears to cover the same liquidation territory.

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?

"Use for where Hyperliquid positions get liquidated for one coin" gives explicit usage context, and it names a non-alternative (carry_now) for the funding use case. However, the genuinely competing sibling hl_liq_near is never mentioned, so the agent gets no guidance on how to choose between the two liquidation tools.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds real context beyond them: the exact cohort definition (top 100 by 30-day PnL, ≥ $5M volume, positive ROI) and a per-call cost of $0.002. It doesn't cover refresh cadence or what happens when a coin isn't tracked, so it falls short of a 5.

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 cohort definition leads, followed by output fields, price, and the sibling alternative — logically ordered with no filler sentences. The long enumeration of return fields is justified by the absence of an output schema, though it makes the block dense to parse in one pass.

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 does the necessary work of enumerating return fields (smart, smart_long_share_pct vs all_tracked_long_share_pct, flow with largest moves), plus cohort and cost. Minor gaps remain around error behavior for untracked coins and data freshness, which an agent would want before spending $0.002.

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

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

Schema coverage is 100%, with both parameters documented (coin = main-dex coin, hours = lookback default 24), so the baseline applies. The description reinforces that hours is the window for the flow block ('flow {hours, ...}'), but adds no new syntax or constraint meaning.

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

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

States a specific resource (positioning of the top-100 30-day-PnL Hyperliquid accounts) in a specific scope (one coin), and names the sibling it is not (hl_smart_flow, all coins). An agent can distinguish it from hl_smart_flow and whale_moves without opening any schema.

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 what to use it for ('how top-PnL Hyperliquid traders are positioned in one coin') and names the alternative with its selecting condition ('for all coins use hl_smart_flow'). No inference required.

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 the read-only/idempotent safety profile, and the description adds genuinely new context: per-call pricing ($0.002/call) and a precise definition of the population being measured (top 30-day-PnL accounts over the last N hours). It does not mention rate limits, caching, or pagination, which keeps it from a 5.

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 dense sentences with no filler. The return-shape listing leads the description rather than the purpose, which is slightly backwards for selection, but given the absence of an output schema the field enumeration earns its space.

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, describing flows[] and positioning[] fields is necessary and mostly done, and pricing is covered. But the description leaves the key 'n' parameter unexplained and its 'N hours' wording conflicts with the param name, so an agent cannot fully determine how to size the request.

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 only 50%: 'hours' documents 'Default 4', but 'n' (1-25) is undocumented in both schema and description. Worse, the description's phrase 'in the last N hours' uses 'N' for the time window while the schema's 'n' is a separate parameter, creating ambiguity about what 'n' actually controls.

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 gives a specific verb+resource ('see where top-PnL Hyperliquid traders are adding or cutting exposure across coins') and the opening 'Across coins' implicitly distinguishes it from the per-coin sibling hl_smart_coin. It never names that sibling outright, so the differentiation is left slightly implicit.

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 closing sentence gives a use case ('to see where top-PnL traders are adding or cutting exposure'), which is implied guidance. However, there is no explicit when-to-use/when-not statement and no reference to hl_smart_coin or hl_liquidations as alternatives for narrower or related queries.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the per-call price ($0.003/call) and the exact shape of what is returned. It stops short of noting rate limits or auth requirements, so it is not fully exhaustive.

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-loads the core definition, then usage, then cost, then sibling routing, in four compact sentences with no filler. Every clause carries distinct 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, and the description compensates by enumerating the returned fields (bias, event count, drivers, rationale, graph path). Combined with 100% schema coverage on inputs and full annotation coverage, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so asset_id, since, and limit are already documented with formats, defaults, and bounds. The description adds only the notion of a 'window' and reinforces single-asset scope, which is marginal beyond the schema — the baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource with scope: 'Net directional pressure on ONE asset over a window', then enumerates the payload (bias −1..+1, event count, strongest drivers, source events with rationale and graph path). It is unmistakably distinct from sibling tools like events_since, brief, and price_for.

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

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

Gives explicit when-to-use ('before entering or sizing a position in that asset, or to explain a move ("why is MSTR down today?")') and names the two alternatives with their selecting conditions: events_since for raw events, brief for a full asset briefing. Nothing is left to inference.

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 read-only and idempotent annotations, it discloses monthly cadence, Census provenance, a $0.003 per-call charge, and the principal result fields. Data-release lag, historical coverage, and any request limits remain unspecified.

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 data scope, followed by useful output details, cost, and an explicit use case. Despite its density, each element supports selection, invocation, or result interpretation.

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 one-parameter read tool, it supplies the source, cadence, main outputs, intended use, and price, which is enough to select and invoke it confidently. Because there is no output schema, the undefined contents of monthly[] and unspecified freshness or coverage are modest remaining gaps.

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

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

The schema already fully documents the sole hs parameter, including accepted digit lengths and an example. The description reiterates that lookups are by HS code but adds no further parameter meaning, so the high-coverage baseline 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 precisely identifies the resource and scope: monthly U.S. imports for a product HS code, sourced from Census. Naming import values, unit values, origins, and trend metrics makes its purpose unambiguous among the siblings.

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 explicit 'Use for' sentence identifies the intended questions: U.S. import value, unit value, and origin countries by HS code. It provides no when-not guidance or alternative tool, but none is necessary for correct basic selection.

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

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

Annotations disclose readOnlyHint=false, idempotentHint=false and openWorldHint=true, and the description reinforces the non-idempotent nature via 'One per e-mail', plus adds quota (200 calls/7 days), no-card requirement, coverage boundaries, and the X-API-KEY delivery convention. It does not say what the response payload contains or how a duplicate-email request fails.

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 final clause 'Use once to get a free trial key (200 calls, 7 days); then send it as X-API-KEY' restates the opening sentence's facts with no new information, making the description noticeably redundant rather than front-loaded and tight.

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, no-output-schema issuance tool the description covers the essential quota, scope, and delivery mechanism, so it is broadly adequate. It still omits what the call actually returns (the key itself? a confirmation?) and any failure/rate behavior, which an agent issuing this credential would benefit from knowing.

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 0% and the sole parameter ('email') is undocumented in the schema, so the description must carry it. 'One per e-mail' does convey that the e-mail is the uniqueness key for issuance, but it never states format expectations or that the key is delivered to that address, leaving a real gap for a 1-required-param tool.

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?

States a specific verb and resource ('free trial API key for Degenscan Intel') and quantifies the deliverable (200 calls, 7 days, no card). It also delineates scope against siblings by naming which tool families it covers (carry_*, event feed) and which it does not (oracle). Slightly muddled by repetition, but an agent can tell what it returns.

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

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

It implies context – constrain usage, one per e-mail, and the resulting key's coverage – but never states when an agent should call this versus using an existing key or another tool. The 'Use once' phrasing hints at a single-shot precondition without spelling out what happens on repeat calls.

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/open-world, and the description adds substantial context beyond them: the exact payload fields (source tier, corroboration count, −1..1 sentiment, impact direction, average sentiment label), the 'links only, no article bodies' limit, and a per-call price of $0.002. That is meaningful operational disclosure an agent cannot get from 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?

Front-loaded with purpose and payload, then usage, cost, and routing in a compact block. It is dense rather than padded, though the parenthetical field list is long enough that the sentence strains slightly.

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 describing return contents and does so thoroughly, including the sentiment scale and the 'no article bodies' caveat. Nothing needed 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?

Schema coverage is 67%, and the description mentions the 'window' concept that maps to the since parameter, but it adds no format or syntax detail for limit or since beyond what the schema already documents. With the schema doing most of the work, this lands at the baseline.

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

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

States a specific verb+resource: 'Headlines that touch ONE asset in the window', scoped to a single ticker. It also explicitly distinguishes itself from the sibling filings_for ('for SEC filings use filings_for'), so an agent can separate news flow from filings without opening a schema.

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

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

Gives concrete usage contexts ('what is the news flow on X today', 'feed a sentiment gate') and an explicit exclusion routing to filings_for. The 'one ticker' constraint is stated up front, so when-to-use and when-not-to-use are both covered.

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

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

Annotations already declare the tool as read-only, idempotent, open-world, and non-destructive. The description adds valuable behavioral context beyond annotations: the $0.001/call cost and the default expiry selection rule.

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 and compact: three short sentences cover purpose, default behavior, cost, and scope with no wasted text.

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 annotations, no output schema, and simple two-parameter input, the description is nearly complete. It lists the returned metrics but does not describe output shape or error behavior, leaving a small 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 schema documents the expiry format and currency enum, while the description adds meaning by explaining that expiry defaults to the next expiry with open interest. It does not add further syntax details, but adequately compensates for the 50% schema coverage.

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

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

The description clearly identifies the resource (one Deribit expiry) and the exact metrics returned (max pain, open interest, put/call ratio) for BTC or ETH. It distinguishes itself from broader siblings like options_summary by scoping to a single expiry, though it lacks an explicit action verb.

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

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

It states the primary use case ('Use for one expiry's max pain and open interest only') and explains the default expiry behavior. It does not explicitly name an alternative sibling for broader options data, but the scoping is clear enough for selection.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond the structured fields: the data source (Deribit public data) and the cost ('$0.002/call'), the latter being useful for call budgeting. It does not mention rate limits or snapshot staleness.

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?

One dense sentence front-loads the resource and return shape, then appends usage and cost. The field enumeration is long but earns its place as a stand-in output schema; nothing reads as 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?

With no output schema, the description must carry the return shape and largely does, spelling out term_structure subfields, put_call and dvol. It leaves top_open_interest[] internals and the semantics of a few fields (e.g. bf25) only lightly implied, a minor gap for a one-parameter tool.

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

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

Schema description coverage is 0%, but the single parameter is an enum (BTC/ETH) whose values are self-documenting and echoed by the description's 'BTC or ETH'. The description adds no format or constraint beyond what the enum already conveys, so this is baseline-adequate rather than enriched.

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 verb-like purpose (options summary for BTC/ETH from Deribit public data) and enumerates exactly which metrics are returned. It distinguishes itself from the closest sibling (derivs_for) with explicit routing, so an agent can separate it without opening the schema.

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?

'Use for BTC/ETH options implied vol, skew, put/call and max pain; for perp funding use derivs_for' gives clear context plus a named alternative. It stops short of explaining when to prefer options_maxpain over this tool, even though max_pain is listed as a use case here, leaving slight overlap unresolved.

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 (readOnly, idempotent, non-destructive), but the description adds cost ($0.002/call), latency/effort profile (cached, no waiting, no LLM call), and freshness semantics (recomputed daily). These are exactly the behavioral traits an agent needs for a polling tool and are not derivable from the structured fields.

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 resource and contents, then usage, then the sibling alternative. Despite being dense, every clause carries distinct information (coverage, fields returned, slug behavior, cost, routing) with 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?

There is no output schema, so the description must describe returns, and it does: probability, 80% interval, base rate, market odds, edge, commitment hash, plus drivers/failure modes/history when a slug is given. Cost, caching, and routing are all present, so nothing an agent needs to invoke 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?

Schema coverage is 100%, so the baseline is 3, and the description goes further by explaining the semantic difference between passing a slug (one forecast with full drivers, failure modes, and history) versus omitting it (the whole board). This adds outcome-level meaning beyond the schema's terse 'Omit for the whole board'.

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?

States a specific verb and resource (the oracle's standing questions, recomputed daily) and enumerates exactly what the board covers: BTC/ETH/SOL price targets, FOMC, Polymarket markets, CPI/NFP. It distinguishes itself from the sibling oracle_forecast by naming the differentiator (standing questions vs. your own question).

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

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

Explicitly tells the agent when to use it ('today's standing forecasts without waiting') and names the alternative with the selecting condition ('to ask your own question use oracle_forecast'). Adds a polling pattern ('poll in a loop for cheap calibrated priors'), which is direct usage guidance.

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

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

Annotations only declare the safety profile (readOnly=false, openWorld=true, idempotent=false); the description goes far beyond, disclosing the async contract (returns forecast_id/queued/eta_s in under a second, 1-3 min to done), cost ($0.25/call, ~70 LLM calls), the require_verified HTTP 422 no-charge behavior, and the commitment_hash committed before resolution. This is unusually rich 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 but nearly every sentence carries load (examples, pipeline, async contract, cost, result fields, alternative). It is somewhat long and the async mechanics sit mid-paragraph rather than front-loaded, which is the only real cost.

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 enumerating the return fields (probability, ci80, base_rate, edge, drivers, panel, commitment_hash, etc.), and it covers cost, timing, polling, and the failure path. An agent has everything needed to call and interpret this 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 already high (89%), but the description adds real meaning: it explains that interventions inject a shock into the simulated society and demonstrates the {round, news, audience} shape, clarifies method routing vs. forcing, and describes require_verified's refusal semantics beyond the 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?

States a specific verb+resource ('get a calibrated probability for a yes/no market question') with concrete examples, and explicitly distinguishes itself from siblings by naming oracle_get for polling and oracle_board for standing forecasts. An agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use ('ask a NEW binary question'), the follow-up workflow (poll oracle_get every ~20s until status=done), and the alternative for a different use case ('For today's standing forecasts use oracle_board'). Nothing is left to inference.

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/destructive=false, and the description adds the behavior those hints cannot express: the tool is a polling endpoint with distinct queued/running states, a retry_after_s field to honor, and a 'full Forecast' payload once complete. It also notes the result is free and verifiable via commitment_hash, which is real context beyond the structured fields.

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?

Purpose and polling behavior are front-loaded and the Forecast field enumeration is informative, but the trailing sentence 'Use only to poll a forecast_id returned by oracle_forecast (free).' repeats content already stated in the first and second sentences and earns no 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?

There is no output schema, and the description compensates well by enumerating the returned Forecast fields and the interim status shape with retry_after_s. It stops short of stating what happens on an unknown/expired id or how aggressively to re-poll, so it is strong but not fully closed.

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 one parameter at 100% schema description coverage, the schema already defines forecast_id and its provenance. The description restates the same origin (returned by oracle_forecast, listed by oracle_board / oracle_track_record) without adding format, constraint or validation detail, so the baseline 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?

States a specific verb+resource ('Poll or retrieve an oracle forecast') and immediately contrasts with the sibling that creates forecasts ('Use after oracle_forecast'). An agent can distinguish this from oracle_forecast, oracle_board and oracle_track_record without opening any schema.

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 names the entry points (oracle_forecast, oracle_board, oracle_track_record) and the ordering ('Use after oracle_forecast'), so the agent knows when this tool is the right call. Minor deduction: the closing sentence 'Use only to poll a forecast_id returned by oracle_forecast' narrows the source of the id in a way that mildly conflicts with the earlier mention of oracle_board / oracle_track_record as id sources.

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 non-destructive, so the safety profile is covered. The description adds that the record is public and free and enumerates the returned fields, which helps an agent judge the trustworthiness of other oracle calls; it does not describe update cadence or how the 20 commitments are ordered beyond 'most recent'.

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 metric list and the interpretability scale, which is exactly what an agent needs first. The trailing audit sentence duplicates the earlier guidance and the title already says 'free', so there is minor wasted verbiage.

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, so the description carries the burden of explaining return values, and it does so by naming the metrics and the commitment fields (id, probability, hash, outcome). It is complete enough to call and interpret, with only minor gaps such as aggregation windows or freshness.

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 takes zero parameters, which is the baseline-4 case. The description correctly implies a no-argument call ('How good the oracle has been'), so nothing is missing here.

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

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

Names the specific resource (the oracle's public track record) and enumerates the exact metrics returned: Brier overall and by domain, oracle vs. market Brier, beat_market_rate, mean absolute edge, and the 20 most recent commitments. It also anchors the scoring scale (0.25 coin flip, 0.15 good human, 0.10 superforecaster), so an agent knows precisely what it is reading.

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 to use it 'to decide how much to trust oracle_forecast / oracle_board' and to 'audit the oracle's public accuracy', which names the sibling tools and the decision context. The closing '(free)' audit sentence largely restates the opening guidance, so it is clear but slightly redundant rather than a crisp when/when-not split.

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, non-destructive, open-world, so the safety profile is covered. The description adds useful behavioral context: what the evidence pack contains (relevance, source tier, corroboration, per-asset impacts), the $0.01/call cost, and the 'information, not a forecast' caveat. It could say more about rate limits or result staleness, but it goes well beyond annotations.

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

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

Front-loaded with the core operation and evidence contents, then usage, then alternative routing. It is slightly dense with parenthetical examples, but every sentence carries routing or behavior 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?

Covers purpose, evidence composition, cost, and sibling routing for a read-only lookup with a fully documented schema. It does not explain return shape or freshness limits, but no output schema exists and the description is otherwise 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 the schema already documents all three parameters in detail. The description adds only the resolution behavior (id/slug via Gamma API, text searched), which is marginal beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb (resolves, returns) and resource (a Polymarket market's odds plus primary-source events), and differentiates from the sibling polymarket_top for discovery. An agent can tell exactly what the tool produces without opening the schema.

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

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

It gives explicit when-to-use ('before trading or quoting a probability', 'to detect a fresh primary event') and sensitive exclusions ('to discover markets use polymarket_top'). The alternative is named with the condition that selects it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond that: cached from the daily board with no LLM and instant latency, pollable in a loop, $0.002/call, and a link to the Brier track record. Cost, freshness and latency disclosure are exactly the kind of behavior annotations cannot express.

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?

Purpose and routing are front-loaded before the output-field enumeration, and no sentence is pure filler. However, the middle clause is a long comma-spliced list of output fields that would read better structured, making it denser than necessary.

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

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

There is no output schema, so the description carries the full burden of describing return values, and it does so comprehensively (oracle probability, 80% interval, market YES price, edge, cheap side, base rate, resolution date, sha256 commitment hash, sort order). Cost, caching and the sibling alternative are all covered, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is only 50% (limit has no description), so the description must compensate. It defines edge as (p − odds), which gives min_abs its meaning ('Minimum |p − odds|'), and limit is a conventional result cap. The added context on min_abs is useful, though limit semantics remain unstated.

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 opening clause states a specific verb and resource: it surfaces open daily-board questions where a calibrated forecaster disagrees most with Polymarket. It is distinguishable from polymarket_top and polymarket_context, and it explicitly contrasts itself with oracle_forecast for single-question use.

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

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

It states the condition for use ('list markets where the oracle and market odds disagree most') and names the alternative with its selecting condition ('for one new question use oracle_forecast'). It also tells the agent to poll it in a loop, so the invocation pattern 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 read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds two genuinely useful facts beyond that: the explicit per-call price ($0.002/call) and the exact return shape (items[] with volume, open interest, liquidity, top_outcomes with yes_prob). It does not disclose pagination behavior, whether 'most active' is a fixed ranking or tied to limit, or what happens when filters match nothing.

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 response-shape notation is front-loaded in one dense clause, followed by filters, price, and the usage cue — no filler sentences. The items[] enumeration is heavier than prose would be, but it earns its place because there is no output schema to document return fields.

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 inline return-field map is a meaningful contribution, and pricing plus the event-group definition round out what an agent needs to select and call this tool. The remaining gaps — undocumented limit, undefined filter semantics, no pagination or empty-result behavior — are modest for a read-only three-parameter lookup.

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 bears full responsibility for parameter meaning, and it only partially delivers. It names 'Filters q, tag' without saying what q matches (keyword? title?) or what form tag takes (slug, ID, free text). The third parameter, limit (1-50), is never mentioned at all, leaving its cap and default undiscoverable from prose.

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 resource and scope: 'most active Polymarket events' with an explicit definition of an event as 'event groups (all outcomes of one question family) with open interest.' That conceptual framing lets an agent distinguish it from market-level siblings like polymarket_markets or polymarket_top without opening schemas. It stops short of naming any sibling outright, so the differentiation is inferential rather than explicit.

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

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

The closing sentence ('Use for Polymarket event groups... with open interest') gives a positive usage signal, implying this is the right tool when you want aggregated outcomes per question. There is no when-not guidance, no mention of when to prefer polymarket_markets or polymarket_context instead, and no note on result limits or cost-driven 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/non-destructive, so the description's main added value is the per-call cost ($0.002/call), which matters for an agent deciding whether to invoke. It also discloses the response item shape. Missing rate/limit behavior or note on what an empty leaderboard means.

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?

One compact sentence plus a usage clause; the item schema is front-loaded so an agent knows the return shape immediately. Dense to the point of terseness, but nothing is wasted.

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

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

No output schema exists, yet the description fully enumerates the returned item fields, and defaults/scope are implied by the enums. The only substantive gap is the unmentioned `limit` bound and any default period/by behavior.

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

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

Schema coverage is 0%, so the description carries the burden — and it does supply the enum values for both `period` (day/week/month/all) and `by` (pnl/volume). The `limit` parameter (1-50) is never mentioned, leaving one of three params entirely undocumented.

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?

States a specific resource (Polymarket top traders) with the exact return fields and the two ranking axes, and explicitly distinguishes itself from the sibling polymarket_top. An agent can tell instantly what data comes back.

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?

"Use to see which Polymarket traders made the most PnL or volume; for markets use polymarket_top" gives a clear positive trigger and names the nearest alternative. Other Polymarket siblings (polymarket_edge, polymarket_context) aren't differentiated, so it stops short of full when/when-not coverage.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds value beyond that: the per-call cost ($0.002/call), the universe size (~500 most active open markets), and the fact that results include bid/ask and spread. It does not cover pagination or rate limits, but for a read-only search this is a strong 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?

Front-loaded with what the tool does and its scope, then the return fields, then filters and price, then the routing hint. The inline field enumeration is dense but earns its place since there is no output schema. Minor redundancy in restating the search dimensions twice, which is why it is not 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?

With no output schema and 0% schema description coverage, the description compensates by enumerating the response fields (id, slug, question, yes_prob, best_bid, best_ask, spread, change_24h, volume, liquidity, end_date, url) and pricing. The remaining gap is the undocumented limit parameter and filter value formats, which keeps it from 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 description coverage is 0%, so the description must carry the parameter burden, and it does list the filters q, tag, ends_within_days and min_liquidity with their intent. However, it says nothing about value formats (units for ends_within_days, whether q is free text or exact match) and it omits the limit parameter entirely, so an agent cannot infer result capping from the description.

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

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

States a specific verb and resource ("Search the ~500 most active open Polymarket markets") with scope (open, most active, ~500) that an agent can act on directly. It also names the sibling it is not ("for the top list use polymarket_top"), so the agent can distinguish it from polymarket_top and polymarket_events without opening either schema.

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: search by words, tag, closing date or liquidity, and when to use the alternative polymarket_top for the top list. It stops short of stating exclusions, such as when to prefer polymarket_events or polymarket_context, or that closed or resolved markets are not covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful non-annotation context: a per-call price ($0.002/call) and the fact that each row links to a primary-source evidence pack. It still says nothing about pagination, rate limits, or freshness of 'right now', so it is only modestly above the annotation bar.

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 and output fields, and reasonably tight overall. The usage sentence is partly redundant, restating 'most active prediction markets' after already saying it in the first sentence, which is minor waste rather than bloat.

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 enumerating the returned fields (question, YES odds, 24h change, volume, liquidity, end date, link), and it covers cost and tool routing. The main residual gap is the undocumented limit parameter and unstated result-count/default behavior.

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

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

Schema description coverage is only 33%: tag is documented in the schema, sort relies on an enum, and limit is undocumented beyond bounds/defaults. The description names the three sort options and gives tag examples (crypto/fed/politics), partially compensating, but it never explains what limit does, its 1-50 ceiling, or what 'tag slug' means beyond the 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?

States a specific resource ('the most active Polymarket markets right now') with the ranking basis (24h volume, liquidity, or 24h change) and enumerates the returned fields. It explicitly names the sibling tools it is not (polymarket_context, polymarket_edge), so an agent can distinguish it without opening any schema.

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

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

Gives explicit routing: use this to find where prediction-market money is moving, use polymarket_context for a single market's evidence, and polymarket_edge for oracle disagreement. The when-to-use and the alternatives are both stated outright.

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

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

Goes well beyond the annotations (which only cover read-only/idempotent safety) by disclosing no-key access, payload size (~1 KB), 30 s caching, cost ($0.001/call), and the polling-loop use case — operational facts an agent cannot derive from structured fields.

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 but front-loaded: capability, data sources, cost/latency, then routing to alternatives. Every clause earns its place 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?

With no output schema, the description compensates by enumerating the return payload fields and the pricing/caching model. For a single-param, read-only probe, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the single 'symbol' param is fully documented with examples (BTC, ETH, SOL, HYPE) and source notes; the description adds nothing beyond the schema, so the baseline 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?

States a specific verb+resource (cheapest price check for ONE coin) and enumerates the returned data (Hyperliquid perp mark/mid/oracle, Coinbase spot, 24h change, basis, funding, event links), making it instantly distinguishable from siblings like carry_funding_matrix and carry_history.

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 gives the when: 'Use for one coin's price/basis/funding now', and names two alternatives with their selecting conditions — carry_history for funding history, carry_funding_matrix for all perps at once. No inference required.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context the annotations lack: a per-call price of $0.006 and the conditional behavior that imports are only included when hs is supplied. It says nothing about response shape, section omission when data is missing, or latency.

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

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

Two short sentences with the source list front-loaded, but the second sentence repeats the same three components almost verbatim, so roughly a third of the text is redundant filler rather than new 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?

For a three-source composite with no output schema, the description does tell the agent which sections come back, which is the essential missing piece. It still leaves the agent guessing about response structure, behavior when hs is omitted, and the meaning of lang, which matters at 0% schema coverage.

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 carry parameter meaning and only partly does. '(with hs)' explains that hs gates the U.S. imports section and 'for a product' implies q, but the lang parameter is never mentioned and no format hints (e.g., HS code length, language codes) are given for any of the three.

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 concrete composite resource (a product research brief) and enumerates its three components: Wikipedia interest trend, CPSC recalls, and U.S. imports. This distinguishes it from single-source siblings like product_recalls, import_trends, and topic_demand, though 'interest trend' stays vague about the underlying metric.

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

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

It says to use this 'for a one-call product research brief,' which implies the alternative (calling the three source tools separately) without naming any sibling. The second sentence largely restates the first, so the when-to-use guidance is present but circular and has no exclusions.

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