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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds non-obvious behavior: 25 results per page, default sort by net value transferred, and that top 3 tokens by count are returned per counterparty. It also notes that long ranges are clamped to one year with the effective range reported, which is useful operational context 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?

Purpose, default sort, and return shape are correctly front-loaded, and the two examples are useful. But the multi-level 'Note: To get related wallets' bullet list is lengthy investigative advice rather than tool definition, and the repeated 'ASC'/'DESC' notation plus the enum mismatch add noise for a single-object request body.

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

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

With an output schema present, the description needn't detail response structure yet still flags the top-3-tokens payload; the schema handles address/entity mutual exclusion and time-range tokens, and the description adds the 30-day default and 365-day clamping. What remains missing is any pointing to the batch or related-addresses alternatives.

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

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

Schema coverage is 100% so the schema already documents address/entity exclusivity, enums, and time-range tokens; the description's list of sortable fields merely echoes the enum. Worse, the examples use 'order_by' while the schema property is 'orderBy', a naming mismatch that could lead an agent to send an unknown key, which offsets the illustrative value of 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?

Opens with a specific verb and resource: 'Get 25 (per page) addresses or entities with the most common interactions with input addresses', and immediately states the default sort and the extra data returned. It doesn't name any sibling (e.g. address_related_addresses or address_counterparties_batch), so an agent must infer the boundary from the name alone.

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 'Note: To get related wallets' block gives analytical usage guidance (focus on direct value transfers, include CEX deposit addresses, go one level deeper), which tells the agent what the output is good for. However, it never states when to use this tool instead of its clearly overlapping siblings like address_related_addresses or address_counterparties_batch, so tool selection 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 annotations, the description discloses important behavioral constraints: per-wallet lists are not aggregated, repeated addresses are removed, at most 10 addresses are allowed, the date range cannot exceed 90 days, and chain families cannot be mixed. It also warns that multi-chain results may repeat counterparties across rows and should not be summed.

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, per-wallet behavior, use cases, limits, and an example. It is somewhat long and repeats some schema details, but the example and constraints generally earn their place for a complex batch tool.

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

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

Given the output schema and rich annotations, the description covers the key invocation risks: wallet count, date window, chain-family mixing, pagination implications, and the correct sibling for non-batch use. Nothing essential for correct tool selection or 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 coverage is already 100%, so the schema documents parameters thoroughly. The description still adds operational meaning through a concrete request example, sort options, chain behavior, and limits that help an agent construct valid calls.

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: getting top counterparties for up to 10 wallet addresses in one call. It clearly distinguishes this batch tool from the single-wallet/entity tool by naming address_counterparties as the 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?

It explicitly says when to use this tool for comparing wallets, shared counterparties, common CEX deposits, or one fund with many wallets. It also states when not to use it: for one wallet or an entity name, use address_counterparties.

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/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: default ordering is newest-first, sortable by timestamp or value, and the exact spot vs perp column sets returned. It omits pagination behavior (the `page` param exists but nothing says page size or how to walk pages).

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?

Well front-loaded — purpose first, then chain rules, then column sets, then an example. The structure (headers, explicit lists) makes it scannable. Slightly padded by repeating the chain rules verbatim from the schema and by listing return columns that the output schema already covers.

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 the hard parts of a nested-parameter, multi-chain tool: chain requirement, perp vs spot differences, filter semantics, and a concrete request example. An output schema exists so return values needn't be spelled out. The remaining gap is pagination — `page` defaults to 1 with no guidance on result-set size or how to retrieve further pages.

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, but the description adds meaning beyond it: token filter fields switch semantics by chain (contract address on spot vs perp symbol selecting Long/Short on Hyperliquid) and the one-token-field restriction. Minor deduction because the chain rules are largely a restatement of the schema's own `chain` 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 ('Get a wallet's individual trades'), scopes it to a single chain, and distinguishes both data modes (DEX spot swaps vs Hyperliquid perps). It explicitly positions itself against the sibling `token_dex_trades` as the wallet-centric counterpart, so an agent can pick between them 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 routing rules: EVM wallets MUST pass `chain`, non-EVM is auto-detected, 'all'/'evm' are unsupported, use 'hyperliquid' for perps with an EVM address, and call once per chain to span networks. It also states that only one token filter field is allowed on Hyperliquid — a real invocation constraint, not just context.

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

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

The annotations already establish read-only, non-destructive, open-world behavior, and the description adds useful operational context: the funder is resolved across all chains, so no chain argument is needed. It does not discuss auth, rate limits, or edge cases, but it meaningfully supplements the structured safety hints.

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

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

The description is two tight sentences: the first states exactly what is returned, and the second explains the key use case and cross-chain behavior. It is front-loaded and has 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?

For a one-parameter read-only lookup with annotations and an output schema, the description supplies the essential purpose, usage rationale, and cross-chain resolution behavior. Nothing critical is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% for the single nested address parameter, so the schema already documents the input. The description adds useful meaning by clarifying that the address is an EVM wallet and that chain resolution is automatic, explaining why no chain parameter exists.

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 precise verb and resource: get the first address that ever funded an EVM wallet, plus the funding transaction hash, chain, and timestamp. The 'first funder' scope is clearly distinct from sibling tools such as address_counterparties, address_related_addresses, and address_transactions.

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: attributing an unlabelled wallet to a known entity because the first funder is often a CEX withdrawal or another wallet controlled by the same owner. It does not explicitly name when not to use it or compare against all plausible alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond purpose: no note on differing results for entity vs. address lookups, no hint about chain-wide ('all') scans being heavier, and no mention of what suspiciousFilter changes in the result.

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 tight sentence with no filler. It is front-loaded and wastes nothing, though its brevity is closer to under-specification than to disciplined editing.

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?

An output schema exists, so return values need not be described, and the schema fully documents the nested request. Still, for a tool that accepts either a wallet or an entity across a chain selector, the description leaves the agent to infer the entity path entirely from the 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 description coverage is 100%, including the mutually exclusive address/entity_id constraint and the lookbackDays enum, so the schema carries the semantics. The description contributes no extra parameter meaning, 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 and resource: retrieving historical native coin and token balances for an address. That is clearly distinct from address_portfolio (current holdings) and address_transactions, though the description never names those siblings to reinforce the distinction.

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?

There is no guidance on when to choose this over address_portfolio or smart_traders_and_funds_historical_token_balances. It also omits that an entity name can be supplied instead of a raw address, which is the main routing decision an agent faces here.

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 read-only and non-destructive. The description adds meaningful behavioral context by disclosing the exact label categories returned and the notable limitation that premium labels are not returned, which goes beyond the structured annotations.

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

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

The description is two compact sentences with no filler. It front-loads the core action in the first sentence and adds the key exclusion in the second, making it easy for an agent to parse quickly.

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

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

Given the rich nested input schema, presence of an output schema, and safety annotations, the description is nearly complete. It clearly defines the tool's scope and key exclusion, though it could briefly mention an alternative for premium labels or define 'standard labels' more precisely.

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 every parameter is already documented in the input schema. The description adds little parameter-level meaning beyond confirming the tool targets a single wallet address, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Get the standard labels for one wallet address.' It further specifies the label categories returned (identity, behavioural, protocol) and explicitly excludes premium labels, which distinguishes it from other address-related tools.

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

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

The description conveys when to use the tool—when standard labels for a wallet are needed—and clarifies that premium labels are not included. However, it does not name an alternative tool or provide explicit when-not-to-use guidance, leaving some routing to inference from the sibling list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that liquidation risk is returned and that no separate portfolio call is needed, but says nothing about whether only open positions are included, how liquidation risk is derived, or any limits.

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 front-loaded sentence with no filler. It is efficient, though arguably terse for a tool with nested filter and sort structures.

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

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

With an output schema, rich annotations and full schema coverage, the description only needs to establish purpose and routing, which it does. The one gap is that it never hints the tool supports filtering and sorting, which an agent might otherwise miss.

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

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

