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

With no annotations provided, the description carries the behavioral burden. It discloses key traits: page size (25), default sort ('net value transferred'), and extra output ('top 3 tokens transferred by count'). It also clarifies that address structure is irrelevant, focusing on relationships. While it doesn't address rate limits or authentication, it provides substantial behavioral context for a read-like analysis tool.

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

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

The description is well-structured with the core behavior front-loaded, followed by a practical note, sorting options, and examples. Though the note section adds length, it earns its place by providing targeted usage guidance. The writing is efficient and free of fluff.

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

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

Given the tool's complexity (nested request object, many sort options, entity/address duality), the description covers key aspects: pagination, default sorting, return contents, examples, and a methodology for related-wallet discovery. The schema provides rich parameter descriptions and an output schema exists, so the description does not need to explain return values. It is complete for practical use, though it could better tie into sibling tools.

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 parameters, establishing a baseline of 3. The description adds value beyond the schema through concrete examples showing valid query structures and a 'Sorting Options' section explaining sortable fields and ASC/DESC support. The note about address structure vs. relationship adds conceptual clarity not present in the schema.

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

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

The description clearly states the tool's function: 'Get 25 (per page) addresses or entities with the most common interactions with input addresses'. It specifies the resource (addresses/entities), the action (get), the pagination, and additional output details ('returns the top 3 tokens transferred by count'). This level of specificity distinguishes it from vaguer siblings like address_related_addresses.

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' section provides actionable context on how to leverage the tool for wallet discovery, including focusing on direct value transfers, including CEX deposit addresses, and going one level deeper. However, it does not explicitly compare against alternatives like address_related_addresses or state when not to use this tool, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses ordering ('newest first'), chain limitations ('one per call... all/evm unsupported'), and special requirements (EVM must pass chain, hyperliquid requires EVM address). It also lists output columns for spot and perp trades. However, it does not mention pagination behavior, rate limits, or error conditions, leaving some behavioral aspects undisclosed.

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 longer than a simple sentence but is well-organized into clear segments: purpose, chain rules, output columns, sorting/filtering, and an example. Every section earns its place given the tool's complexity, though it could be slightly tighter by omitting the column lists since an output schema exists.

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

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

Given the tool's complexity (multi-chain EVM/non-EVM, hyperliquid perps, spot/perps output differences), the description is remarkably complete. It includes a concrete example, explicit chain rules, output columns, and sort/filter options. The presence of an output schema covers return-value details, and the description addresses all other contextual aspects needed for correct use.

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

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

Although the input schema is a single 'request' object with 0% top-level description coverage, the description compensates thoroughly by explaining chain semantics (EVM explicit, non-EVM auto-detected), sort fields ('Sort (order_by, asc/desc): timestamp, value'), and valueUsd filtering. The example demonstrates valid parameter combinations, adding meaning beyond the schema's nested descriptions.

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

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

The description begins with a specific verb and resource: 'Get a wallet's individual trades on a single chain — DEX swaps (spot) or Hyperliquid perpetual trades, newest first.' It also distinguishes itself from sibling token_dex_trades by noting it is wallet-centric while the sibling is token-centric, making its purpose unambiguous.

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

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

Explicit guidance is given on when to use this tool vs the alternative token_dex_trades, plus detailed chain requirements: 'EVM wallets MUST pass chain explicitly... non-EVM is auto-detected' and 'Use hyperliquid for Hyperliquid perpetual trades.' It also instructs to 'Call once per chain to span multiple networks,' providing clear usage 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?

