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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral context by specifying the tool returns aggregated network-level analytics (not raw data) and by naming the covered metric families: block cadence, fees, SegWit/Taproot adoption, and activity metrics. It does not disclose cost/rate-limit behavior, but with annotations and output schema present this is sufficient.

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 headings and is front-loaded with the core one-line summary. The WHEN TO USE and DON'T USE sections are useful. However, COMMON USER ASKS and FIRST CHOICE FOR largely repeat the WHEN TO USE content, so not every section earns its place; still compact overall.

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 9-parameter tool with zero required params, output schema, and read-only annotations, the description is nearly complete: it gives a common ask, a concrete example, selection criteria, and an explicit don't-use rule. The only small gaps are the unexplained mode parameter and the lack of a named sibling tool for raw transactions, but those are minor against the schema's coverage.

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

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

Schema description coverage is 100%, so the baseline is 3; the description's example {'network':'bitcoin-mainnet','timeframe':'1h'} demonstrates a valid minimal invocation and adds a little beyond the schema. However, it does not clarify the meaning of mode ('fast' vs 'deep'), whose schema description is a placeholder, so the description doesn't fully compensate where schema help is weakest.

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

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

Description opens with a clear verb+resource: 'Get the big picture for Bitcoin block, fee, and address activity over a recent or explicit window.' This explicitly names the domain (Bitcoin analytics, not raw transactions) and the object (block/fee/address activity), and the WHEN TO USE section further specifies metrics like block cadence, SegWit/Taproot adoption. This sufficiently differentiates it from sibling raw-transaction tools such as portal_bitcoin_query_transactions.

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

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

The description has dedicated WHEN TO USE and DON'T USE sections, making selection criteria explicit. It lists four when-to-use cases (network snapshot, block cadence/fees/adoption/activity metrics) and an explicit exclusion: 'You need raw transactions rather than network analytics,' which routes away from the transaction-querying sibling. This is more than clear context; it gives direct routing guidance.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context by mentioning raw transaction records, optional inline inputs/outputs, and the UTXO envelope, which informs the agent about the response shape without relying solely on 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 well-organized with clear section labels and immediately front-loads the main purpose. Some redundancy exists between COMMON USER ASKS and EXAMPLES, but overall it remains concise and scannable.

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

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

For a 12-parameter read-only query tool with full schema descriptions and an output schema, the description covers the key use cases, exclusions, and example invocations. It does not discuss cursor pagination or all time-filter options, but those are documented in the schema, so the description remains sufficient.

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

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

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds value through examples combining network, timeframe, limit, include_inputs, and include_outputs, but it does not go beyond what the schema already documents for other parameters.

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

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

The description clearly states the tool's function: 'Query raw Bitcoin transactions' with optional inline inputs and outputs. It distinguishes itself from sibling tools by specifying Bitcoin network raw transaction records and the UTXO envelope, 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 WHEN TO USE and DON'T USE sections give explicit guidance on when to use the tool versus when to avoid it, such as for wallet/network summaries. It does not name specific sibling tools, but points clearly toward the relevant alternative use 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'ADVANCED' warning and clarifies that this returns raw order-action events rather than fills/analytics, but it does not disclose additional behavioral traits such as rate limits, data freshness, or pagination behavior. This is adequate but not rich.

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

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

The description is well-structured with headers, a common user ask, when/don't-use guidance, and one concrete example. Every section adds value and the most important routing information is front-loaded. There is no wasted text.

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

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

For a 13-parameter tool with no required parameters, the schema carries the full parameter documentation and an output schema exists. The description adds enough context for tool selection and a working example for invocation. It could have elaborated more on cursor/time-filter interaction, but that is a minor gap given the schema's completeness.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters. The description's example shows a reasonable combination of network, timeframe, and limit, but it does not add parameter semantics beyond what the schema provides. Baseline 3 is appropriate here.

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

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