Schema description coverage is 100% and the nested request object documents address, filters (tokenSymbol, positionType, value/PnL ranges) and orderBy in detail. The description contributes nothing about these parameters, so it neither compensates nor detracts — baseline 3.

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

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

Specific verb + resource: it returns a wallet's Hyperliquid perpetual positions plus liquidation risk. The phrase 'without a portfolio lookup' implicitly contrasts it with the heavier address_portfolio sibling, though that sibling is never named explicitly.

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 clause 'without a portfolio lookup' hints that this is the lightweight path when the full portfolio isn't needed, which is useful implied guidance. There is no explicit when-to-use/when-not statement and no named alternative for cases where portfolio context is 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 readOnly/destructive/openWorld, so the description's added value is the output-handling contract: 'pre-formatted markdown that should be presented exactly as returned, preserving all tables... without reinterpretation', plus the note that entities aggregate balances across all associated addresses. This is genuinely useful non-schema behavior. It loses a point for internal inconsistency, claiming markdown output globally while examples for 'defi' and 'hyperliquid' say '(returns raw JSON)'.

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 critical behavior (markdown must be preserved verbatim) is buried mid-description after a long mode list, and the mode bullet list duplicates the schema's own mode enum almost verbatim. Filler like 'This tool provides flexible portfolio analysis in a single request, allowing users to focus on specific aspects of their holdings' adds no decision-relevant information, and the four example blocks are repetitive.

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

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

With 100% schema coverage, an output schema, and nested request objects, the description covers the pieces an agent needs: mode semantics, the XOR constraint on walletAddress/entity_id, and output presentation rules. The unresolved markdown-vs-raw-JSON ambiguity across modes and the unmentioned 'chain' parameter are the 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?

Schema description coverage is 100%, and the nested request's mode and identity fields are already documented in the schema in nearly identical wording, so the description mostly restates structured data. The worked examples do add concrete invocation shapes for each mode. The 'chain' parameter (default 'all') is never mentioned in the description, leaving a small gap the schema does not fill either.

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 ('Get comprehensive portfolio overview') and scopes it to a wallet address or entity, with a mode breakdown that makes the returned surface concrete. It does not explicitly distinguish itself from overlapping siblings such as address_perp_positions, address_historical_balances, or address_dex_trades, so an agent cannot be certain it is the right tool for a narrower 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?

Each mode is explained in terms of what it includes and excludes (e.g., fast-mode-default 'skip defi, for fast mode only'; defi 'excluding Hyperliquid'), which gives the agent clear selection context. It also states the entity-vs-wallet constraint. However, it never says when to prefer a sibling tool over one of these modes, so no real exclusion guidance exists.

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/non-destructive, so safety is covered; the description goes further by scoping the result set to a fixed list of 'special' connections and warning that first-funder exchange addresses usually do not belong to the same entity. That is a real analytical caveat that saves the agent from a wrong inference. It doesn't mention pagination or result volume.

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 is front-loaded in the first sentence, with caveats following in a clearly separated note. Some waste exists ('the the' typo, an awkward multi-clause enumeration) but every sentence 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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. The description fills the main gap by defining which relationships count as 'related'. Only the chain parameter's behavior is left entirely to the 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 nested request already documents address and chain, so the baseline applies. The description adds nothing about the chain parameter (default 'all') or how scope changes results. Marginal value beyond the schema.

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

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

States a specific verb and resource: 'Get information about related addresses of an input address.' The note enumerates the exact connection types returned, which is unusual precision. It stops short of fully distinguishing itself from address_counterparties and address_first_funder, which it only gestures at.

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?

'To get related wallets, also check address counterparties' explicitly names the complementary sibling and the condition for using it. The note about first-funder exchange withdrawal addresses being a false positive is genuine usage guidance. No explicit statement of when NOT to use this tool in favor of address_first_funder or address_labels.

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/openWorld/non-destructive, so the bar is lower; the description still adds substantive behavior: page size of 20, latest-transactions-only ordering, entity lookups aggregating across wallets, and a 7-day clamp. It does not mention rate limits or pagination exhaustion, but the added context is well 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?

Four short sentences, front-loaded with the core action and result size, then the parameter rule and the entity caveat. Slight redundancy with schema text ('covers at most 7 days') 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?

An output schema exists, so return shape needn't be explained; the description covers the essentials an agent needs — result cap, recency, mutually exclusive selectors, entity aggregation and date clamping. Minor gaps like chain selection are already handled in the 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 description coverage is 100%, so the baseline is 3. The description's statements about address/entity_id exclusivity and the 7-day entity window largely restate what the nested schema already documents, so it adds little new parameter 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 verb and resource ('Get list of ... transactions') plus a precise scope (20 most recent per page, address or entity). It is distinguishable from siblings like address_counterparties or transaction_lookup by the recency/list framing, though it never names an alternative explicitly.

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

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

The description gives a real constraint — 'Provide exactly one of `address` or `entity_id`' — and notes the entity path spans all wallets with a 7-day cap, which is genuine usage guidance. It gives no when-to-use vs when-not guidance relative to sibling tools such as address_dex_trades or transaction_lookup, leaving the agent to infer 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 mark this as read-only and non-destructive, and the description adds matching behavior beyond that: case-insensitive matching, matching anywhere in the name, and returning exact entity names. This gives the agent useful expectations without contradicting the annotations.

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

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

Three sentences carry the purpose, use case, example, and routing rule with no filler. The main behavior is front-loaded before the alternative guidance.

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

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

The tool is simple, has full schema coverage, annotations, and an output schema, so the description does not need to explain return formats. It covers purpose, usage timing, matching semantics, and alternatives, making it complete for an agent to invoke correctly.

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

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

The input schema already documents both parameters with 100% coverage, so the baseline is a 3. The description adds value by explaining how search_query is interpreted (case-insensitive, partial, matches anywhere) beyond the schema's 'Partial entity name' phrasing.

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

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

The description clearly states a specific verb and resource: search Nansen entity names by partial name and return exact matching names. It also distinguishes itself from general_search, which is for tokens or addresses, so an agent can tell sibling tools apart.

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 rule: when a downstream tool needs an exact entity name but the user provided an approximate one, with a concrete example. It also states the alternative for tokens/addresses, making the routing decision unambiguous.

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, non-destructive behavior, and the description adds useful scope and limitation context, especially the NFT support caveat and premium-label restriction. It does not add much about rate limits, pagination, or auth, but the safety profile is already covered by annotations.

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

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

The description is front-loaded with the primary purpose and exclusion, then uses a readable bullet list for capabilities. It is somewhat verbose, but the structure makes the long capability list scannable and useful for a broad search tool.

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

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

Given the tool's breadth, annotations, 100% schema coverage, and presence of an output schema, the description is complete enough for correct selection and invocation. It covers primary use, exclusions, supported query categories, and important domain limitations.

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 four parameters in detail. The description adds some query-type nuance by mentioning domains and Nansen labels, but for most parameters it does not add 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 states a specific verb and resource: a general search entry point for tokens, entities, and addresses. It also distinguishes the tool from prediction-market search by naming `prediction_market_lookup` as the sibling for that domain.

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 routing guidance: use this as the FIRST entry point, do not use it for prediction markets, and use `prediction_market_lookup` for Polymarket names, topics, slugs, or URLs. It also clarifies the NFT limitation while explaining when a token check may still be appropriate.

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

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

Annotations only declare readOnly/non-destructive; the description adds material behavior the annotations can't: zero credit cost, no report slot consumption, and a uniform not-found response for unknown, expired, and other-account IDs (an important information-disclosure/anti-enumeration trait). It also explicitly declines to promise a fix or delivery date, which sets correct expectations for the returned status.

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 cost and lookup mechanics, then the status semantics, then the guardrails – a sensible order with no filler sentences. The two closing sentences about not creating replacements / not redirecting overlap somewhat, but each adds a distinct prohibition.

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

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