With no annotations, the description carries the full burden of disclosing behavior, but it only states the action. It does not disclose whether balances are aggregated across chains, how the lookback period behaves, or what the response contains (beyond what the output schema may 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 a single, front-loaded sentence with no redundant words. However, it sacrifices useful context for brevity, making it less helpful than it could be without being overly long.

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 a rich nested input schema and an output schema, the description omits key usage context such as the ability to query by entity_id, the default lookback of 1 day, and the distinction from current portfolio tools. This is under-specified for a tool of this complexity.

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

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

The input schema descriptions already cover the parameters (address/entity_id mutual exclusion, lookbackDays, suspiciousFilter) with 100% coverage, so the baseline is 3. The description adds no additional parameter meaning, but it doesn't need to since the schema is informative.

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 the specific verb 'Get' and identifies the resource as 'historical native coin & token balances of address', clearly distinguishing it from sibling tools such as address_portfolio (current) and address_transactions. The scope 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?

No guidance is provided on when to use this tool versus alternatives like address_portfolio or address_transactions. There is no mention of when not to use it, prerequisites, or the address/entity_id dual mode, leaving the agent to infer usage.

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

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

With no annotations provided, the description carries the full burden. It discloses output formatting (pre-formatted markdown vs raw JSON for certain modes), entity-specific behavior, and the inclusion of liquidation prices for risk analysis. It does not mention rate limits or edge cases, but covers the main behavioral traits well.

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

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

The description is long but well-structured with clear sections, mode lists, and code-block examples. Every section earns its place, though some phrasing like '(skip defi, for fast mode only)' is slightly redundant and could be tightened.

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

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

For a complex multi-mode tool, the description covers purpose, mode behaviors, entity limitations, output formatting, and examples for key modes. Missing the 'chain' parameter and not describing the 'wallet_balances' return format are notable gaps, but overall the description is quite complete.

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

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

The description elaborates on modes, walletAddress/entity_id exclusivity, and provides concrete examples. However, it entirely omits the 'chain' parameter and inconsistently uses 'wallet_address' in prose while the schema uses 'walletAddress'. Since schema description coverage is listed as 0%, the description only partially compensates for parameter documentation.

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

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

The description opens with a clear, specific verb and resource: 'Get comprehensive portfolio overview for a wallet address or entity.' It differentiates from sibling tools by covering aggregated portfolio data across modes, while siblings focus on individual transaction, trade, or token metrics.

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 lists distinct modes with explicit scopes (fast-mode-default, all, wallet_balances, defi, hyperliquid) and states that entities only return token balances. It implies when to use this tool via the phrase 'flexible portfolio analysis in a single request,' though it does not explicitly name alternative sibling tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses that only 'special' connections are included and explains the nuance around exchange withdrawals (usually NOT same entity). This is valuable behavioral context beyond what the schema offers, though it stops short of discussing other behavioral aspects like rate limits or pagination.

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

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

The description is moderately sized and front-loaded with the main purpose. The note and caveat are placed appropriately and earn their place. The listing of connection types is a bit long but necessary for clarity.

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

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

Given the tool's moderate complexity, an output schema exists, and no annotations are present, the description covers the key semantic limitations and cross-references an alternative tool. It does not explicitly mention return format or pagination, but the output schema likely handles that. Overall, it is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds meaning beyond the schema by clarifying what 'related addresses' means in this context (e.g., the special connection types), which helps interpret the 'address' parameter. It does not add specific syntax details, but the schema already covers them.

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 information about related addresses of an input address.' It further clarifies the exact types of connections included, which differentiates it from sibling tools like address_counterparties. This makes the tool's purpose unmistakable.

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

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

It explicitly directs users to 'also check address counterparties' for related wallets, naming an alternative tool. It also warns about the interpretation of 'First Funder' connections, providing critical usage context that helps the agent decide when to trust the data.

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?

No annotations are present, so the description carries the full burden. It discloses the 20-per-page limit and date-range filtering ('Only the latest transactions according to the date range are returned'), but omits details about pagination mechanics, spam filtering behavior (hideSpamToken), chain handling, or response structure beyond what the output schema provides.

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

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

The description is two concise sentences with the most important details front-loaded. It communicates the core purpose, pagination, and filtering without unnecessary filler. The minor redundancy between 'MOST RECENT' and 'latest' does not materially detract.

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

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

For a tool with one top-level parameter and an output schema, the description provides an adequate high-level understanding. However, it lacks guidance on the request structure, how to navigate pages beyond 'per page', and important defaults (e.g., date range defaults to last 30 days, chain defaults to 'evm'). It is functional but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It only generically mentions 'address' and 'date range', and hints at pagination via 'per page'. It does not explain the request object, page parameter behavior, chain field, hideSpamToken, or dateRange format.

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

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

Description states a specific action ('Get list of 20 MOST RECENT transactions') and resource ('made by an address'), with pagination scope ('per page'). It clearly identifies the core function, but does not explicitly distinguish it from sibling tools like address_dex_trades which might also return transaction-like 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?

The usage is implied: use when needing recent transactions for an address. There is no explicit when-to-use or when-not-to-use guidance, nor any reference to alternatives. It doesn't clarify whether this tool covers all transaction types or if DEX-specific tools should be preferred for certain cases.

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

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

With no annotations, the description carries the transparency burden. It discloses key limitations (no prediction markets, no NFT support) and output capabilities (price, volume, contract address, market cap, labels, domain resolution). It does not mention rate limits or error behavior, but for a search tool this is strong behavioral context.

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

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

The description is somewhat long, but well-structured with a clear opening directive, explicit exclusions, and a bulleted capability list. It is front-loaded with 'FIRST entry point' and every section earns its place, though a few phrases could be tightened.

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

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

For a broad search entry point with an output schema, the description is contextually complete. It covers supported query types, output information, exclusions, a named sibling alternative, and a caveat about token/NFT name collisions. No critical behavioral information is missing for correct tool selection.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful meaning beyond the schema by clarifying query can include name, symbol, address, or domain, and by emphasizing that chain must be passed via the `chain` parameter rather than in the query string. It also ties `result_type` to the searchable categories.

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

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

The description clearly identifies this as a 'General search tool' and the 'FIRST entry point' for looking up tokens, entities, addresses, and domains. It distinguishes itself from siblings by explicitly excluding prediction markets and noting that NFT support is unavailable, while also clarifying that token/NFT name collisions may occur.

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 explicit when-to-use guidance: use first for any token/entity/address/domain query. It also gives a clear when-not-to-use with a named alternative ('Do NOT use this tool for prediction markets... use `prediction_market_lookup` instead') and practical advice about checking token queries despite NFT unsupported.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states what data is ranked but not how 'growth' is calculated, whether rankings are ascending/descending, if results are limited or paginated, or what the response format is. This is a significant gap for a tool that likely returns ordered data.

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

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

The description is a single sentence that is front-loaded with the action and resource. Every word adds value, and there is no redundancy. It is appropriately concise for a tool with a simple, well-schemaed input.

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 output schema exists, and the input schema covers all parameters, so the description does not need to explain return values or parameter syntax. The description gives the core metrics and scope. However, it omits details like sorting order, but that may be covered by the output schema. Minor gaps prevent a 5.

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

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

Schema description coverage is 100% for both parameters (chain_type and time_frame), so the schema already documents their meaning. The description adds value by listing the ranking metrics but does not elaborate on parameter syntax, defaults, or edge cases. Baseline 3 is appropriate given the high schema coverage.

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

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

The description uses a specific verb ('Get'), names the resource ('chain growth rankings'), and specifies the ranking metrics (active addresses, transactions, gas fees, DEX volume). It clearly distinguishes this tool from sibling tools, none of which focus on chain-level growth rankings.

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 phrase 'Get chain growth rankings' clearly implies when to use the tool. No exclusions or alternatives are mentioned, but no similar sibling exists, so explicit when-not-to-use guidance is unnecessary. The context is clear enough for an agent to select it for chain ranking queries.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return format (markdown), lists columns, and explains sorting/filtering capabilities and default order_by behavior. It doesn't mention pagination, but the overall behavior is well explained.

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

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

The description is structured with clear sections (Returns, Columns, Sorting/Filtering, Example, Notes) and every sentence contributes useful information. It is slightly long but warranted by the tool's complexity, and the main purpose 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?

Given the tool's complexity, the description covers the return format, columns, filtering options, and an example, making it quite complete. Minor gaps like pagination details exist, but overall it provides enough context for effective use.

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

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

The schema has rich descriptions for the single request object, but the tool description adds a concrete example and names the filterable/sortable fields. Since schema coverage is low, the description partially compensates by showing how parameter values are structured, though it doesn't explain every parameter such as 'page'.

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 gets the Hyperliquid perpetual futures trader leaderboard with performance metrics, which is a specific verb+resource. It distinguishes itself from sibling tools by explicitly noting it is Hyperliquid-specific and perp-only, making it clear which tool to choose.

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: it is for Hyperliquid perp leaderboard data and explains sorting/filtering options. It doesn't explicitly name alternative tools for when not to use it, but the 'Hyperliquid-specific endpoint (perpetual futures only)' note gives enough situational 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?

With no annotations, the description carries full behavioral burden. It discloses key behaviors: the pre-filtering threshold 'performance_score >= 15', scoring ranges ('Performance Score (range -60 to +75)', 'Risk Score (range -60 to +80)'), data update cadence ('Data is updated in batches'), dynamic column exclusion, and the instruction to explain thresholds whenever quoting scores. It does not cover rate limits or auth, but for a read-only query tool this is adequate.

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

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

The description is long but well-structured, with clear sections: purpose, usage guidance, alternative comparisons, example queries, scoring explanation, and return format. Every section earns its place given the complexity and the need to differentiate from many sibling tools. It is front-loaded with the core purpose and then provides necessary details.

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 complexity (many sibling tools, scoring thresholds, dynamic output columns) and lack of annotations, the description is quite complete. It explains what the tool does, when to use it, what it returns, and the scoring system. The only missing piece is parameter semantics, but that is partially covered by the schema's description of marketCapGroup. Overall, it provides sufficient context for an agent to select and invoke the tool correctly.

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

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

The description provides zero information about the input parameter. It never mentions 'request' or 'marketCapGroup' even though the schema includes an optional marketCapGroup filter. Schema description coverage is 0%, and the description does not compensate by explaining the parameter. The agent would have to rely entirely on the schema, which is outside the description's contribution.

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: 'Discover and filter a daily list of attractive tokens using Nansen Score Indicators weighted by coefficients (= Performance Score).' It also distinguishes itself from siblings, explicitly saying 'For specific token analysis (e.g., "should I buy AAVE?"), use token_quant_scores instead.' and later contrasts with token_discovery_screener, making the purpose unmistakable.

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

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

The description gives explicit usage guidance: 'Use this tool when you don't know which tokens to buy and need recommendations based on backtested indicators.' It further provides a detailed 'When to use this tool vs token_discovery_screener' section, stating when to use each alternative, and includes example queries like 'what tokens should I buy?'. This is exemplary usage guidance.

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

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

The description adds important behavioral context: blank PnL fields mean unavailable data (not zero), and defines the semantics of 'Position Size (Shares)' vs 'Position Value USD'. It also notes that market-by-market PnL is only provided when the API supports it. Since no annotations are present, this disclosure is valuable for interpreting 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?

The description is concise and well-structured, opening with the core purpose and using bullet points to highlight the most critical field semantics. Every sentence adds value, with no redundant or filler content.

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

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

An output schema exists, and the description provides key field semantics, which partially compensates. However, the lack of usage guidance and parameter explanation makes the description incomplete for confident tool selection and invocation, especially given the many sibling prediction market tools.

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 description does not mention the input parameters (address, page) or the 'request' wrapper at all. Schema description coverage is 0%, so the tool description does not compensate for the schema's complexity. The agent must rely entirely on the schema, which is particularly challenging due to the anyOf union with one generic and one specific branch.

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 'Prediction market PnL breakdown for a Polygon wallet', which clearly identifies the tool's function (providing PnL breakdown), the target resource (prediction markets), and the scope (a specific wallet). This distinguishes it from siblings like prediction_market_address_summary 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 description implies use for a Polygon wallet's PnL breakdown but does not explicitly state when to use it compared to alternatives such as summary or trades tools. No exclusions or alternative tool references are provided, leaving the agent to infer the appropriate context from the name and 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?

No annotations are provided, so the description carries the burden. It discloses that fields are provided 'where the API provides them' and that blank PnL or ROI means unavailable data, not zero. This is useful behavioral context. It does not mention additional traits like pagination or error handling, but for a summary query this is reasonable.

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

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

The description is moderately sized, front-loaded with the core purpose, and uses clear section headers. Every sentence adds value—the when-to-use and key fields sections are directly useful. No wasted words.

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

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

The tool has an output schema and the description covers usage context, key fields, and blank-field semantics. It lacks an explanation of the input request format, but given the output schema and summary nature, it covers most essential context for selection and basic invocation.

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

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

Schema description coverage is 0% (the nested address/page descriptions aren't counted), and the description does not explain the required 'request' parameter structure or the page parameter. It only mentions 'Polygon wallet' which aligns with the address parameter. Since the schema leaves users uncertain about the oneOf structure, the description fails to compensate.

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

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

The description clearly states the tool provides prediction market summary metrics for a Polygon wallet, listing specific fields (volume, win rate, ROI, PnL). It distinguishes from sibling tools by positioning itself as the first wallet-level Polymarket tool, to be used before detailed trades/PnL queries.

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' bullet points state this is the first wallet-level Polymarket tool for quick trader overview, and should be used before detailed address trades/PnL when the user asks for general profile or activity. This clearly directs the agent on use case vs alternatives, though it doesn't list exclusions.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It explains key field semantics ('Share Size is quantity traded...', 'Value USD applies to that row only') and a pitfall (not for profitability), which gives useful behavioral context. It does not mention read-only nature or pagination, but those are implicit and partially covered by 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?

The description is concise and well-structured with bold headers for 'Key fields' and 'Pitfalls.' Every sentence adds value, and it is front-loaded with the main purpose. No waste or redundancy.

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

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

Given the output schema exists and the input schema has some parameter details, the description sufficiently covers the tool's core function and caveats. However, it could explicitly mention that this is address-specific vs. global trades or point to the profitability tool, but it is otherwise complete for a list-style tool.

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

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

The description does not explain the input parameters (address, dateRange, page). Schema description coverage is reported as 0%, so the description must compensate but does not. The 'Key fields' refer to output fields, not parameters, adding no guidance for how to construct requests.

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 'Prediction market trade history for a Polygon wallet,' specifying the resource (prediction market trades) and scope (a specific wallet address). The 'Pitfalls' section adds 'Use this for wallet trade activity, not profitability,' which distinguishes this tool from PnL-focused siblings.

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

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

The description provides explicit usage guidance: 'Use this for wallet trade activity, not profitability.' This tells when to use the tool and when not to, though it does not name alternative tools directly. The context is clear enough for an agent to differentiate.

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?

No annotations are provided, so the description carries full burden. It discloses that results include current outcome prices, last trade price, and bid/ask; explains the event/market hierarchy; and states an explicit output rule about not silently substituting a nearby market. Missing details on pagination and rate limits, but core behavior is well covered.

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

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

The description is long but well-structured with clear headers ('PM building blocks', 'When to use', 'Query tips', 'Output rules'). Each section earns its place and key guidance is front-loaded. Slightly verbose but not wasteful.

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

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

With an output schema present, return values need not be fully described, but the description already hints at output content (prices, bid/ask). It covers matching behavior, event/market distinction, and no-substitution rule. Missing details on pagination and status filtering are minor given the output schema exists.

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 reported as 0%, meaning the description must compensate. It adds meaning for 'queryVariant' ('cleaner short keyword version') and 'includeEventMarkets' ('also return child markets'), and clarifies event vs market, which helps interpret the 'query' parameter. However, it does not mention 'page', 'status', 'maxCandidates', or 'maxEventMarkets', so compensation is incomplete.

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 'Search Polymarket for events and markets by name, topic, URL, or slug.' This is a specific verb+resource+scope. It also distinguishes from siblings by explicitly saying 'Do NOT use general_search for prediction markets' and referencing prediction_market_ohlcv for price history.

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

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

Under 'When to use', it says to use this as the first tool when the user asks about a PM topic/event/slug/URL without a marketId. It provides explicit exclusions ('Do NOT use general_search') and alternatives ('For price history or dated moves, still use prediction_market_ohlcv'). It also gives query tips and output rules.

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?

No annotations are provided, so the description carries the full burden. It discloses key behavior: Close is share price, binary markets are complementary, responses are for one exact marketId only, and if no candles are found, the agent should say so directly rather than estimate. This is rich, non-obvious behavioral context.

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

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

The description is well-organized into 'When to use', 'Key fields', 'Pitfalls', and 'Prerequisites'. Each section is concise and every sentence provides useful guidance. No filler or redundancy.

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

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

With an output schema present, return values are already documented. The description adds necessary context about use cases, pitfalls, and prerequisites. It is complete for an agent to use the tool safely and 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 description mentions marketId and the date window ('requested window') but does not describe page, orderBy, or other parameters. However, the input schema already provides detailed descriptions for all parameters. The description adds some context (e.g., marketId exactness) but does not fully compensate for the low schema description coverage signal.

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

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

The description clearly states it provides 'Historical odds/volume candles for a Polymarket market' and lists specific use cases like current odds, price history, and probability changes. This verb+resource combination distinguishes it from sibling tools like prediction_market_trades or prediction_market_orderbook.

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' section explicitly lists scenarios for this tool. It also gives a prerequisite: call prediction_market_lookup first if marketId is unknown. While it doesn't explicitly name alternative tools as 'do not use this for X', the context is clear enough for an agent to decide.

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

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

With no annotations, the description fully carries the transparency burden. It discloses that Order Size is shares not USD, explains the Yes/No complementary price relationship, and warns against misinterpreting No bid prices—all critical behavioral/interpretive details that go beyond basic tool function.

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 with clear markdown sections (When to use, Key fields, Yes/No price relationship, Pitfalls, Prerequisites). Every section adds essential context, and the information is front-loaded with the core purpose first. It is detailed but not wasteful.

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

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

Given the output schema exists to handle return values, the description covers the essential context: use cases, data interpretation (shares vs USD, Yes/No complementarity), pitfalls, and prerequisite steps. It is comprehensive enough for an agent to correctly select and invoke the tool without ambiguity.

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

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

The schema itself has descriptions for marketId and page, so the parameter structure is somewhat covered. The description adds a useful note about obtaining marketId from prediction_market_lookup but does not explain the 'request' object wrapper or page parameter. Overall, it provides marginal value beyond the schema, but with 0% description coverage, it leaves some gaps.

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 'Live orderbook for a Polymarket market,' clearly stating the tool's function and resource. It also explains when to use it (bid/ask depth, liquidity, yes/no structure), which distinguishes it from siblings like prediction_market_ohlcv and prediction_market_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' section explicitly lists use cases, and the 'Pitfalls' section tells agents to prefer prediction_market_ohlcv for current odds. It also provides a prerequisite: use prediction_market_lookup if marketId is unknown, giving clear guidance on tool selection and setup.

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

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

Despite no annotations, the description discloses important behavioral traits: it explains that 'Side Held' reflects current exposure where available, and it defines what to do when PnL fields are blank (say unavailable, don't substitute). This gives the agent concrete handling instructions, though it could also mention pagination 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?

The description is tightly structured with labeled sections (When to use, Key fields, Pitfalls, Prerequisites). Each sentence serves a purpose, and the main intent is front-loaded in the first line. No filler or repetition, 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 complexity of the request schema and the presence of an output schema, the description adequately covers usage context, prerequisites, and pitfalls. The only notable gap is lack of clarity on the open-object variant of the request parameter, but the prerequisites and field guidance reduce the risk of misuse. Overall, it is reasonably complete for selection and 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 0%, and the description does not explain the 'request' union structure or the 'page' parameter. However, it adds value by telling the agent to call prediction_market_lookup if marketId is unknown, which indirectly guides parameter provisioning. The schema itself contains parameter descriptions for marketId and page, but the description could have clarified the nested request object to fully compensate.

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 'PnL leaderboard for a Polymarket market' with a specific resource and scope. It differentiates from siblings like prediction_market_top_holders and token_pnl_leaderboard by focusing on market-level PnL. The 'When to use' section further narrows the purpose to profitability claims, making it unambiguous.

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

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

The description provides explicit usage guidance: 'Only for profitability claims' and a clear pitfall ('do not substitute top holders or position size'). It also includes a prerequisite directing users to call prediction_market_lookup first if marketId is unknown, which effectively steers the agent to the correct preliminary tool.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It clarifies that Position Value is marked value, not final payout, and that Cost Basis/Unrealized PnL apply only to the displayed row, which is valuable context. It omits auth and rate limits but covers key data semantics.

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

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

The description is concise and well-structured, using bold headers and bullet points. It front-loads the purpose, adds essential field semantics, 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?

The description covers important field semantics and prerequisites, which is helpful. However, it contradicts the schema about where to obtain marketId (lookup vs screener) and does not mention pagination or the request union structure, leaving gaps for a tool with no annotations.

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

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

Schema description coverage is 0%, and the description does not explain the request parameter's union structure or the page parameter. It only mentions marketId in prerequisites, which is insufficient for a low-coverage schema. The description fails to compensate for the missing parameter documentation.

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 'Detailed position breakdown for a Polymarket market' and lists key fields, making the tool's purpose clear. It distinguishes from sibling prediction tools by focusing on position breakdown, though it lacks an explicit verb and could be more direct.

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 specific prerequisite: if marketId is unknown, call prediction_market_lookup first. This gives clear context for when to use this tool. However, it does not contrast against alternative position-related tools such as 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?

Despite no annotations, the description discloses important behavioral traits: literal-style matching (not fuzzy), query tips (avoid bundling unrelated topics), handling of empty results (don't invent matches), and output rules (superlatives must match shown metric exactly). It does not disclose rate limits or auth, but for a data discovery tool, it is thorough and goes beyond basic expectations.

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 longer than a simple sentence but is well-structured with bolded section headers ('When to use', 'Query tips', 'Output rules'). Each section provides actionable information without fluff. It is slightly verbose but earns its place given the tool's nuanced matching and output behavior.

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 moderate complexity (three modes, query semantics, output constraints) and the presence of an output schema (so return values are structured), the description is highly complete. It covers selection criteria, exclusions, query construction, error handling, and output interpretation, enabling an AI agent to use it correctly without additional context.

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

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

The input schema has descriptions for nested properties (mode, page, query, status, orderBy), but the top-level 'request' parameter has no direct description, yielding 0% schema coverage. The description compensates by adding semantic guidance on how to use the query parameter (literal matching, one short topic, no bundling) and how to interpret output (superlatives). This adds value beyond the schema, though it doesn't explicitly enumerate the request structure (which the schema handles).

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

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

The description clearly states the tool's purpose: 'Browse and sort Polymarket markets, events, or categories.' It uses a specific verb (browse/sort), names the resource (Polymarket markets/events/categories), and distinguishes from siblings by explicitly pointing to prediction_market_lookup for resolving a single named market.

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' section explicitly states broad discovery and screening, and provides a clear exclusion: 'Do NOT use this to resolve one named market/event/slug/URL — use prediction_market_lookup instead.' This is exemplary guidance with an alternative tool named.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does an excellent job by detailing key field semantics (positions are share balances, Position Value is marked value not payout), source-of-truth limitations (holder table is source of truth, summary only shown rows), and a pitfall about interpreting smart money. This goes well beyond the schema and gives the agent a strong understanding of data 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 well-structured with bolded section headings ('Key fields', 'Pitfalls', 'Prerequisites'). The main purpose is stated in the first sentence, and every subsequent sentence adds meaningful caveats or context. Though it is longer than a simple one-liner, the complexity of the tool justifies the length, and each sentence earns its place.

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

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

Given that an output schema exists and the input schema has rich parameter descriptions, the description does not need to cover formatting details. It thoroughly explains result interpretation and limitations, which are not otherwise disclosed. However, it omits any guidance on pagination or sorting behavior, though these are present in the schema. Overall, it is highly complete for a data retrieval tool.

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

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

Schema description coverage is 0% from the natural language description, so the description does not compensate for parameter explanations. However, the input schema itself contains detailed descriptions for all nested properties (page, orderBy, marketId, orderByDirection), so the agent still has sufficient information to invoke the tool. The description adds only the prerequisite mention of marketId, which is a minimal bonus.

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

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

The description clearly states the tool returns 'Largest current holders for a Polymarket market.' It is unambiguous about the resource (Polymarket market) and the specific scope (top holders). While the verb is implied rather than explicit, the title and description together leave no doubt, and it distinguishes itself from token-focused holder tools like 'token_current_top_holders' by explicitly naming Polymarket.

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 by including a prerequisites section: 'If marketId is unknown, call prediction_market_lookup first.' It also gives important interpretation cautions (e.g., do not infer risk or smart money without explicit output support). However, it does not explicitly mention alternative tools for similar tasks or state when not to use this tool, so it falls just short of a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses important behavioral details: each row is a visible trade leg, Value USD applies to the row rather than the whole transaction hash, and large visible trades do not necessarily indicate smart money. This goes beyond basic output expectations, though it does not mention pagination limits or rate 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?

The description is well-structured with sections (When to use, Key fields, Pitfalls, Prerequisites) and is front-loaded with a one-sentence summary. Every section provides distinct value without unnecessary fluff, making it easy to scan and act upon.

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, usage context, data interpretation, pitfalls, and a prerequisite – all relevant for an agent to use the tool correctly. An output schema exists, so the description does not need to explain return types. The only minor gap is parameter documentation, but that is already present in the input 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 0%, so the description must compensate for parameter explanations. It only mentions that marketId is required and how to obtain it if unknown, but it does not explain the 'page' or 'dateRange' parameters. The schema itself has descriptions, but the description adds no additional meaning for these parameters, leaving a gap in compensation.

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

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

The description starts with 'Recent trades for a Polymarket market,' which clearly states the tool's function and resource. It further distinguishes itself by calling out 'source of truth for recent fills and latest trade-tape pricing' and explicitly contrasting with OHLCV candles, separating it from sibling tools like prediction_market_ohlcv.

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' section provides explicit guidance: it is the source of truth for recent fills and latest prices, and it warns not to overwrite recent trade prices with older OHLCV candles. It also gives a concrete prerequisite (call prediction_market_lookup if marketId is unknown), which helps the agent decide when to use this tool versus alternatives.

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

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

With no annotations, the description carries full burden. It discloses Hyperliquid-only scope, recent-trades-only limitation, column meanings, sorting possibilities, and examples. However, it doesn't mention pagination behavior, rate limits, or the default page size, leaving minor gaps. Overall, it provides substantial behavioral context beyond annotations.

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

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

The description is well-organized with a lead summary, a note about scope, a clear bulleted list of columns, sorting options, and inline code examples. Every sentence provides useful information without fluff. It front-loads the core purpose and then logically expands.

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

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

Given the tool's complexity (multiple filters, sorting, labels) and an output schema being present, the description covers all necessary aspects: data scope, limitations, column definitions, sorting fields, and examples. The listing of output columns compensates for the lack of an output schema in the provided context. It is a complete guide for a complex tool.

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

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

Although the context signal indicates 0% schema description coverage, the actual schema has rich descriptions on sub-properties. The description adds value by clarifying the default sort behavior ('amount' when not specified), demonstrating example filters, and mentioning case-insensitive sort directions. This goes beyond the schema's raw fields, though it doesn't fully restate all parameter nuances.

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+scope: 'Get recent Hyperliquid perpetual futures trades from Smart Traders and Funds across all tokens.' It clearly distinguishes from the sibling token_discovery_screener by noting this is for granular perp trades while the screener gives a big picture. This is unambiguous and differentiates from siblings.

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

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

Explicitly states when to use this tool versus an alternative: 'For a big picture view of smart traders and funds activity across all tokens, use token_discovery_screener with traderType="sm" filter.' It also notes the Hyperliquid-only scope and the lack of date filtering, providing clear context for suitability.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds valuable context by stating the aggregation level ('aggregated (not per wallet)'), the explicit exclusions (whales, large holders, influencers), the per-chain scope, and the default behavior of querying all chains. This goes beyond a simple 'Get positions' and gives the agent a solid understanding of what to expect, though it does not cover pagination or read-only guarantees.

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 begins with the core action and scope. It efficiently conveys the essential information without extraneous filler. The only minor redundancy is 'per chain for all chains' but it is acceptable for clarity. Overall, it is well-structured and front-loaded.

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

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

Given the tool's moderate complexity (multiple chains, filters, smart money categories) and the presence of an output schema, the description covers the primary purpose and key behavioral nuance (aggregation level, exclusions, default chains). It does not list all filter options, but those are documented in the nested schema. The description provides sufficient context for an agent to decide when and how to invoke the tool.

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

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

The schema description coverage is listed as 0% for the top-level 'request' parameter, and the description adds minimal parameter-level detail. It mentions 'default is ['all']' for chains, but this is already present in the schema's nested descriptions. The phrase 'Use filters' is generic and does not explain the specific filters (e.g., minHolders, includeStablecoin, includeSmartMoneyLabels) or their syntax. The description does not adequately compensate for the low schema coverage.

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

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

The description clearly states a specific action ('Get aggregated token balances and 24h change') with a defined resource ('smart trader and fund' positions), and explicitly distinguishes this tool from per-wallet or other smart-money tools by noting 'not per wallet' and 'EXCLUDES whales, large holders, influencers, etc.' This differentiates it from siblings like address_portfolio and smart_traders_and_funds_perp_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 description implies the tool's use case (aggregated smart money/fund token balances per chain) and includes a generic instruction to 'Use filters to narrow down the results.' However, it does not explicitly state when to choose this tool over alternatives or mention exclusions such as 'use smart_traders_and_funds_perp_trades for perp trades.' The context is clear but only implied.

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

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

With no annotations provided, the description carries full burden and excels: it discloses pagination ('upto 25 per page'), fallback behavior (wrong-mode orderBy falls back to holding_size), unsupported combinations for native tokens falling back to holding_size, and the SOL limitation. It also lists the exact columns returned for both modes, giving full visibility into the output.

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

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

The description is long but highly structured, with headers ('Modes', 'Columns returned', 'Sorting Options', 'Examples', 'Native-token...') that make it scannable. The primary purpose sentence is front-loaded, and every section adds necessary operational detail; no filler.

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

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

Given the tool's complexity (two modes, many columns, sorting restrictions), the description covers all essential context: mode selection, schema, sorting, filters, examples, and known limitations. An output schema exists, but the description still explains return columns and fallbacks, making the tool fully self-contained for an agent.

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

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

Despite a schema coverage of 0%, the description compensates richly: it explains the mode parameter semantics (including the default rule when token_address is a symbol), enumerates valid orderBy values per mode, explains labelType options and their caveats, and provides multiple concrete examples showing parameter combinations (e.g., orderBy, side, upnlUsd, positionValueUsd). This adds meaning far beyond the raw schema.

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

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

The description opens with a clear verb-object statement: 'Get upto 25 (per page) top holders information for a specific token.' It distinguishes from sibling tools by enumerating two distinct modes (onchain_tokens and perps) and detailing column sets, making it unambiguous what this tool does relative to others like token_info or token_flows.

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 includes explicit when-not guidance ('Using labelType smart_money is not a good proxy... use it only if user explicitly requests it'), an explicit alternative for SOL ('Does not work for SOL in onchain_tokens mode... use perps mode instead'), and detailed restrictions with fallback behavior for native tokens. It clearly explains when to use each mode and how to adjust labelType/aggregateByEntity for advanced filters.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It reveals useful behavioral details like the auto-chain-setting for perps and the native token limitation, but does not describe return format, pagination behavior, or error handling. These gaps limit transparency.

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

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

The description is succinct, with a clear one-sentence purpose followed by two concise mode bullets and a critical note. Every sentence earns its place, and the structure is easy to scan with bold headers.

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 moderate complexity and rich schema descriptions, the description covers the core purpose and critical edge cases (native token support). The output schema is present, so return details are not needed in the description. Missing explicit guidance on when to use this versus address_dex_trades is a minor gap.

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

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

The input schema has 100% description coverage for parameters, so the baseline is 3. The description adds the important note about native token support and perps mode, which enriches understanding of the mode parameter, but otherwise relies on the schema for parameter details.

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

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

The description clearly states 'Get DEX trades for a specific token' with a specific verb and resource, and distinguishes between on-chain tokens and perps modes. It also differentiates from sibling tools like address_dex_trades by focusing on token-centric queries.

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 mode guidance, noting that in onchain_tokens mode only ETH is supported for native tokens and that perps mode should be used for other native tokens. However, it does not explicitly compare to sibling tools like address_dex_trades or state when to prefer this tool over them.

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

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

With no annotations, the description carries the full transparency burden and exceeds it: it details the 25-result cap, 5-chain limit, Hyperliquid perps special case (two sections, supported filters), fallback behavior for unsupported filters, timeout risks, and return format (markdown, empty string when no tokens). This gives the agent a rich behavioral model beyond the basic 'screen tokens' idea.

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

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

The description is long, but every major section earns its place: limits, Hyperliquid special case, examples, return columns, filter/sort details, and warnings. It uses headings and bold text for skimmability. A few repetitive examples could be trimmed, but overall it is appropriately sized for the tool's complexity.

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

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

For a high-complexity screener with many filters, chain-specific behavior, output columns, and edge cases, the description is remarkably complete. It covers purpose, parameters, behavior, return schema, and operational warnings, leaving little ambiguity for an agent deciding whether and how to invoke it.

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

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

Schema coverage is effectively 0% for the single 'request' parameter, so the description must compensate—and it does extensively. It lists all numeric range filters, category filters, traderType usage rules ('Use "sm" ONLY when user explicitly asks for "smart money"'), sorting options, defaults, and invalid filter warnings (priceChange). This far exceeds the schema's sparse descriptions.

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

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

The description opens with 'Get comprehensive token screening data across multiple blockchain networks with advanced filtering' and later states 'This tool helps with token discovery and finding trending tokens by combining different metrics.' This clearly specifies the verb, resource, and scope, and distinguishes it from more narrowly-focused siblings like token_ohlcv or token_flows.

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

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

The description provides clear usage context—'helps with token discovery and finding trending tokens'—and includes practical warnings (use ≤4 chains, shorter timeframes to avoid timeouts) and a critical filter-vs-sort warning. However, it does not explicitly name alternative tools or define when not to use this screener, so it stops short of a perfect score.

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

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

No annotations are provided, so the description carries the full burden. It discloses important behavioral traits: the return granularity (hourly), the mode-dependent behavior (perps auto-sets chain to hyperliquid), and the surprising native-token fallback behavior (native placeholder addresses return Hyperliquid perpetual-futures flows with a data-source warning). It also warns about the smart_money segment not being a market proxy. It could add pagination behavior or response shape details, but the key behavioral quirks are covered.

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

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

The description is moderately sized but well-structured with clear sections for modes and a prominent note. It front-loads the core purpose in the first sentence. While the native-token note is long, all content is substantive and earns its place. It loses one point for being somewhat verbose in the final note, but overall it is organized and readable.

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

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

Given the tool's complexity (multiple modes, native-token fallback, holder segment caveats) the description covers the critical decision points well. The output schema is present, so return values don't need to be described. It does not explicitly mention pagination parameters or the default holder_segment, but those are in the schema. The description suffices for correct tool selection and invocation, with minor gaps in clarifying that 'more granular' means hourly versus the sibling's snapshot.

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

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

The input schema covers parameter descriptions extensively (100% coverage per context), so the description doesn't need to repeat them. The description adds semantic value beyond the schema by explaining the total flows over time frame broken down by segment, and by describing the perps mode meaning (Hyperliquid perpetual futures by symbol) and the native-token fallback behavior, which clarifies the tokenAddress parameter's behavior beyond its bare schema entry.

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

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

The description clearly states the tool returns 'hourly token-flow history for ONE holder segment over a date range', identifying the specific verb (get), resource (token-flow history), and scope (one holder segment, date range). It distinguishes itself from sibling token_recent_flows_summary by noting it is 'more granular' and provides 'TOTAL flows over the entire time frame broken down by segment'.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: it says to use token_recent_flows_summary instead for an on-chain snapshot across ALL wallet categories. It also gives a specific warning that holder_segment: smart_money is 'not a good proxy for an overall market view' and should only be used if explicitly requested. The modes section explains when to use perps vs onchain_tokens.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It covers return format (markdown), default mode behavior, field lists for both modes, and input conventions (address vs symbol). It doesn't address error handling or invalid input behavior, but the core behavioral traits are well disclosed.

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 verbose but well structured with clear sections: overview, mode breakdowns, returns, field lists, examples, and notes. The field enumerations and examples earn their place for a dual-mode tool that returns markdown, but it could be tightened without losing 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?

Given the dual-mode complexity and an existing output schema, the description is thorough: mode selection, input formats, output fields, and examples are all covered. It is internally complete, though it misses an opportunity to explicitly position itself against overlapping siblings (e.g., when to use token_ohlcv instead of this tool's perps price data).

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 for the top-level 'request' parameter is 0%, so the description must compensate. It does so strongly by explaining mode semantics, the address-vs-symbol distinction tied to tokenAddress, and by providing concrete JSON examples for both modes. It doesn't explicitly document the 'chain' parameter, but the mode and address nuances more than compensate for the schema gap.

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

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

The description opens with a specific verb+resource: 'Get token information — spot on-chain details or Hyperliquid perpetual futures stats.' It clearly delineates the tool's dual scope and differentiates it from specialized siblings like token_ohlcv, token_dex_trades, and token_flows, which this tool aggregates into a comprehensive info view.

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

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

The description provides clear usage context: on-chain mode (default) for contract addresses and perps mode for symbols, with explicit examples showing when to use each. It lacks explicit exclusions or alternative tool recommendations, so it doesn't quite reach the bar of 'when-not-to-use' guidance.

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

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

No annotations exist, so the description carries full responsibility. It discloses automatic interval resolution rules, supported chains, perp symbol normalization, output columns, market cap behavior, and even the rationale for auto-resolution (keeping responses at ~100 rows). This is deep behavioral transparency with no contradictions.

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

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

Although long, the description is well-structured: purpose statement, support details, usage directive, resolution table, column list, and examples. Every section earns its place for a tool with multiple chains and auto-resolution, and the front-loaded main purpose enables quick understanding.

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 (multi-chain, auto-resolution, market cap fields), and the description covers all critical aspects: what it does, when to use it, how to pass parameters, what output columns to expect, and even a warning about an alternative. The output schema exists, so the documented columns are a bonus. No essential information is missing.

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

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

Schema description coverage is 0% for the top-level 'request' property. The description compensates thoroughly by explaining chain, tokenAddress, date.from/to, includeMarketCap, and providing concrete date token examples ('7D_AGO', 'NOW', '5MIN_AGO'). This adds substantial meaning beyond the minimal 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 uses a specific verb ('Get OHLCV') and resource ('price data for a token'), and clearly distinguishes from sibling `general_search` by stating it must be used over it for prices. The scope (EVM chains, Solana, Hyperliquid perps) is immediately clear.

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

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

Provides explicit when-to-use guidance: 'YOU MUST USE THIS over general_search to get prices' because `general_search` prices are 'delayed and often incorrect'. Also includes specific instructions for Hyperliquid perps and multiple examples covering different chains and date ranges, making the invocation context unmistakable.

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

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

With no annotations provided, the description carries full responsibility and does exceptionally well. It discloses the top-25 limit, empty-string return when no data, markdown return format, unsupported chains (hyperevm), native-token limitations per mode, and the importance of choosing relevant sort order.

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

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

The description is long but well-organized with clear sections for modes, returned columns, sorting, filtering, and examples. Some redundancy exists (e.g., native-token limitations repeated in two places), but each section serves a purpose.

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

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

For a complex tool with many options, the description is remarkably complete. It covers modes, sorting/filtering capabilities, return columns, examples, limitations, and usage notes. The presence of an output schema reduces the need to explain return values, but the description still adds substantial context.

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

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

Schema description coverage is 0%, so the description must compensate. It lists sorting fields, filter categories, and includes examples, but it omits several schema parameters (e.g., boughtAmount, soldAmount, nofBuys) and references names like trader_address_label that do not appear in the schema. This is useful but incomplete and slightly inconsistent.

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

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

The description clearly states it returns 'Upto 25 results (per page) of trader PnL for a token', with explicit modes for onchain tokens and Hyperliquid perps. It distinguishes itself from likely siblings by specifying token-level leaderboard behavior and supported chains.

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 on when to use each mode and encourages the use of sorting/filtering. It does not explicitly name alternatives like hyperliquid_leaderboard or wallet_pnl_for_token, but gives enough guidance to choose between onchain_tokens and perps modes.

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?

No annotations provided, so the description carries the full burden. It discloses the return format (markdown with interpretation guidance), the list of indicators, the note that not all indicators are available for every token/chain, and the market cap group logic. It does not discuss potential side effects or auth requirements, but for a read-only data tool, the disclosed behavior is substantial.

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 usage, then structured with clear sections for returns, indicator types, and notes. It is longer than the minimal example but every section adds value, such as the stablecoin caveat and market cap grouping. It is not overly verbose for the complexity of the tool.

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

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

The description thoroughly covers the output format, indicator categories, and important limitations. It lacks clarity on the request parameter structure, but the schema partially covers that. Given the tool's complexity and the presence of an output schema, the description is largely complete for an agent to invoke the tool correctly, with the main gap being parameter semantics.

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%, meaning the tool description must compensate for explaining parameters. The description does not explain the 'request' object structure or how to specify token/chain. It only mentions 'token/chain combination' in notes. The schema itself has some descriptions for 'chain' and 'tokenAddress', but the outer union parameter is left unexplained. The description adds little beyond what the schema already provides.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Get Nansen Score Indicators for a token - quantitative risk and reward signals.' It distinguishes itself from siblings by focusing on quantitative risk/reward indicators and lists the specific indicator types, making it unique among the other token-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 provides explicit usage context: 'Use this tool when assessing a token's risk/reward profile, evaluating buy/sell decisions, or when the user needs quantitative data to make trading decisions.' It does not name alternative tools or state when not to use it, but the guidance is clear enough for an agent to select it appropriately.

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

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

With no annotations, the description fully carries the burden of behavioral disclosure. It explains the meaning of flow signs ('Positive flow = net buying, negative flow = net selling'), special exchange flow semantics, aggregation over lookback periods, and the distinction between onchain_tokens and perps modes. This gives a comprehensive behavioral picture beyond just input/output.

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 with clear sections, bullets, and notes, making it easy to scan. It front-loads the core purpose and then covers details systematically. There is slight redundancy (token_flows alternative mentioned twice), preventing a perfect score, but every sentence is informative and earns its place for a tool with multiple modes.

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

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

Given the tool's complexity (two modes, multiple wallet categories, unsupported assets, sign conventions), the description thoroughly covers all necessary aspects. It explains output format, segment categories, lookback behavior, and warns about Bitcoin. The presence of an output schema and the detailed description together provide complete contextual understanding for an agent to invoke this tool correctly.

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

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

Although the schema contains descriptions for mode, chain, and lookbackPeriod, the description adds crucial context: it explains that values are aggregated over the lookback period, introduces the two modes, and clarifies that native ETH and SOL are supported (while BTC is not). The description also notes that perps mode returns position intelligence, which is not obvious from the schema's enum. This adds meaningful 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 clearly states the tool's purpose: 'Get an on-chain flow snapshot across ALL wallet categories in one call.' It specifies a concrete verb and resource, and differentiates itself from sibling tool token_flows by noting it is 'the correct choice for standard lookbacks such as 1d.' This distinguishes it clearly from other flow- or transfer-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?

Usage guidance is explicit and actionable. The description states when to use this tool ('standard lookbacks such as 1d') and when to use alternatives: 'If you have SPECIFIC date ranges in mind, use token_flows instead.' It also includes a strong exclusion: 'Bitcoin is not supported. DO NOT use this tool for bitcoin.' This provides clear decision boundaries against siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels. It discloses the computation window (last 260 closed candles), how insufficient history is handled ('Indicators without enough closed-candle history render as n/a'), that candle count is always reported, and that VWAP is n/a on Hyperliquid 5m-1h due to NULL volume. It also previews the output structure (snapshot header plus indicator rows with trend deltas). No annotation contradictions exist.

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

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

The description is long but information-dense, with clear section separation (Supports, You-must-use, Timeframes, Output, n/a notes, Examples). Every sentence contributes meaningful operational detail; there is no fluff or repetition. The front-loaded purpose sentence immediately orients the agent, and the structured format makes the extended content easy to parse.

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

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

Given the tool's complexity (7 indicator families, 7 timeframes, 3 chain types, perp naming variants, edge cases), the description is remarkably complete. It covers input semantics, output shape, limitations, and usage rationale. An output schema exists, so return values don't need schema-level explanation, but the description still provides a high-level output preview. This is a model example of contextual completeness for a data-analysis tool.

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

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

Schema description coverage is 0%, so the description must compensate for the single 'request' wrapper with no inline documentation. It does so comprehensively: it explains every nested parameter (chain, tokenAddress, timeframe), gives valid values (timeframe enum, chain examples), shows Hyperliquid perp symbol conventions ('BTC', 'HYPE', 'XYZ:ORDI'), and includes two concrete JSON examples. This fully covers the semantics that the schema lacks.

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

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

The description opens with a specific verb+resource+scope: 'Get a technical-analysis snapshot for a token' followed by an exhaustive list of indicators (SMA, EMA, RSI, MACD, Bollinger, ATR, VWAP) and the data window (260 closed candles). It clearly distinguishes itself from siblings like token_ohlcv by explicitly stating it computes indicators rather than returning raw candles, and it explains its multi-chain support (EVM, Solana, Hyperliquid). This is far beyond a vague or tautological statement.

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

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

The description gives explicit when-to-use guidance: 'YOU MUST USE THIS for technical analysis instead of computing indicators from raw token_ohlcv candles' with rationale (more history, charting-platform conventions). It also provides timeframe selection guidance (5m/15m/30m/1h for intraday, 1d for swing, 1w for long-term) and warns when VWAP is unavailable (Hyperliquid 5m-1h). It names the alternative tool (token_ohlcv) and explains why this tool is preferred, fully satisfying the usage-guidelines criterion.

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?

Without annotations, the description carries full disclosure burden and does reveal pagination, unsupported native tokens, column details, and smart money semantics. However, it makes a significant contradictory claim: 'Default is most recent transfers first' while the input schema says orderBy default is 'amount' (with DESC direction), implying largest transfers first. This misleads the agent about default behavior and is a notable transparency failure.

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

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

Despite its length, the description is exceptionally well-structured with headers, bold labels, code blocks, and examples. Every section (columns, sorting, examples, filters, notes) adds value and is front-loaded with the core purpose. The length is justified by the tool's complexity.

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

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

The description covers almost all necessary context: scope, unsupported tokens, return columns, sorting, filter options with examples, and usage notes. Gaps include no explicit pagination instructions (e.g., how to get page 2) and the inconsistent default sort claim. Given the availability of an output schema, the overall completeness is still high for a tool of this complexity.

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

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

The description adds rich semantics for most parameters: fromAddress/toAddress types and examples, transferOriginCategories possible values and examples, onlySmartTradersAndFunds meaning, transferValueUsd range format, and sorting options. However, it does not explain the 'page' parameter (only mentions per page) and the orderBy default mismatch weakens the semantics. Since schema coverage is 0% per context, the description is close to fully compensating but has these gaps.

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

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

The description starts with a specific verb and resource: 'Get 25 token transfers (per page) for a specific token based on the sort order.' This clearly distinguishes it from sibling tools like token_dex_trades or token_flows by focusing on all token transfers per token, with pagination and sort order.

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 extensive usage context with examples and explicit guidance for filters: 'Use fromAddress/toAddress when looking for a specific wallet's transfers,' 'Use transferOriginCategories to control which transfer origins are included,' and explains smart money and USD value filters. It does not explicitly name alternative tools or when-not-to-use conditions, but the available filter guidance is strong.

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

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

The description discloses return behavior (empty string if no data, markdown format, columns) and notes about aggregation, but contains a misleading claim: it says sorting by 'bought_volume_usd or sold_volume_usd' is possible, while the schema's orderBy description states 'USD volume fields are disabled.' This contradiction could lead to incorrect invocation. With no annotations to provide safety/deletion context, the description carries full burden and fails on accuracy.

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 with explicit sections for Returns, Columns, Sorting Options, and Notes. It is detailed but stays focused, with no wasted sentences. Slightly long but justified by the information provided.

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

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

For a tool with a nested request object and many parameters, the description omits essential invocation details: how to structure the request, required fields (chain, tokenAddress), and available filters. The sorting contradiction further reduces confidence. The return columns are well documented, so it is not entirely incomplete, but major usage gaps 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?

The description explains buy_or_sell semantics (net buyers/sellers) and mentions sorting, but omits critical required parameters like chain and tokenAddress, and does not explain the request wrapper or time_range/include_labels filters. Schema description coverage is 0% at top level, so the description must compensate, but it only partially does and inaccurately for sorting.

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

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

The description clearly states the tool's function: 'Get TOTAL amount of tokens bought/sold by address for a token on DEX' and explicitly says it identifies WHO is buying/selling. It uses specific verb+resource and differentiates from siblings by emphasizing DEX-only aggregated activity.

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

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

It provides clear context for when to use the tool: 'Use this tool to find out WHO is buying or selling a token' and further suggests checking if they are liquidating or accumulating. However, it does not name alternatives or explicitly state when not to use it.

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

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

With no annotations, the description must disclose behavioral traits, but it only says 'comprehensive transaction details including token transfers.' It does not explain what 'comprehensive' covers (e.g., logs, internal transactions, events), whether chain filtering is applied, or any side effects or limitations.

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

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

The description is a single sentence, front-loaded with the core action and resource, and contains no unnecessary words or repetition.

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

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

Although an output schema exists, the description is too sparse for a tool with no annotations and no param explanations. It lacks usage context, parameter clarification, and behavior disclosure, making it inadequate for reliable tool selection and invocation.

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

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

Schema description coverage is 0%. The description does not explain the 'chain' parameter, its default value, or the format/meaning of 'transaction_hash'. The only added hint is that token transfers are included, which is output-oriented, not parameter semantics.

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 ('Get') and resource ('transaction details'), and adds 'including token transfers' to clarify scope. While it doesn't explicitly differentiate from sibling tools like address_transactions or token_transfers, the reference to a transaction hash makes the purpose reasonably distinct.

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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of when a transaction lookup is appropriate compared to address-level or token-level tools, nor any conditions or prerequisites.

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?

No annotations are provided, so the description bears the full burden. The word 'Get' implies a read-only operation, which is useful, and the description adds date-range scoping. However, it does not disclose any other behavioral traits such as whether the token address must be exact, whether the chain parameter can be overridden, or any data latency/rate limits. Given the absence of annotations, a bit more transparency would be expected, but the core read-only and time-bound nature is conveyed.

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

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

The description is two sentences, front-loaded with the core function, and contains no wasted words. It is appropriately concise for the tool's simplicity.

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

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

The tool has an output schema, so return values are covered. The description provides enough context to select the tool, but given the complexity of the request schema (union type, required showRealized), a slightly more complete description would help an agent construct a valid request. Still, the schema provides the necessary details, so the description is minimally complete.

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

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

The schema has descriptions for several properties (walletAddress, tokenAddress, dateRange, showRealized), but the tool description itself does not explain any parameter semantics. The description mentions 'specific token', 'input address', and 'date range' in prose, but it fails to mention the required showRealized parameter or the flexible 'request' wrapper. With schema description coverage indicated as 0%, the description should compensate, and it does not.

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

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

The description clearly states the tool's function: 'Get PnL stats for a specific token traded by the input address during a specific date range.' It uses a specific verb ('Get'), names the resource ('PnL stats for a specific token'), and includes scope ('by the input address', 'during a specific date range'). This clearly distinguishes it from sibling tools like wallet_pnl_summary, which would cover the whole wallet.

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

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

The second sentence provides direct usage guidance: 'Use this tool for analysing the performance of the wallet for the specific token over a time period.' This clarifies the intended scenario and implicitly contrasts with wallet_pnl_summary, but it does not explicitly mention alternative tools or when not to use it.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It provides meaningful context: for Hyperliquid it includes realized PnL plus an unrealized snapshot; for 'all'/'evm' it reports separate sections and never sums; for a named chain it covers realized PnL only. This is more transparent than typical tool descriptions, though it does not discuss auth, rate limits, or response format (output schema exists).

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

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

The description is moderately sized but every sentence adds useful behavioral nuance. It is front-loaded with the core purpose and then elaborates on chain-specific behaviors. No filler or redundancy.

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

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

For a read-only wallet analysis tool with an output schema, the description covers the important edge cases and limitations (chain-specific behavior, no summing, realized vs unrealized). It is not overly complex, and the output schema handles return-value documentation. A complete agent instruction would benefit from a note on response structure, but that is already covered structurally.

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 should compensate, and it partially does by explaining chain-value behaviors (e.g., 'hyperliquid' includes realized + unrealized; 'all'/'evm' splits sections). It also implies the date-range parameter ('over a time period'). However, it does not explain the wrapper 'request' parameter or its flattening, and the schema already provides detailed property descriptions, limiting the added value.

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 aggregate stats of overall realized PnL for the input address.' It clearly identifies the tool's scope (wallet-level aggregate PnL) and distinguishes it from siblings like wallet_pnl_for_token (token-specific) and prediction_market_address_pnl (prediction-market-specific). The chain-specific behavior further clarifies its purpose.

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

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

The description explicitly states when to use it: 'Use this tool for analysing the performance of the wallet over a time period.' It also includes important chain-specific context (e.g., Hyperliquid perp vs EVM vs named chain) and notes a limitation ('covers realized PnL only' for a single named chain). It does not explicitly name alternatives or when not to use them, so a 5 is not warranted.

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