The description opens with a specific verb and resource: 'Query Hyperliquid replica-command actions such as orders, cancels, and leverage updates.' It also explicitly contrasts itself with fills and analytics, so an agent can distinguish it from sibling tools like portal_hyperliquid_query_fills without opening their schemas.

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

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

The 'WHEN TO USE' and 'DON'T USE' sections give clear routing: use it when debugging replica-command records or needing raw order-action events; avoid it when public trading activity or fills/analytics are the better fit. This is explicit, practical guidance that names the alternative categories.

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

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

Annotations already declare readOnly=true and destructive=false, low'ering the bar. The description adds useful behavioral context: it is an ADVANCED debugging tool, queries raw block records, and covers multiple chains. It also clarifies the result is block records rather than transaction-level or summmary data, which is behavioral and return-type information beyond the annotations.

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

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

The description is organized into labeled sections, front-loaded with the ADVANCED warning and core purpose. Common asks, when-to-use, don't-use, and examples each earn their place without fluf. It is longer than average but structured so an agent can scan 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 11 parameters, zero required, 100% schema coverage, and an output schema, the description supplies the missing selection-level context: when to choose this debugging tool over all siblings, what raw blocks are, and how to build a typical query. An agent has enough to select and invoke it correctly.

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

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

Schema description coverage is 100%, so parameter semantics are already well documented. The description adds an example ('Recent Base blocks: {"network":"base-mainnet","timeframe":"1h","limit":5}') that demonstrates how typical parameters combine, and it names the three block-chain contexts. This is meaningful added value above the schema, though it does not need to restate every parameter.

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

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

The description clearly states the tool's action and resource: 'Query raw block records directly for EVM, Solana, or Bitcoin.' It differentiates from sibling tools by emphasizing raw block records rather than transactions, logs, or summaries, which is a meaningful distinction. The title 'Inspect raw blocks' reinforces this without ambiguity.

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?

WHEN TO USE and DON'T USE sections provide explicit guidance. It says to use when debugging Portal coverage or block-level fields and to avoid when answering normal end-user questions, routing the agent toward recent activity, time series, or raw transaction tools instead. This is exemplary alternative-selection guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful behavioral context: it resolves to the 'nearest indexed block or slot' and can help inspect 'exact versus estimated' resolution, which goes beyond the structured annotations.

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

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

The description is well-structured with labeled sections for common uses, when to use, when not to use, and examples. The purpose is front-loaded in the first sentence, and every section contributes actionable guidance without filler.

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

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

For a two-parameter tool with a 100% described schema, annotations, and an output schema, the description provides complete enough guidance. It explains when to use the tool, when to avoid it, and includes concrete call examples that an agent can immediately adapt.

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

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

Schema description coverage is 100%, so parameters are already documented. The description still adds value with concrete examples mapping 'base-mainnet' and 'polkadot' to the network parameter and showing both relative ('1h ago') and ISO timestamp formats.

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

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

The first line states a specific operation: 'Resolve a timestamp to the nearest indexed block or slot.' This clearly distinguishes the tool from sibling query tools such as portal_debug_query_blocks or portal_get_time_series. Examples for Base and Polkadot reinforce the exact scope.

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

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

The description provides explicit WHEN TO USE and DON'T USE sections, which is strong guidance. It tells the agent not to use this for simple time-based queries because 'most public tools already accept natural timestamps directly,' but it does not name a specific sibling tool as the recommended alternative.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the description only needs to add behavioral expectations. It does: 'ranked contracts', 'compact overview metrics', and 'analytics-style network overview instead of a raw record list' tell the agent what kind of aggregated output to expect. No contradiction with annotations.

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

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

The content is organized into scannable sections and front-loaded with the core summary. It loses a point because 'big picture' is repeated across the summary, FIRST CHOICE FOR, and WHEN TO USE, and the COMMON USER ASKS/FIRST CHOICE sections overlap.

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

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