With an output schema present, the description needn't document return shape, and annotations already cover the safety profile. What remains – status meaning (received/reviewed/closed), cost, slot consumption, and not-found behavior – is all supplied, so 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 description coverage is 0%, so the description carries the burden for the single feedback_id parameter. It confirms the lookup is by feedback_id, but never says where the ID comes from (presumably the submit_feedback response) or anything about the accepted format constraints already expressed only as a regex in the schema, so it doesn't fully 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 opening sentence states a specific verb (read) and resource (Nansen feedback receipt) and scopes it to the authenticated account, which clearly separates it from the write-side submit_feedback and from get_feedback_preferences. It stops short of naming a sibling tool explicitly, so the differentiation is implied by the read/write split rather than stated.

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?

Goes well beyond a generic 'use this to look up feedback': it says the lookup is keyed on feedback_id, consumes no report slot, and gives explicit negative guidance for the failure path (do not create a replacement report, do not use another account or an internal server key, do not redirect to unrelated feedback channels). An agent knows both what to call this for and what not to do when it fails.

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/destructiveHint/openWorldHint, yet the description adds real behavior: it is free with no report quota, reads are fresh, scope is the current account only, and the preference must never be enabled automatically. The trailing 'Direct lasting changes to Superapp settings' fragment is confusing on a read-only tool and reads like a truncated negation.

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 is front-loaded, but the body is a dense block of consent policy and includes an ambiguous fragment ('Direct lasting changes to Superapp settings') that costs comprehension. Much of the policy is legitimate, but it is not organized for scanning.

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

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

An output schema exists, so return values needn't be explained, and the description covers the consent and scoping context thoroughly. The only real gap is the undocumented required 'request' parameter.

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 there is a required 'request' object with no properties. The description says nothing about what goes in it or why it is required and empty, so the parameter is 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?

The opening sentence states a specific verb and resource: 'Read the authenticated account's saved automatic feedback preference.' That is enough to separate it from siblings like get_feedback and submit_feedback, though the description never names those siblings to reinforce the distinction.

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 trigger ('Before a new automatic report about useful Nansen friction... call this tool') and spells out outcome branches (enabled permits sending subject to controls; off/unconfigured means show and ask first). It does not explicitly compare against get_feedback, which 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the dimension set being ranked, but leaves open whether all four rankings are returned together or one is selected (no metric parameter exists), what the ranking order/direction is, and how pagination works despite the schema's request doc mentioning 'pagination settings'. Useful but thin given the ambiguity.

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 front-loaded sentence with zero filler, but the terseness is part of why behavioral questions go unanswered.

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?

An output schema exists, so return values need not be explained, and the single nested request parameter is fully documented. Still, the description does not resolve the central ambiguity of what 'growth ranking' means per metric or how metrics map to output, which matters for a tool with four named dimensions and only two filter 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 description coverage is 100%; chain_type and time_frame both carry enums, defaults, and descriptions. The prose adds no guidance beyond the schema, and the metric names it mentions do not correspond to any parameter, 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?

"Get chain growth rankings" names a specific verb and resource, and the four metrics (active addresses, transactions, gas fees, DEX volume) scope what the ranking covers. It is clear on its own terms, though it does not distinguish itself from any adjacent tool (there is no direct sibling, so the cost 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?

There is no statement of when to use this versus alternatives, no prerequisites, and no exclusions. The agent must infer usage entirely from the name and title.

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 a safe read, so the description correctly spends its budget on semantics beyond annotations: UTC calendar-boundary date handling, the 'null/empty means unavailable, not zero' caveat, the account-value limitation to top 500K traders, and the warning that realized PnL is net so no win rate is derivable. These are non-obvious behavioral facts an agent could not get 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?

Front-loaded with the one-line purpose, then organized into Returns / Columns / Sorting / Filtering / Example / Notes sections that are easy to scan. Some redundancy exists — the date-range token semantics are restated from the schema's own parameter descriptions — which keeps it from a 5.

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

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

For a single nested request parameter with sorting, filtering, paging and a markdown return, the description covers everything needed: column meanings, sortable fields, filter semantics, a runnable example, and the alternative tool. An output schema exists, yet the column glossary still adds value by explaining units and derivability rather than just shapes.

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 earns credit for clarifying that roi is a fractional ratio ('pass 0.1 for "10% or better", not 10') — a trap the schema's bare 'Filter by ROI (from/to)' does not close. The worked example also concretely demonstrates composing date, accountValue and totalPnl ranges plus ordering.

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 sentence names a specific verb and resource ('Get Hyperliquid perpetual futures trader leaderboard') and scopes it ('Hyperliquid perpetual futures only'), which separates it from the token, prediction-market and smart-money leaderboard siblings. The follow-up pointer to address_portfolio for open positions further pins down its role.

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

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

It gives an explicit alternative for the adjacent use case ('For a trader's open positions, call address_portfolio with mode="hyperliquid"'), which is genuine routing guidance. It does not, however, distinguish itself from token_pnl_leaderboard, smart_traders_and_funds_pnl_leaderboard, or prediction_market_pnl_leaderboard, so the agent must still infer which leaderboard to pick.

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 with readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context not present in annotations: results are pre-filtered by Performance Score >=15, data is updated in batches, output columns are dynamic, and scoring thresholds must be explained to users.

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 well structured with clear sections for usage, alternatives, scoring, and returns. It is somewhat long and repeats the Performance Score >=15 threshold in multiple places, which keeps it from being maximally concise.

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

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

Given the presence of annotations, an output schema, and 100% schema description coverage, the description is complete for correct invocation. It explains the ranking logic, filtering behavior, output shape, and scoring interpretation without needing to restate schema details.

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 single marketCapGroup parameter is already well documented in the schema. The description does not add parameter-specific details such as market-cap filtering semantics, so the 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 and resource: discover/filter a daily list of tokens ranked by Nansen Score. It also explicitly distinguishes this tool from token_quant_scores and token_discovery_screener, so an agent can identify its role 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?

It gives explicit when-to-use guidance, including the exact scenario for this tool versus token_quant_scores and a detailed comparison against token_discovery_screener. Example queries further remove ambiguity about the intended invocation context.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), yet the description still adds real behavioral context: each row is one market and must be summed, blank PnL fields mean unavailable rather than zero, and the API exposes no ROI or share count. It stops short of permissions, rate limits, or pagination behavior, but the data-shape caveats are exactly what prevents misreporting.

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 purpose followed by tight, labeled sections; every pitfall earns its place. The per-field definitions partly restate information an output schema already carries, so a little length is not strictly necessary, but the formula for Total PnL adds interpretive value.

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

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

For a read-only per-market breakdown with an output schema present, the description covers the one thing the schema cannot: how rows aggregate into a wallet total and how to interpret blank values. Nothing needed to call or trust the result 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 is effectively one meaningful parameter (nested `request.address`, plus `page`), and the schema documents both at 100% coverage with a default for `page`. The description adds only that the address is a Polygon wallet, which is already implied by the purpose statement, so it does little beyond the schema — baseline 3.

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

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

States a specific resource and verb: a per-market PnL breakdown for a Polygon wallet. The Pitfalls section explicitly distinguishes it from the sibling `prediction_market_address_summary`, which returns the aggregate, so an agent can pick the right tool 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?

A dedicated "When to use" line gives the selecting condition (wallet-level Polymarket track record with per-market cost and proceeds), and the Pitfalls section names the alternative tool and the exact condition for switching to it (summing rows vs. the summary endpoint).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description still adds real value: it defines what each reported field means (Win Rate = won/traded, Total PnL = realized + unrealized), flags what the API does NOT return (trade count, volume, ROI), and warns that blank PnL means unavailable, not zero. That last point is a genuine data-quality trap an agent would otherwise mishandle.

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?

Well structured and front-loaded: one-line purpose, then When to use, Key fields, Pitfalls in priority order. Slightly verbose in the Key fields bullets, but each carries non-obvious semantics rather than restating the schema.

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

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

An output schema exists, yet the description goes further by interpreting the returned fields and their failure modes, which is what an agent needs to report results responsibly. Nothing material for correct selection or interpretation 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%, so the address and page fields are already documented in structured form, and nested request wrapping is explicit. The description contributes only the implicit constraint that the address is a Polygon wallet; it says nothing about the pagination parameter. 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 opening line states a specific resource and scope: lifetime summary metrics for a Polygon (Polymarket) wallet. It explicitly frames itself as the entry-level wallet overview, which separates it from depth tools like prediction_market_address_pnl and prediction_market_address_trades.

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

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

The 'When to use' block names the triggering conditions (general wallet profile, activity summary, is-this-wallet-active) and the ordering rule (call this first, before detailed trades/PnL). The Pitfalls section names the explicit alternative — prediction_market_address_pnl — for per-market cost and proceeds, so routing is unambiguous.

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 (readOnlyHint, destructiveHint false) and openness, and an output schema exists, so the description rightly spends its budget on data semantics rather than restating safety. The two field notes are genuine disambiguation aids — clarifying that `Value USD` is per-row, not per-transaction, prevents a real misinterpretation. It says nothing about pagination behavior or result caps, which would have made it 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 core purpose is front-loaded in the first sentence, followed by only the two field caveats and one routing pitfall that actually change how results are read. No filler, no restatement of the title.

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

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

For a single-parameter read tool with a full output schema, the description covers scope, field interpretation, and the main misuse case. The remaining gap is chain scope — it says "Polygon wallet" but not whether non-Polygon addresses return empty or error, which the agent may need in order to handle bad input.

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%, including a very detailed dateRange token spec, so the schema carries the parameter burden and baseline 3 applies. The description only contributes the implicit constraint that the address is a Polygon wallet; it adds nothing about the page parameter or the default 30-day window.

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 ("trade history") plus a scope qualifier ("for a Polygon wallet"), which separates it from the market-wide prediction_market_trades sibling. The differentiation is implicit, though — it never names prediction_market_trades or prediction_market_address_pnl directly, so the agent must infer the boundary.

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 Pitfalls line gives an explicit when-not ("not profitability") with a positive statement of the right context ("wallet trade activity"). It stops short of naming the alternative tool that should be used for profitability (prediction_market_address_pnl or prediction_market_address_summary), so routing still requires a small 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 readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered; the description adds real substance on top — it names the underlying Polymarket search API, states that results include outcome prices, last trade price and bid/ask inline, and gives a behavioral rule ('if lookup returns no suitable market... say so explicitly — do not silently substitute'). It does not mention pagination behavior or rate limits despite a `page` parameter existing.

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?

Bold section headers ('PM building blocks', 'When to use', 'Query tips', 'Output rules') front-load the routing decision, and the event/market example earns its place because it prevents a wrong `marketId` call. It runs slightly long and some bullets (e.g. the broad multi-topic query warning) are marginal, but there is no true 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?

An output schema exists, so return shape need not be described, and the description still covers the qualitative output contract (inline prices, no silent substitution). For a single nested-request parameter with 100% schema coverage and full annotations, nothing an agent needs in order 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 description coverage is 100%, so a 3 would be the floor, but the description goes further: it explains that `queryVariant` is a cleaner short keyword form of a slug, that `includeEventMarkets` returns child markets of the best-matching event, and that queries should be 1–3 keywords, which is usage semantics the schema does not convey. The `page` and `status` parameters get no prose treatment.

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 (Search) and resource (Polymarket events and markets) plus the input forms accepted (name, topic, URL, slug). The 'PM building blocks' section explicitly defines event vs. market and warns that detail tools need `marketId`, not `eventId`, which lets an agent separate this tool from prediction_market_ohlcv and the other PM siblings 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?

Has an explicit 'When to use' block that names the trigger condition (topic/slug/URL but no marketId) and names alternatives directly: 'Do NOT use general_search for prediction markets' and 'for price history... use prediction_market_ohlcv'. It also distinguishes the quick probability check case from the history case, which is exactly the boundary an agent 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, openWorld, and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: it warns not to mix dates/prices across markets, and instructs the agent to say so directly rather than estimate when no candles are returned. These are useful operating constraints not captured by annotations.

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

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

The description is front-loaded with purpose followed by clearly labeled sections (When to use, Key fields, Pitfalls, Prerequisites). Every section adds value, though the bold-headed formatting is slightly heavier than strictly necessary for a single-parameter tool.

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

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

An output schema exists, so the description needn't explain return values, and it still adds the important note about Close signifying the displayed outcome side. It covers the prerequisites and pitfalls an agent needs. The only minor gap is not distinguishing itself from orderbook/trades siblings for overlapping use cases.

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

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

Schema coverage is 100%, and the description adds no direct guidance on parameters like dateRange or orderBy beyond saying it defaults to the last 30 days (also in schema). The Close/Yes-No complementarity note explains output semantics rather than parameters. Baseline 3 is appropriate 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?

The description opens with a specific verb+resource: 'Historical odds/volume candles for a Polymarket market.' This clearly distinguishes it from siblings like prediction_market_orderbook and prediction_market_trades. It doesn't contrast with sibling alternatives explicitly, so it falls short of a 5, but the purpose is unambiguous.

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

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

A dedicated 'When to use' section names price history and recent probability changes, and the Prerequisites section routes to prediction_market_lookup when marketId is unknown. It lacks explicit 'when not to use' guidance (e.g., use orderbook for current depth or trades for individual fills), so it lands 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/openWorld/non-destructive, yet the description adds substantial domain behavior: units disclosure (share size vs USD), the Yes+No≈$1 complementarity, the trap of reading No bids as Yes support, and the conversion step needed for cross-tool comparison. This is meaningful context beyond the safety profile.

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

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

Front-loads the one-line purpose, then sections for when-to-use, key fields, price relationship, pitfalls, and prerequisites. Every block is useful, though the Yes/No pricing explanation runs a few lines longer than strictly needed for tool selection.

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

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

With an output schema present, return values need not be described. The description covers when to call, prerequisites, field units, and interpretation pitfalls, leaving no material 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 coverage is 100% and both query fields (marketId, page) are documented in the schema, so the baseline is 3. The description adds routing value by telling the agent where to obtain marketId (prediction_market_lookup), which goes slightly beyond the schema's own note pointing to the screener.

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 scope: 'Live orderbook for a Polymarket market.' It also implicitly delineates from siblings by naming prediction_market_ohlcv for odds and prediction_market_lookup for ID resolution, 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' block names the use case (bid/ask depth, liquidity, order structure) and explicitly redirects to prediction_market_ohlcv for implied probability/odds, with a stated prerequisite to call prediction_market_lookup when marketId is unknown. Alternatives and conditions are spelled out.

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/open-world safety, while the description adds substantive behavior: how Total PnL is composed, which metrics the API lacks, and what to do when PnL fields are blank. Those are operational constraints beyond what annotations provide.

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 organized into 'When to use', 'Key fields', 'Pitfalls', and 'Prerequisites'. The field definitions and pitfalls are relevant to correct interpretation, and there is no obvious filler despite the Key fields block being the longest section.

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 a documented schema and output schema, the description supplies purpose, usage constraints, field semantics, and failure handling. The notable gap is the inconsistent marketId prerequisite, which leaves sourcing guidance ambiguous.

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 100% schema description coverage, the schema already documents marketId and page, so the baseline is 3. The description adds a prerequisite, but it conflicts with the schema's note that marketId comes from prediction_market_screener by directing agents to prediction_market_lookup instead; that inconsistency prevents credit above baseline.

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

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

The opening sentence names the specific verb/resource and scope ('PnL leaderboard for a Polymarket market'), and the 'Only for profitability claims' line plus pitfalls distinguish it from holder/position tools. An agent can tell this is market-level PnL, not address-level or top-holder 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 provides a clear when-to-use rule ('Only for profitability claims') and explicit exclusions ('do not substitute top holders or position size'), plus a prerequisite for resolving marketId. It stops short of naming the relevant alternative sibling for other PnL scopes, so it is not a full when/when-not/alternatives statement.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered; the description adds real value beyond that by explaining row granularity (one outcome token per wallet) and by scoping Position PnL to the displayed row rather than wallet totals. It does not describe pagination behavior or result-set size, which is the main behavioral 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?

Front-loaded purpose sentence followed by scannable Key fields and Pitfalls sections; each field note explains a non-obvious accounting distinction rather than restating the field name. Minor redundancy with the output schema and a slightly heavy bullet list keep it from a 5.

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

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

With an output schema present, the description need not explain return format, yet it goes further by interpreting the trickiest fields and warning about duplicate wallets. The remaining gaps are pagination semantics and explicit sibling routing; note also that the description says to use prediction_market_lookup for marketId while the schema description points to prediction_market_screener, a minor inconsistency an agent must reconcile.

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

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

Schema description coverage is 100% and the nested request object documents both marketId and page with constraints, so the schema carries the load. The description repeats the marketId sourcing hint but adds no semantics for the page parameter or result ordering, 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 and resource: a detailed position breakdown for a Polymarket market, with field-level semantics for position size, cost, proceeds, unrealized/redemption value and PnL. It implicitly separates itself from sibling tools like prediction_market_address_pnl by noting each row is one outcome token of one wallet, but it never explicitly names the sibling it is not, leaving the market-wide vs per-wallet distinction to be inferred.

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 prerequisite rule — call prediction_market_lookup first if marketId is unknown — and a usage pitfall about wallets holding both outcome sides appearing twice. It offers no guidance, however, on when to prefer this over related siblings such as prediction_market_address_pnl, prediction_market_top_holders, or prediction_market_address_summary.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior: matching is literal-style rather than fuzzy web search, no-match results should not be backfilled with nearest guesses, and superlatives must map to the shown metric. Pagination/rate behavior is left implicit, keeping this just 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-loaded with the core action in sentence one, then cleanly sectioned with bold headers. Slightly long, and the anti-hallucination rules overlap a little with the no-match rule, but nearly every line carries actionable instruction rather than 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?

An output schema exists and all four nested request parameters are documented, so return values and parameter shapes need no prose. Combined with the annotations, the description covers everything an agent needs to select, scope, and interpret calls to this screener.

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, but the query tips add real meaning about the `query` parameter — short topic fragments, no multi-topic bundling, split broad questions into separate calls. That goes beyond the schema's "Optional text query for filtering" and shapes how the parameter should actually be filled.

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 ("Browse and sort Polymarket markets, events, or categories") and explicitly distinguishes itself from the sibling prediction_market_lookup. An agent can route between the two 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?

Contains an explicit "When to use" block plus a negative rule naming the alternative tool for single named markets/slugs/URLs. It also covers failure handling (no rows returned → do not invent a nearest match), which is real invocation guidance rather than restated metadata.

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, non-destructive, open-world. The Pitfalls block still adds real value beyond them: the table is the source of truth, the summary reflects only shown rows, and labels/large positions must not be read as smart money. It doesn't mention pagination limits or how far the 'visible' table extends, which matters for a paginated holder list.

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 one-liner followed by labeled blocks, so an agent can stop after sentence one if it already knows the market ID. The "Key fields" block partly restates what the output schema already provides, which costs some of the budget.

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

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

With annotations, a full output schema, and complete parameter documentation, the description only has to supply the reasoning constraints — and it does, via the pitfall about not inferring risk/PnL beyond explicit output. Only the pagination/row-count behavior for the 'visible table' caveat is left unspecified.

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?

Every parameter is documented in the schema (100% coverage), including the `orderBy` enum and default, so the description adds nothing on paging or sorting. The "Key fields" bullets describe output columns rather than inputs, so they don't compensate further on parameter meaning.

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

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

The opening line states a concrete verb and resource — "Largest current holders for a Polymarket market" — which pins both the operation and the domain. The Polymarket scoping directly distinguishes it from token_current_top_holders and from the address-level prediction market siblings such as prediction_market_address_pnl.

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 Prerequisites section gives an explicit routing rule: if `marketId` is unknown, call prediction_market_lookup first. It doesn't state any when-not-to-use conditions or contrast with prediction_market_position_detail / prediction_market_trades, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds real interpretive context — per-row trade-leg semantics for 'Value USD' and the pitfall that large visible trades do not imply smart money. It does not mention pagination behavior or result limits, 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?

Front-loaded one-line purpose followed by labeled sections (When to use, Key fields, Pitfalls, Prerequisites), which is scannable and each block carries usable information. Slightly verbose formatting for the payload, but 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?

With an output schema present, the description needn't explain return values, and it instead supplies the interpretation guidance (per-leg value, smart-money caveat) plus the marketId acquisition path. Combined with readOnly annotations, an agent has everything needed to call and interpret results correctly.

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

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

Schema coverage is 100%, with page, marketId, and dateRange all fully documented including token syntax, so the schema already carries parameter meaning. The description's 'Key fields' section describes output fields rather than parameters and adds nothing about marketId or dateRange usage, leaving baseline territory.

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 ('Recent trades for a Polymarket market') with market scoping, so an agent knows exactly what it retrieves. It does not explicitly differentiate itself from siblings like prediction_market_address_trades or prediction_market_position_detail, but the market-level trade tape framing is distinct enough in practice.

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' section positions it as the source of truth for fills and warns against overwriting recent trade prices with older OHLCV candles, which effectively routes the agent away from prediction_market_ohlcv for tape data. The prerequisite line telling the agent to call prediction_market_lookup first when marketId is unknown is exactly the kind of conditional guidance that prevents failed 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 declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the Solana-only scope and the kinds of data returned, but does not discuss pagination behavior, data freshness, or rate limits. With annotations covering the critical safety traits, a 3 is appropriate.

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

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

The description is two sentences, front-loads the tool's purpose, and then adds a crisp usage distinction. There is no redundant or wasted phrasing.

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 rich input schema, annotation coverage, and existing output schema, the description is complete enough for selection and invocation. The main missing context is how this differs from the sibling token_jup_dca tool and any pagination expectations, though the schema and tool prefix mitigate those 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?

Schema description coverage is 100%, and the nested request parameters are individually documented, so the schema already carries parameter semantics. The description does not explain filter behavior such as traderAddress, token symbol filters, numeric ranges, or smart-money label selection beyond the general 'opened by smart traders' phrasing. Baseline 3 is correct 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?

The description states a specific verb and resource: getting Jupiter DCA orders opened by smart traders on Solana. It also names the returned concepts (deposit size, amount spent, order status) and explicitly distinguishes the tool from smart_traders_and_funds_dex_trades.

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

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

It gives explicit when-to-use guidance: 'Use this for scheduled accumulation intent.' It also names the relevant alternative and its condition: 'use smart_traders_and_funds_dex_trades for one-off swaps.' This is enough for an agent to choose between them without opening the schema.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real context beyond that: the composition of the result set (smart traders only, whales/influencers excluded) and the default all-chains scope. It stops short of covering pagination behavior or result-size expectations, which matters given a page parameter.

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, zero filler. The scope/exclusion detail comes first, then the routing alternative, so the most decision-relevant information 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?

An output schema exists, so return shape needn't be explained, and annotations carry the safety profile. Combined with the fully documented nested request schema and the explicit sibling routing, an agent has everything needed to select and call this correctly.

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

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

Schema description coverage is 100% and every request field, including chains, orderBy, trade value range and label filters, is documented inline. The description's only parameter-adjacent contribution is restating the ['all'] chain default, which the schema already says, 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 verb and resource ('Get individual per wallet, per transaction DEX trades'), and pins down the subject population: smart traders only, explicitly excluding whales, large holders and influencers. That scope statement distinguishes it from the aggregated smart-money siblings without any schema inspection.

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?

Names the concrete use case ('see exactly which wallet bought or sold what') and routes the agent to the alternative, smart_traders_and_funds_netflow, for the aggregated view. The selection condition is stated, not inferred.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful domain context by stating that whales, large holders, and influencers are excluded, and by clarifying inclusive UTC calendar date 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?

Three sentences are front-loaded with the core action, then the alternative-tool distinction, then the date semantics. Each sentence contributes useful selection or invocation context.

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

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

The description covers purpose, scope, exclusions, supported chains, date semantics, and the current-snapshot alternative. With a fully described nested schema, annotations, and an output schema, nothing essential is missing 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 100%, so the nested request fields and date-range tokens are already fully documented in the schema. The description restates date-range and chain semantics but adds little parameter-level detail beyond what the schema provides.

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

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

The description states a specific verb and resource: get day-by-day history of aggregated smart trader token balances, with explicit exclusions and supported chains. It also distinguishes the tool from the current-snapshot sibling, so an agent can identify 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?

The description explicitly says to use this tool to see how smart money holdings changed over time and names smart_traders_and_funds_token_balances as the alternative for the current snapshot. That gives a clear when-to-use rule against a specific sibling.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral scope beyond annotations: results are aggregated rather than per wallet, certain wallet categories are excluded, and chain coverage defaults to all supported chains.

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 are used with no waste: the first front-loads the core scope and constraints, and the second clarifies when to use this tool versus the holdings sibling.

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

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

The tool is complex with a nested request object, but the schema has 100% description coverage and an output schema exists. The description supplies the essential scope, exclusions, default chain behavior, and sibling routing, leaving parameter and return details to the structured fields.

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 nested request parameters are already well documented. The description reinforces the chain default and available timeframes, but adds little parameter-specific syntax or filtering semantics beyond what the schema provides.

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

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

The description states a specific verb (Get) and resource (aggregated smart trader net USD flow per token) with scope details: aggregated not per-wallet, excluding whales/large holders/influencers, across 1h/24h/7d/30d and chains. It also distinguishes the tool from smart_traders_and_funds_token_balances by contrasting buying/selling flows with holdings.

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 usage guidance: use this for what smart money is buying or selling right now, and use smart_traders_and_funds_token_balances for what they hold. That directly routes the agent between the two closest alternatives.

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

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

Annotations already cover the safety profile (readOnly, non-destructive), and the description adds behavior the annotations cannot express: Hyperliquid/perp-only coverage, a fixed cohort, recent-trades-only with no date filtering, and the sortable fields. That is exactly the extra context this dimension rewards.

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 the sibling routing rule, then caveats, then structured reference material. The column list is long and largely duplicates the output schema, but the headers and short examples keep it scannable; a bit of trimming 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 filtered read tool, everything an agent needs is present: scope, cohort semantics, freshness limits, sortable fields, filter combinations, and an explicit alternative. The presence of an output schema makes the column enumeration optional rather than necessary, so nothing important 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 already 100%, so the baseline is 3, but the description earns more by explaining that labels are a subgroup filter on a fixed Smart Money cohort rather than a global label search, and by listing valid sort keys with an example. The only gap is that the page parameter and its pagination semantics are never mentioned.

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 ('Get recent Hyperliquid perpetual futures trades from Smart Money addresses across all tokens'), and explicitly distinguishes this from token_discovery_screener. The Hyperliquid-only scope further sharpens the boundary against sibling DEX/spot trade 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?

Gives an explicit alternative and the condition that selects it ('For a broad view of Smart Money activity across all tokens, use token_discovery_screener with traderType="sm"'), plus a clear caveat about what the optional labels do and do not do. It also warns that no date filtering is available, which prevents a whole class of misuse.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the description's added value is the entity-type exclusion rule and the set of returned performance metrics, both of which change how an agent interprets results. It stops short of noting pagination or result-size behavior, 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?

Two sentences, both earning their place: the first front-loads scope, metrics and windows; the second routes the agent to the correct sibling. No filler or restatement of the title.

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

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

With an output schema present, return values need not be spelled out, and the nested request object is fully documented in-schema. The description supplies the business-level semantics (who counts as smart money, what PnL variants exist); only minor gaps like paging behavior remain.

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

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

Schema description coverage is 100% and each nested property (chains, orderBy, timeframe, orderByDirection, includeSmartMoneyLabels) is documented in the schema itself. The description restates the timeframe windows and metric names but adds no syntax or default guidance 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 (rank), resource (smart trader addresses), the metrics ranked (realized/unrealized/total USD PnL, ROI, win rate, trade counts), and the supported windows. It also declares a scope exclusion (whales, large holders, influencers), which sharpens what 'smart money' means here.

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 ('find the best performing smart money wallets') and names the alternative ('use token_pnl_leaderboard for the best performers on one specific token'), giving the selecting condition rather than leaving it 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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds meaningful behavioral context by clarifying that results are aggregated rather than per wallet, exclude whales/large holders/influencers, and cover all chains by default, though it does not mention pagination or rate-limit behavior.

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

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

The description is two sentences and front-loads the core purpose and aggregation/exclusion behavior. The second sentence is generic and somewhat vague, but the overall structure is efficient.

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

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

Given a rich input schema with 100% description coverage and an output schema, the description provides enough context for correct invocation: aggregation, exclusions, chain scope, and default behavior. Minor gaps around pagination and sorting are acceptable because those details are covered by the 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 description coverage is 100%, so the schema already documents the nested request parameters in detail. The description only reinforces the default chains behavior and general filter usage, adding little parameter semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: getting aggregated smart trader token balances and 24h change per chain. It clearly distinguishes the result from per-wallet data and notes exclusions like whales and influencers, but it does not explicitly distinguish itself from the closely named historical token balances sibling.

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 only usage guidance is 'Use filters to narrow down the results,' plus an explanation of the default chain scope. It does not say when to choose this tool over related siblings such as smart_traders_and_funds_historical_token_balances, netflow, or token_flows.

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 far beyond the annotations: zero-credit cost, a concrete rate limit (seven accepted reports per account per week, Monday 00:00 UTC reset), idempotency semantics for submission_id including the timeout rule, and the meaning of the feedback_not_enabled refusal. It also discloses side-effect limits ('Received means saved, not fixed', 'No alternate-account or server-key fallback') and a privacy rule ('Omit secrets').

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 cost are front-loaded, but the body is a dense block of policy prose without grouping, and the per-field character limits duplicate the schema's maxLength constraints. Several sentences (rollout, host denial, preference persistence) are individually useful but not separated by topic, making the operative rules hard to scan.

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 nested-object mutation with consent, rollout, rate-limit, and idempotency concerns, the description covers everything the schema and annotations cannot: consent gating, credit cost, quota, retry identity, refusal handling, and PII hygiene. An output schema exists, so return values need not be described.

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 field definitions already carry the load; the description adds genuine semantics on top: generate submission_id once per report and reuse the exact same ID and report on retries, use category missing_capability for feature requests, and missing_capability needs no endpoint/tool/request ID. The character-limit list largely restates schema maxLengths, capping the score below 5.

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

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

Opens with a specific verb and resource ('Submit product feedback') scoped to 'the authenticated Nansen account', and adds the cost model ('Costs zero credits') immediately. The naming and framing make it clearly distinct from the sibling read tools get_feedback and get_feedback_preferences.

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 ('Send when the user requests or approves this report'), prerequisites (call get_feedback_preferences first and check the preference), and when-not-to-use ('If the user refuses or you cannot ask, do not send', 'Never enable it yourself'). It also routes the agent back to the sibling while keeping submission separate.

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

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

The annotations already declare read-only, open-world, non-destructive behavior, and the description adds important operational context: pagination, fallback-to-`holding_size` on unsupported sort combinations, native/stablecoin restrictions, and mode auto-detection. There is no contradiction with the annotations.

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

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

The description is well-structured and front-loaded with purpose and modes, but it is very long. It enumerates all returned columns even though an output schema exists, and includes five full examples, so parts duplicate structured data rather than adding unique guidance.

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 complex modes, filters, restrictions, and the presence of an output schema, the description covers everything an agent needs to select and invoke the tool correctly. Return values are already documented in the output schema, so the main completeness burden is met by the mode, filtering, and limitation guidance.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds real semantic value: mode-specific sort fields, label-type caveats, filter examples, and fallback behavior. However, its examples use snake_case (`token_address`, `label_type`) while the schema uses camelCase (`tokenAddress`, `labelType`), which could confuse literal invocation.

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

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

The description states a specific verb and resource: fetch top holders for a specific token, with an explicit per-page limit and two distinct modes. It clearly separates on-chain-token holder analysis from Hyperliquid perps position analysis, so an agent can identify the tool's purpose 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 mode guidance, including the default `onchain_tokens` behavior and when to use `perps`. It also states when not to use `smart_money` as a market proxy, when to switch label types, and that SOL is unsupported in on-chain mode with `perps` as the alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral fact beyond annotations: perps mode forces chain='hyperliquid' and only ETH is supported natively in onchain mode. It says nothing about pagination behavior, result caps, or data freshness.

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 verb, then a compact bolded Modes block and a short NOTE. Every sentence carries information the agent needs to pick a mode; nothing is redundant.

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?

An output schema exists, so return values need no explanation, and annotations cover safety. The description adequately covers the main ambiguity (mode selection and the native-token caveat), though it omits anything about pagination or how filters interact across modes.

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

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

Schema description coverage is 100%, so the schema already documents mode, chain, side, action, dateRange, valueUsd, and smart-money labels. The description's only additional semantic value is the ETH-only native-token restriction and the mode defaults, which the schema largely restates. 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 and resource ("Get DEX trades for a specific token") and the token-centric scope implicitly distinguishes it from address_dex_trades. It never names a sibling or explicitly routes the agent between address_dex_trades, smart_traders_and_funds_dex_trades, and this tool, so it stops short of full differentiation.

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

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

The Modes block gives concrete when-to-use guidance: contract-address analysis vs. Hyperliquid symbols, with the note that perps mode auto-sets chain to hyperliquid. The NOTE also gives a real selection rule (use perps for native tokens other than ETH). What's missing is guidance on when to choose this over the sibling DEX-trade 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/openWorld/non-destructive, and the description adds substantial non-obvious behavior on top: 25-results-per-page cap out of 1000s of tokens, 5-chain limit with silent trimming, Hyperliquid returning two sections (spot + perps) with a restricted filter set, silent fallback to defaults for unsupported filters, and timeout warnings. These are operational traits the agent could not get from annotations or 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?

It is front-loaded and organized with headers, which helps, but it is bloated with material duplicated from structured fields: the entire Returns/columns list repeats the output schema, and the filter and sort enumerations largely mirror the input schema enums. That repetition dilutes the sections that actually add value.

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

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

For a complex single-object request with many nested filters, Hyperliquid branching, and pagination, the description covers everything an agent needs to call it correctly, including fallback behavior. The only drag is redundancy with the output schema rather than 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?

Schema coverage is already 100%, yet the description still adds real meaning: the explicit warning that priceChange is not a valid filter (use orderBy instead), the distinction between filterable-only fields (tokenAgeDays, outflowFdvRatio) and sortable fields, sparsity warnings for smart-money cohorts, and perps-specific orderBy semantics like funding direction.

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: screening token data across multiple chains with advanced filtering, plus a secondary framing as token discovery / finding trending tokens. This is clearly distinguishable from siblings like token_flows, token_who_bought_sold, or token_ohlcv, but it never names those siblings as alternatives, leaving the agent to infer when the screener wins over them.

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

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

Usage context is explicit and rich: when to use traderType 'sm'/'whale'/'public_figure', when to exclude them, and a direct routing instruction ('use token_who_bought_sold before you report broad Smart Money buying'). The five worked examples show the intended call shapes. It stops short of stating when NOT to use this tool in favor of nansen_score_top_tokens or token_sectors.

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/non-destructive, and the description adds non-obvious behavior on top: mode-dependent chain handling (perps auto-sets chain to hyperliquid) and the native-token fallback, where a native placeholder address silently returns Hyperliquid perp flows with a data-source warning. That quirk would otherwise be a genuine surprise to a caller.

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 scope, then organized under Modes/NOTE headings that are easy to scan. Minor waste: token_recent_flows_summary is referenced three times and the 'more granular ... TOTAL flows over the entire time frame' sentence partly restates the opening and sits in mild tension with 'hourly history'.

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?

An output schema exists, so return values needn't be described, and the single top-level param is a nested request object fully documented in schema. What remains slightly unclear is how the 'hourly' series relates to the 'TOTAL flows over the entire time frame' claim, which an agent may need to resolve empirically.

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

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

Schema description coverage is 100%, so baseline is 3; the description earns above that by adding semantics the schema lacks — that perps mode auto-sets the chain, that native placeholder addresses are rejected in onchain_tokens mode, and the smart_money segment caveat. It stops short of explaining the from/to token vocabulary, which stays with 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?

Opens with a specific verb, resource, scope and granularity: 'Get hourly token-flow history for ONE holder segment over a date range.' It immediately names the sibling it is not (token_recent_flows_summary, which covers ALL wallet categories), 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?

Explicit routing rules: use token_recent_flows_summary for an on-chain snapshot across all categories, use this one for one segment over time. It also states a when-not caveat ('smart_money is not a good proxy for an overall market view; use only if explicitly requested') and mode-selection guidance, which is exactly the when/when-not/alternatives bar.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: the mode-defaulting rule for symbol vs. contract-address input, the fact that both modes reuse the same timeframe parameter, and the markdown return format. The long field catalogs are largely duplicated by the existing output schema, so it stops 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 opening two-mode summary is well front-loaded and the examples are useful, but the two exhaustive field bullet lists also duplicate the output schema and could be dropped without loss. Roughly half the text is redundant reference material rather than decision-relevant guidance.

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

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

For a tool with nested parameters, an output schema, and full annotation coverage, the description supplies what an agent needs to call it correctly: mode choice, input type per mode, timeframe reuse, and example payloads. The one wrinkle is labeling on-chain as the '(default)' mode while the schema explains that a symbol input actually defaults to perps; the schema resolves it but the description phrasing is slightly at odds.

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%, including a mode description that already explains the symbol-to-perps default, so the baseline is 3. The description restates that mapping ('On-chain tokens mode uses contract addresses / Perps mode uses token symbols') and shows example values, which is helpful but adds little the schema does not already state.

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

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

The description opens with a specific verb and resource ('Get token information') and immediately splits it into two named modes, on-chain spot details vs. Hyperliquid perps stats. That is far clearer than the title alone, but it never distinguishes this tool from close siblings such as token_ohlcv, token_current_top_holders, or token_flows, which an agent would have to disambiguate on its own.

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 context for each mode: on-chain mode takes contract addresses and `chain`, perps mode takes symbols like BTC/ETH/HYPE, and both share `timeframe`. Worked JSON examples reinforce which mode to pick. What is missing is any exclusion or comparison against sibling token tools, so the agent gets clear context but no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds the non-obvious chain restriction (Solana only) and clarifies that the data represents forward-looking, not-yet-executed pressure rather than historical fills, which prevents misinterpretation of the results.

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, no filler. The core definition and returned fields come first, followed by the routing guidance and the chain constraint, so the most decision-relevant information 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?

An output schema exists, so return values need no prose elaboration, and the description correctly spends its budget on scope and alternatives instead. The only gaps are minor: no mention of pagination behavior despite a page parameter, and no reference to the sibling smart_traders_and_funds_dcas variant.

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 every nested field — status enum, traderAddress, depositUsdValue range, smart-money labels, page — is documented in the schema itself. The description does not map its field mentions to filterable parameters or explain pagination, so it adds no semantic value beyond the schema, making the baseline 3 correct.

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

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

The description states a specific verb and resource ('Get Jupiter DCA orders opened against a Solana token') and enumerates the returned fields (deposit size, amount spent, amount accumulated, status). It is immediately distinguishable from the adjacent token_dex_trades tool because it explicitly scopes itself to unexecuted, scheduled orders.

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 use case ('see scheduled buying or selling pressure that has not hit the market yet') and names the alternative for the complementary case ('use token_dex_trades for trades already executed'). It also states a hard boundary ('Solana tokens only'), leaving nothing to infer.

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/openWorld/non-destructive), yet the description adds genuinely useful behavior: the full auto-resolution table mapping date range to interval, and the perp-symbol normalization rule. The 'Columns returned' block overlaps with the existing output schema, and it says nothing about row limits/errors beyond the ~100-row hint in the 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?