With 100% schema coverage, an output schema, zero required parameters, and read-only annotations, the only missing context is when to choose this tool and what a call looks like—both provided. The example plus exclusions make it complete for an agent to select and invoke.

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

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

Schema description coverage is 100%, so the schemas carry parameter definitions. The description adds value by giving a complete worked example ('Top contracts on Base: network=base-mainnet, timeframe=1h, limit=10') that demonstrates short network names and natural timeframes, which is extra usage 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 one-line summary names a specific resource ('network-wide EVM activity'), a specific artifact ('ranked contracts and compact overview metrics'), and an explicit contrast with 'raw record list'. This clearly separates it from transaction/query/log siblings like portal_evm_query_transactions and from other chains' analytics 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 WHEN TO USE section lists concrete conditions, and the DON'T USE section gives an explicit exclusion for chart-bucket/time-series requests. It doesn't name a specific sibling alternative (e.g., portal_get_time_series or portal_evm_get_ohlc), so it stops just short of the strongest possible guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds value beyond that by disclosing the tool's aggregate behavior: it returns a summary with unique callers, interaction volume, and optional event activity rather than raw records. This sets accurate expectations about output shape and analytic nature. No contradiction with annotations.

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

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

The definition uses a clear lead sentence followed by scannable labeled sections (COMMON USER ASKS, FIRST CHOICE FOR, WHEN TO USE, DON'T USE, EXAMPLES), with the core purpose front-loaded. It is longer than minimal, and COMMON USER ASKS partially overlaps with FIRST CHOICE FOR, but each section earns its place by making routing and invocation faster for the agent.

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 7 parameters, an output schema, and rich annotations, the description is thorough: it covers intended use cases, exclusions, and provides a concrete example with the required parameters. The main gaps are tool-level context about mode semantics (fast vs deep) and timeframe block-count behavior, but these are already documented in the parameter schema descriptions, so the description need not repeat them.

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

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

Schema description coverage is 100%, so the schema carries the parameter documentation burden. The description's example call {'network':'base-mainnet','contract_address':'0xabc...','timeframe':'24h'} reinforces realistic usage and that timeframe accepts formats like '24h' (already documented in the schema). It also maps 'optional event activity' to include_events. This is marginal added value on top of complete schema descriptions, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Summarize what one specific contract has been doing lately, including recent interactions, unique callers, and optional event activity.' It names the unit of analysis (one specific contract) and what distinguishes it from siblings (a contract-level summary, not raw records). The DON'T USE section explicitly steers away from raw logs and transactions, which differentiates it from portal_evm_query_logs and portal_evm_query_transactions.

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

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

The WHEN TO USE section lists three concrete conditions (contract-level answer, contract-centric summary instead of raw records, top callers and interaction volume) and the DON'T USE section lists two exclusions (raw logs/transactions, general network activity without a specific contract). These conditions map cleanly onto sibling alternatives: query_logs/query_transactions for raw records and get_recent_activity for general network activity. The guidance is explicit and decision-ready.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: the search is bounded to a window, it returns the create trace and parent transaction, and it notes that old contracts without a block/time hint are not suitable. This is useful context without contradicting the annotations.

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

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

The description is longer than average but is well-structured into clear sections (COMMON USER ASKS, FIRST CHOICE FOR, WHEN TO USE, DON'T USE, EXAMPLES) and front-loads the core purpose in the first sentence. Some redundancy exists between 'COMMON USER ASKS' and 'FIRST CHOICE FOR,' so it is not maximally concise, but every section contributes useful guidance.

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

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

Given the tool's complexity (11 parameters, multiple ways to specify the contract/range), the description is complete: it covers use cases, exclusions, parameter semantics, examples, and the critical constraint about providing block/time hints for older contracts. The output schema exists, so not describing return values is acceptable. An agent can correctly select and invoke this tool with the information provided.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds real value above the schema by explaining parameter relationships and usage patterns, such as using from_block for older contracts, search_depth_blocks when no explicit range is given, and contract aliases like 'bored apes'. The three examples illustrate valid, concrete parameter combinations that the schema alone does not convey.

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: 'Locate the create trace and parent transaction that deployed a specific EVM contract address within a bounded window.' This clearly distinguishes it from sibling tools like contract activity or transaction queries, and the 'DON'T USE' section reinforces that it is for deployment lookup rather than general 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?

The 'WHEN TO USE' and 'DON'T USE' sections give explicit conditions and exclusions, such as not using it for all post-deployment activity and requiring from_block/from_timestamp for older contracts. It clearly describes the deployment-lookup use case but does not name a specific sibling alternative (e.g., portal_evm_get_contract_activity) by tool name, so it falls just short of fully explicit alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral context beyond annotations: it explains the output includes both OHLC candles and a trade tape, that prices come from event-derived sources, and that v4 candles are built from PoolManager Swap events. This goes beyond simple read-only labeling without being exhaustive.

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

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

The description is longer than average, but it is well-organized into labeled sections and front-loaded with the core purpose. The COMMON USER ASKS and EXAMPLES are somewhat redundant with the parameter list and source enum, but they serve as practical invocation templates and are not 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?

For a tool with 24 parameters, 5 enums, an output schema, and a broad sibling family, this description is highly complete. It covers supported sources, usage boundaries, common wording variants, and concrete JSON examples. Nothing an agent needs to decide whether and how to call this tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 24 parameters. The description's examples demonstrate realistic parameter combinations, but the prose does not add new semantic meaning beyond the schema. This meets the baseline of 3 without exceeding it.

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

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

The description states a specific action ('Build chart-ready EVM OHLC candles plus a recent trade tape') and names the exact event sources it supports (Uniswap v2/v3/v4, Aerodrome Slipstream). It clearly differentiates this tool from siblings like portal_hyperliquid_get_ohlc and portal_get_time_series by specifying EVM DEX-derived candle 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 description includes explicit WHEN TO USE and DON'T USE sections, along with concrete COMMON USER ASKS and EXAMPLES. It tells the agent when candle charts are appropriate and when to avoid this tool in favor of scalar metrics or simple activity charts, giving clear decision criteria.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds meaningful behavioral context not carried by annotations: performance caveats for ranges >10k blocks, sparse scan defaults of 25,000 blocks to respect MCP timeouts, context-size effects of field_preset='minimal', and response_format defaulting to 'compact'. No contradiction with annotations.

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

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

The description is long but well-organized with clear headers (COMMON USER ASKS, FIRST CHOICE FOR, WHEN TO USE, DON'T USE, EXAMPLES) and a front-loaded summary sentence. There is some overlap between FIRST CHOICE FOR and WHEN TO USE, but each section contributes distinct selection or invocation guidance, earning its place.

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

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

For a 25-parameter tool with 0 required parameters and an existing output schema, the description covers selection criteria, alternatives, examples, performance caveats, pagination/context usage hints, and decode behavior. The description plus schema and output schema leave no significant gap an agent needs 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?

Schema coverage is 100%, so the baseline is 3, but the description adds concrete parameter combinations in EXAMPLES (scan_order='latest', limit=1, decode=true, include_transaction=true) and explains non-obvious behavior for max_scan_blocks, field_preset, and response_format that supplements the schema descriptions. This exceeds the baseline.

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

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

The description opens with a specific verb+resource: 'Query raw EVM logs with address/topic filters, common event aliases, earliest/latest scanning, and optional inline decoding.' It clearly differentiates from siblings by explicitly stating token transfers are better handled by the token-transfer tool.

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?

WHEN TO USE lists five concrete conditions (filtered event logs, decoded log hints, first/last matching event, common event names, latest ERC721/pass mints). DON'T USE names the exact alternative tool (token-transfer) and the condition that should route an agent away, making selection unambiguous.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by framing this as the fastest/easiest raw transfer query, supporting earliest/latest scan order for 'first matching transfer' questions, and hiding the Transfer topic-hash burden.

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 substantial but tightly organized under COMMON USER ASKS, WHEN TO USE, DON'T USE, and EXAMPLES. The core statement is front-loaded, and every section earns its place; the examples replace lengthy explanations with exact invocations.

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 15-parameter tool with full schema coverage, readable annotations, and an output schema, this description supplies the missing operational understanding: when to prefer it, when to avoid it, and exactly how to invoke it with realistic examples. Nothing an agent needs to correctly select and call the tool 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?

With 100% schema coverage, the baseline is 3, and the schema already documents all 15 parameters. The description meaningfully adds on top by showing concrete payload examples that combine network, timeframe, token_symbols, limit, and scan_order for 'Recent USDC transfers' and 'First recent USDC transfer'.

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 ('Query token-transfer activity on EVM') and immediately distinguishes the tool by removing the need to know Transfer event signatures. The common asks and the DON'T USE section clearly separate it from the sibling log-querying tools, so an agent knows exactly what this tool is for.

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

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

A dedicated WHEN TO USE list provides concrete decision conditions, such as 'did USDC move?' and tracing suspicious/stolen/bridged movement. The DON'T USE section explicitly routes 'arbitrary event logs beyond token transfers' to the logs tool, giving unambiguous guidance on when not to choose this tool.

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

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

Annotations already declare read-only, open-world, non-destructive behavior, so the description does not need to repeat that. It adds useful behavior context beyond annotations: client-side filtering/scanning behavior ('Applied client-side while streaming Portal results'), aggregation that returns ranked address rows instead of raw transactions, token-list resolution, and field presets that shrink response size.

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 tightly structured with COMMON USER ASKS, WHEN TO USE, DON'T USE, and EXAMPLES, and the core action is stated in the first sentence. For a tool with 35 parameters, the length is justified; no section is 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 representative use cases, important parameter interactions, response-size tradeoffs, and exclusions, and it is backed by an output schema for return-value details. An agent has enough context to choose this tool and construct a valid first query.

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

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

With 100% schema description coverage, the schema already documents every parameter, so the baseline is 3. The description adds value by demonstrating parameter combinations in examples (e.g., transaction_type + scan_order + from_block for 'first typed TX' and aggregate_by + aggregate_metric for top senders) and explaining method aliases and token symbols, which are non-obvious 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 first line names a specific verb and resource ('Query raw EVM transactions') and immediately scopes the tool to transaction-level investigations with optional logs, traces, and state-diff context. The WHEN TO USE/DON'T USE sections distinguish it from convenience tools like recent-activity feeds, so an agent can tell it apart 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?

Explicit 'WHEN TO USE' bullets list concrete triggers (raw fields, first matching transaction, top-N rankings, token-symbol calls) and a 'DON'T USE' exclusion for quick recents or wallet summaries. This makes the choice boundary clear without needing to inspect sibling schemas.

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 annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds useful behavioral context by noting this returns the *indexed* head, not a live chain-tip or status indicator. It further clarifies limitations through the DON'T USE section, which is valuable beyond the annotation fields.

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

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

The description is structured with short, purposeful sections and every snippet adds information: scope, common asks, when to use, when not to use, and examples. It is efficient despite being longer than average because no redundant content is present.

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

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

For a simple two-parameter tool with an output schema and read-only annotations, the description covers accepted inputs, selection of latest vs finalized, examples, and missuse cases. Nothing essential is missing 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?

Schema description coverage is 100%, so the baseline is 3. The description goes further by showing concrete example payloads for 'latest' vs 'finalized' and calling out the typical use case of preceding a block-range query, making the parameters' real meaning clear.

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 just the latest indexed head block or slot for a network.' It clearly distinguishes this lightweight head lookup from network status, table availability, and other sibling query tools via the COMMON USER ASKS and DON'T USE sections.

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

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

The description provides explicit WHEN TO USE bullets, a FIRST CHOICE FOR statement, and a DON'T USE exclusion. This gives an agent clear decision rules for calling this tool instead of using it for status or table-inspection tasks.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context by spelling out what the tool reports (indexing freshness, lag, heads, available tables, capabilities) and giving an example, which helps the agent understand expected 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 well-structured with clear sections and front-loaded intent. There is minor redundancy between FIRST CHOICE FOR and WHEN TO USE, but overall every section contributes useful guidance without excessive verbosity.

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

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

Given the tool has a single required parameter, a complete input schema, and an output schema, the description provides sufficient context for correct invocation. It covers common asks, when to use, when not to use, and includes a concrete example, making it complete for the tool's complexity.

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

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

Input schema has 100% description coverage for the single 'network' parameter, so the baseline is 3. The description adds concrete value with a user-ask example ('Is Base caught up?') and a JSON example using 'base-mainnet', demonstrating the expected parameter format and alias usage.

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

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

Description clearly states the tool's purpose: answering 'is this network caught up?' by providing indexing freshness, lag, heads, and available tables for one network. It distinguishes itself from siblings by emphasizing 'one network' and explicitly noting it is not for getting only the latest block/slot, which separates it from portal_get_head.

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?

WHEN TO USE and DON'T USE sections provide clear usage context and exclusions, such as avoiding this tool when only the latest block or slot number is needed. However, it does not explicitly name the alternative sibling tool, so the guidance stops short of fully explicit alternative routing.

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

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

Annotations already cover readOnlyHint=true and destructiveHint=false. The description adds behavioral detail beyond that: chronological paging, 'newest activity first', 'bounded recent evidence timeline', and investigation pivots. No contradiction 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 well-structured with clear sections and a strong front-loaded summary. There is son.what overlap between COMMON USER ASKS, FIRST CHOICE FOR, and WHEN TO USE, but each section still adds usable direction and the extra length is justified by the tool's broad cross-network scope.

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

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

Given the tool has an output schema, full parameter coverage, and safety annotations, the description is complete. It covers use caxses, exclusions, examples, paging behavior, and how to decide when to use this tool instead of raw query tools. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value through concrete exaxamples such as network values like 'base-mainnet' and 'hyperliquid-fils' and realistic parameter combos. These clarify exact accepted network identifiers beyond the schema's brief description.

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

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

The description states a specific verb and resource: 'Get a simple recent-activity feed across EVM, Solana, Bitcoain, or Hyperliquid.' It clearly distinguishes itself from raw VM-specific query tools by positioning itself as a first-pass feed and investigation starting point. This makes its role unambiguous against the large sibling list.

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 provides FIRST CHOICE FOR, WHEN TO USE, and DON'T USE sections. It tells the agent when to reach for this tool, when not to, and points generally to raw query tools for logs/chain-specific fields and chart tools for time-series needs.

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

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

Annotations carry the safety profile (readOnlyHint=true, destructiveHint=false), lowering the bar. The description adds useful behavioral detail: defaulting to a 6h interactive window, compare-previous windows, and grouped contract trends. It does not cover output format, but an output schema is present, so that gap is acceptable.

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 clear headers and a logical flow, but it is somewhat lengthy. Each section arguably earns its place, and the front-loaded purpose sentence gives immediate orientation. Slight redundancy between 'FIRST CHOICE FOR' and 'WHEN TO USE' prevents a perfect score.

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

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

For an 11-parameter tool with 3 required params, the description covers common use cases, exclusions, examples, and behavioral defaults. Since an output schema exists, return-value details are not required. The description, combined with the rich schema and annotations, gives an agent everything needed to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by providing two concrete JSON examples that demonstrate realistic parameter combinations, including network shorthand, interval buckets, duration defaults, and compare_previous. This practical grounding helps agents assemble correct calls.

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

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

The description opens with a specific verb-resource combination—'Build simple activity charts and other time-series views'—making the core action and resource unmistakable. It also distinguishes itself from sibling tools by explicitly excluding DEX pool candles and OHLC output, which separates it from portal_evm_get_ohlc.

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 'WHEN TO USE', 'DON'T USE', and 'FIRST CHOICE FOR' sections, giving clear selection guidance. The 'DON'T USE' clause explicitly excludes raw record lists and OHLC candles, effectively routing agents toward alternatives like portal_get_recent_activity or portal_evm_get_ohlc without naming them directly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds behavioral context about returning a high-level summary with inbound/outbound flow, top counterparties, evidence pivots, and follow-up filters rather than every raw transaction. No contradictions with annotations.

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

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

The description is longer but well-structured with labeled sections, front-loaded summary, and examples. Some redundancy exists between 'FIRST CHOICE FOR' and 'WHEN TO USE', but the organization makes it easy to scan and the detail is justified for a complex wallet-analysis tool.

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

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

Given the output schema exists, annotations are present, and there are no required params, the description covers all needed selection and invocation context: purpose, common asks, when to use, when not to use, and concrete examples. Nothing essential is missing for an agent to select and call this tool correctly.

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

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

Schema_description_coverage is 100%, so the schema already documents all 11 parameters. The description's examples show sample values for network, address, and timeframe, but do not add new semantic meaning beyond what the parameter descriptions already state. This is the baseline for fully-covered schemas.

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 defines the tool as a wallet activity and fund-flow summarizer, listing specific outputs like shared overview, asset movement, counterparties, and evidence pivots. This differentiates it from sibling query/analytics tools that return raw records or network metadata.

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 has explicit WHEN TO USE and DON'T USE sections, specifying suspicious-wallet triage, stol-en-funds paths, and incident addresses, and excluding raw-record extraction. It does not explicitly name an alternative tool for raw records, but the exclusion is clear enough for an agent to infer a query tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds useful behavioral context by noting the tool returns grouped aggregate analytics without requiring raw fill stitching, which goes beyond the structured annotations.

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

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

The description is well-structured with clear headings and front-loaded purpose. The two examples are redundant since they use identical JSON, but the overall size is appropriate and each section serves a distinct 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?

With full schema coverage, an output schema, and safety annotations, the description provides enough context for an agent to select and invoke the tool correctly. It covers the main use cases, exclusions, and gives concrete example inputs, though a note about pagination or cursor usage would add further completeness.

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

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

Schema description coverage is 100%, so the schema fully documents all 9 parameters. The description's examples reinforce the network and timeframe parameters but do not add significant meaning beyond the schema.

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

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

The description states a specific verb and resource: get big-picture Hyperliquid fill analytics including top traders, volume by coin, fees, and PnL. It clearly distinguishes itself from sibling tools by explicitly excluding individual fill records and OHLC candles.

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 and DON'T USE sections explicitly state the intended use cases and exclusions. It names alternatives such as individual fill records and OHLC candles, making the routing decision straightforward for an agent.

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

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

Annotations already provide safety context (readOnlyHint=true, destructiveHint=false), so the description only needs to add behavioral value. It does so by explaining that candles are derived from fills, are chart-ready, use fixed buckets and auto intervals, and include volume and VWAP. Minor details like pagination and the optional user scope are left to the schema, which is acceptable given the annotation coverage.

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

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

The description is well-structured with clearly labeled sections: common asks, when to use, when not to use, and an example. It is front-loaded with the core purpose and every section earns its place without unnecessary 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?

For a read-only OHLC tool with full schema coverage, an output schema, and explicit usage guidance, the description is complete. It includes an example payload, clear exclusions, and the source of the data, so an agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds conceptual context (chart-ready, fixed buckets, auto intervals) and a concrete example, but it does not add parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: "Build chart-ready Hyperliquid trade OHLC candles with fixed buckets and auto intervals." It clearly states the output type, source data, and scoping, and the DON'T USE section distinguishes it from scalar time-series and raw fills, so an agent can separate it from siblings like portal_get_time_series and portal_hyperliquid_query_fills.

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 and DON'T USE sections give clear selection criteria: use for per-coin Hyperliquid candles with chart-ready OHLC/volume/VWAP, avoid for raw fills or scalar buckets. However, it does not name the specific alternative tools to use in those excluded cases, so it falls just short of the highest bar.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds the 'raw individual' nature of the data, but doesn't disclose other behavioral traits such as pagination via cursor, potential large result sizes, or any rate limits. Given the annotations cover the safety profile, this is an adequate but not rich disclosure.

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

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

The description is well-structured with short labeled sections (COMMON USER ASKS, WHEN TO USE, DON'T USE, EXAMPLES). It front-loads the core purpose and every sentence earns its place. No repetition or fluff.

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

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

Despite having 18 parameters, all are documented in the schema (100% coverage), an output schema exists, and the description provides selection criteria, exclusions, and an example. The description is complete enough for an agent to decide when to use it and how to invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by showing a real invocation example ("Recent BTC fills": network, timeframe, coin, limit) and by listing the filtering dimensions (trader, coin, direction, builder, fee token) that map directly to schema parameters. This helps an agent construct calls correctly beyond what the schema alone provides.

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

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

The description opens with a precise verb and resource: "Query raw individual Hyperliquid fills" and lists the specific context fields (trader, coin, fee, PnL, builder). It clearly distinguishes this tool from siblings like portal_hyperliquid_get_analytics and portal_hyperliquid_get_ohlc by emphasizing raw fill rows versus aggregates/candles.

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 has explicit WHEN TO USE and DON'T USE sections, naming concrete conditions (need raw fills, filter by trader/coin/direction) and exclusions (big picture, top traders, grouped aggregates, candles). It also provides a concrete example for a common user ask, leaving no ambiguity about when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about the tool being a lookup/filter catalog, but does not disclose additional behavioral details such as pagination behavior, result ordering, or how network availability is determined beyond what the schema and annotations already imply.

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 average but every section earns its place: common asks, first-choice guidance, when to use, when not to use, and examples. The front-loaded summary sentence immediately conveys the tool's scope, and the formatting makes the guidance scannable for an agent.

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 lookup tool with an output schema, the description covers the essential decision space: what the tool finds, which filters matter, and when it should not be used. The presence of an output schema relieves the description from explaining return values, and the examples cover representative parameter combinations.

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

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

Schema coverage is 100%, so the schema already documents all six parameters. The description adds value through concrete usage examples mapping common asks to parameter combinations (e.g., Base-like networks via query, Solana mainnets via vm and network_type), which helps an agent infer how to construct effective calls.

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

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

The description states a specific verb and resource: find the correct network or chain name across multiple families. It also distinguishes itself from the surrounding data-querying siblings by being the catalog/discovery tool, explicitly labeled as the first choice before other 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?

Clear WHEN TO USE guidance is provided, including concrete scenarios like uncertainty about network names and filtering by VM, network type, or availability. The DON'T USE section gives an exclusion but does not name an alternative sibling tool such as portal_get_network_info or portal_get_head, so the routing is slightly less explicit than it could be.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral depth beyond those annotations: ambiguity is kept explicit, the tool checks which token-list addresses a symbol maps to, and it provides source-backed addresses rather than recalled constants. This is useful context but does not fully detail edge cases like no-match 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 organized with labeled sections: a one-line summary, common asks, first-choice uses, when to use, don't use, and examples. The most important scoping information is front-loaded, and the examples are compact and directly actionable. No content is wasted or redundant.

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

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

The tool has an output schema, so return values need not be described. Given the four parameters and one required field, the description covers purpose, usage conditions, exclusions, and concrete invocation examples. An agent has everything needed to select and call this tool correctly without additional inference.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing concrete example payloads (e.g., {"network":"base-mainnet","kind":"token","query":"USDC","limit":10}) that illustrate valid combinations of kind, query, network, and limit. This goes beyond the schema's per-field descriptions by showing realistic usage patterns.

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