Front-loaded well with the critical routing warning, but the body is bloated: five near-identical JSON examples where three differ only in the date field, and a column enumeration that restates the output schema. Roughly a third of the text could be cut 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?

For a nested-request tool with auto-resolution, this covers everything an agent needs: supported chains, perp symbol handling, the resolution table, output columns, and worked examples. With an output schema present, return-value explanation is a bonus rather than a gap.

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

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

Schema coverage is 100% but `chain` and `tokenAddress` carry no schema descriptions at all, so the description is the only source of their semantics (EVM/Solana vs. 'hyperliquid', address vs. perp symbol). It also supplies concrete date-token examples ('7D_AGO', '20MIN_AGO', 'NOW') beyond the vague '___-MM-DD' hint, though it never enumerates the accepted chain strings.

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 ('Get OHLCV ... price data for a token') and immediately delimits scope: EVM chains, Solana, and Hyperliquid perps. It also explicitly distinguishes itself from `general_search`, 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?

Explicit when-to-use guidance: 'YOU MUST USE THIS over general_search' with the reason (delayed/incorrect prices there), plus a concrete recipe for latest price (`from='5MIN_AGO'`, `to='NOW'`). It also names the exact condition for the Hyperliquid path (chain='hyperliquid', perp symbol in tokenAddress).

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

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

Beyond the readOnly/openWorld annotations, the description discloses the hard 25-row cap and warns the result is 'NEVER complete', that sort order determines which data you see, that an empty string is returned when no data exists, and the unsupported chains/assets. These are exactly the operational constraints 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?

Headers and examples make it scannable and the critical 25-result caveat is called out, but the sixteen-row column table restates what the output schema already provides and consumes a large share of the text. The size is defensible but not 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 wrapper around a rich nested request object, the description covers modes, limits, sorting, filtering, and failure behavior. The return-value enumeration is redundant given an output schema exists, but nothing essential an agent needs in order to call it correctly is missing, aside from sibling differentiation.

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 earns an extra point by enumerating the sortable fields, grouping filters into list vs numeric-range categories, and providing three worked request examples (including a combined-filter case). It loses a point because the prose filter list is shorter than the actual schema filter set (e.g., boughtAmount/soldAmount/nofBuys are omitted).

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 sentence states a specific resource and scope (trader PnL rankings for a given token, capped at 25 per page), and the two modes are spelled out. However, it never differentiates itself from close siblings such as wallet_pnl_for_token, smart_traders_and_funds_pnl_leaderboard, or hyperliquid_leaderboard, so an agent must infer which leaderboard tool fits.

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

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

It gives clear mode-selection guidance ('onchain_tokens' by contract address vs 'perps' by symbol, chain auto-set to hyperliquid), an explicit native-token exclusion per mode, and a chain exclusion (hyperevm). What is missing is any explicit when-not-to-use or sibling routing, which is the main remaining gap.

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/non-destructive, and the description adds real behavioral context beyond them: per-indicator field semantics, the reward vs risk indicator taxonomy, and the important caveat that not all indicators are available for every token/chain pair. It omits any note on latency, coverage limits, or error behavior for unsupported tokens.

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 is front-loaded and the header-based structure aids scanning, but the long 'Returns' block partially duplicates the existing output schema, and the market cap group definition is repeated verbatim twice. Several lines could be collapsed 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?

Given a single nested parameter object, full schema coverage, and an output schema, the description is complete enough to invoke correctly — it covers scope, expected signals, and availability caveats. The duplicated return-format detail is surplus rather than missing, so the only gap is the absence of alternative-tool routing.

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

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

Schema description coverage is 100% and both the chain and tokenAddress fields are already documented, including the Hyperliquid exclusion, so the schema carries the load. The description contributes adjacent meaning (market cap group thresholds, stablecoin applicability) but adds nothing about parameter usage itself, making baseline 3 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?

Names a specific verb+resource (get Nansen Score Indicators for a token) and states the domain (quantitative risk and reward signals). It is clearly distinguishable from list-oriented siblings such as nansen_score_top_tokens, though it never names a sibling explicitly to sharpen the boundary against token_technical_indicators.

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: assessing risk/reward, evaluating buy/sell decisions, or needing quantitative data for trading decisions. There is no when-not guidance and no pointer to an alternative tool for overlapping signals (e.g., token_technical_indicators), so it stops short of full routing guidance.

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

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

Annotations only say read-only/open-world; the description adds the sign convention (positive = net buying, exchange inflow interpretation), the wallet-overlap caveat that segment flows must not be summed, the markdown output shape, and the Bitcoin exclusion. These are non-obvious behaviors an agent would otherwise get wrong.

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 capability and sibling contrast, with clear section headers. Some repetition (the `token_flows` alternative is stated twice, the Bitcoin exclusion twice) and heavy bolding add noise, but nothing is misleading.

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

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

Despite an output schema already existing, the description supplies the interpretive context needed to use results correctly (segment definitions, sign semantics, aggregation caveat) plus mode and asset coverage. Nothing material is missing for a correct 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%, so baseline is 3; the description goes further by explaining what `mode` actually produces (on-chain cohort flows vs Hyperliquid long/short USD by cohort) and which assets are supported natively (ETH, SOL, but not BTC). It does not add much about `chain` or `lookbackPeriod` beyond what the schema enums already say.

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 (on-chain flow snapshot across all wallet categories) and enumerates the segments returned. It explicitly contrasts itself with the sibling `token_flows`, so an agent can choose 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 explicit routing rules: use this for standard lookbacks such as 1d, use `token_flows` for exact date ranges or hourly breakdowns, and do not use it for Bitcoin. It also clarifies which mode to pick and what each mode returns.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with read-only behavior. The description adds only that it lists 'valid' sectors, implying a controlled vocabulary. It does not contradict annotations but also does not provide significant behavioral detail beyond what annotations already convey.

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

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

The description is a single, succinct sentence that front-loads the verb and resource. There is no fluff, and every word contributes to clarity. It is an example of concise and well-structured tool documentation.

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

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

For a tool with no parameters and an existing output schema, the description is fully sufficient. It explains the tool's purpose, and the output schema provides the return structure. No additional information is needed for an agent to call this tool correctly.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. Per the rubric, a baseline of 4 is appropriate for no parameters. The description does not need to explain parameters and does not attempt to, so it does not detract from the baseline.

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

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

The description clearly states the tool's function: listing valid token sectors for token discovery filters. The verb 'List' and resource 'token sectors' are specific, and the purpose ties directly to token discovery, distinguishing it from sibling tools like token_discovery_screener that likely consume these sectors.

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

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

The description provides clear context that the tool's output is intended for token discovery filters, implying its use case. However, it does not explicitly mention when to use it versus alternatives or when not to use it, and it names no sibling tools. The context is sufficient for an agent to infer usage but lacks explicit exclusions.

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