SQD

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

Annotations already establish read-only and non-destructive behavior. The description adds useful context that address activity requires extra queries and can be slower, which is valuable behavioral information beyond the annotation flags. No contradictions found.

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 a clear purpose and includes structured usage sections. Some redundancy exists among 'common asks', 'first choice', and 'when to use', but overall it remains efficient 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?

With an output schema present, return values need no explanation. The description provides enough context for selecting the tool, understanding its scope, and avoiding misuse, even with nine optional parameters.

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

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

Input schema covers 100% of parameters with meaningful descriptions, so the baseline applies. The main description adds an example call but does not significantly extend parameter understanding beyond the schema's already detailed explanations.

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 a specific action ('Get the big picture') on a specific resource (Bitcoin block, fee, and address activity). It differentiates well from sibling tools like portal_bitcoin_query_transactions and other chain analytics tools by emphasizing high-level network analytics rather than raw 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 explicitly includes WHEN TO USE and DON'T USE sections, telling the agent when to choose this tool and directing raw transaction needs to the appropriate sibling. This leaves no ambiguity about appropriate usage.

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

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

Annotations already declare the tool read-only and non-destructive. The description adds useful context about returning raw transactions, optionally attaching inputs/outputs inline, and avoiding separate input/output tools. It does not discuss pagination or response size limits, but those are already documented in the schema and output schema.

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

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

The one-sentence summary is front-loaded, followed by compact, scannable sections for common asks, when to use, don't use, and examples. Every section earns its place with no redundant 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 12 optional parameters and rich schema/output schema, the description provides sufficient selection and invocation guidance: clear purpose, use cases, exclusions, and two example payloads. Remaining details like cursor pagination are already covered by the parameter descriptions.

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 met. The description adds value with concrete example payloads showing realistic combinations of network, timeframe, limit, and include_inputs/include_outputs.

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

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

States a clear verb and resource ('Query raw Bitcoin transactions') and specifies the optional inline input/output attachment. The 'raw' vs 'summary' distinction and UTXO envelope phrasing help differentiate it from summary/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?

Includes explicit WHEN TO USE and DON'T USE sections, telling the agent to use it for raw transaction records or UTXO envelopes and to avoid it for quick wallet/network summaries. However, it does not explicitly name the alternative tools such as portal_get_wallet_summary or portal_bitcoin_get_analytics.

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 useful context that this returns raw order-action events rather than public fills/analytics, but it does not go deeper into pagination, response behavior, or operational caveats. 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 compact and well-structured with scannable sections: ADVANCED, COMMON USER ASKS, WHEN TO USE, DON'T USE, and EXAMPLES. Every section contributes selection or invocation guidance, and the example is minimal and directly useful.

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 provides enough context: when to use it, when not to use it, a representative example, and a clear distinction from similar tools. The full input schema and output schema cover the remaining parameter and response details, so the description does not need to 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 parameters are already well documented and the baseline is 3. The description adds value with a concrete example mapping a common user ask ('Recent order action') to specific parameter values (network, timeframe, limit), which helps an agent construct a valid request.

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 'Query Hyperliquid replica-command actions' and names concrete examples such as orders, cancels, and leverage updates. It also explicitly distinguishes itself from fills and analytics, so an agent can tell it apart from sibling tools like 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?

It provides explicit 'WHEN TO USE' and 'DON'T USE' guidance, including the condition 'need raw order-action events instead of fills or analytics.' This gives an agent both selection criteria and an exclusion rule, which is exactly what is needed for correct tool choice.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds useful context: the 'ADVANCED' warning, the context-usage note about the lower MCP default, and the field_preset behavior for EVM. It does not contradict 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?

Well-structured with clearly labeled sections (ADVANCED, COMMON USER ASKS, WHEN TO USE, DON'T USE, EXAMPLES). The most important warning (ADVANCED/debugging) is front-loaded, and the example is placed early. Each section earns its place without bloat.

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

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

For a tool with 11 parameters, all documented in the schema, plus an output schema, the description covers the key decision points: when to use it, when not to, and a concrete invocation example. It is complete for an advanced/debugging tool whose safety profile is already carried by 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 coverage is 100%, so all 11 parameters are documented in the schema. The description adds marginal value by giving a concrete example mapping network/timeframe/limit, and notes the tradeoff between timeframe and from_block/to_block, but does not need to explain each 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?

States a specific verb-resource pair ('Query raw block records') with explicit chain scope (EVM, Solana, Bitcoin). The 'raw block records instead of transactions, logs, or summaries' phrasing clearly distinguishes it from the many sibling query tools in the same portal family.

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

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

Has explicit WHEN TO USE and DON'T USE sections. It names concrete alternatives ('recent activity, time series, or raw transaction tools') and states the condition that selects this tool (debugging Portal coverage or block-level fields). A worked example is also provided.

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 destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by noting this is an ADVANCED debugging tool, that it resolves to the 'nearest indexed block or slot,' and that it distinguishes exact versus estimated resolution.

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 scannable sections: purpose, common asks, when to use, when not to use, and examples. Each section contributes practical decision-making or invocation guidance without redundant filler.

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

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

With two well-documented required parameters, an output schema present, and clear examples plus usage boundaries, the description gives an agent everything needed to decide whether to invoke this tool and construct valid inputs. No important operational context is missing.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds concrete examples showing accepted forms such as '1h ago' and ISO datetime strings, which clarifies the timestamp parameter beyond the schema's formal definition.

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 'ADVANCED: Resolve a timestamp to the nearest indexed block or slot,' which clearly states the verb, resource, and intentional scope. This distinguishes it from sibling tools like portal_debug_query_blocks that likely operate on blocks directly rather than resolving times to blocks.

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, giving clear context for when this tool is appropriate and when it is unnecessary. However, it does not name a specific sibling alternative, instead referring generically to 'most public tools,' so the routing guidance is strong but not maximally specific.

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 useful context beyond those annotations by clarifying the network-wide scope, ranked-contract focus, and overview-style output, without contradicting any annotation.

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 sections and a concrete example. It is slightly repetitive in restating 'big picture' across the description, FIRST CHOICE FOR, and WHEN TO USE, but each section is scannable and purposeful.

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, fully described parameters, and safety annotations, the description is nearly complete for tool selection and invocation. The main gap is that the DON'T USE section points to a use case without naming the alternative tool, leaving the agent to infer which sibling handles time-bucket queries.

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 parameters thoroughly. The description adds a concrete example invocation mapping network, timeframe, and limit, but does not add meaningful semantic detail beyond what the schema provides.

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

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

The description states a specific verb ('get') and resource ('network-wide EVM activity') and defines the output shape as ranked contracts and compact overview metrics. It clearly distinguishes the tool from raw record-list query tools by describing it as an analytics-style overview.

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 and a DON'T USE exclusion for chart-bucket-over-time queries. However, it does not name the specific alternative sibling tool for that case, so it stops short of a fully explicit alternative recommendation.

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

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

Annotations already mark the tool as read-only and non-destructive, so the safety profile is covered. The description adds useful context that this tool produces a summary rather than raw records, but it doesn't disclose potential differences between 'fast' and 'deep' execution depth or other behavioral nuances beyond what the schema already says.

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

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

The description is well-structured and scannable, with clear WHEN TO USE and DON'T USE sections. There is some redundancy, such as 'Contract activity snapshot' appearing in both COMMON USER ASKS and EXAMPLES, and FIRST CHOICE FOR overlapping with WHEN TO USE, but it remains appropriately efficient.

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

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

An output schema exists, so return-value details don't need to be in the description. The description covers intent, use cases, exclusions, and a concrete example with required parameters, while the 100%-coverage input schema fills in the rest. Given the 7-parameter complexity, nothing important is missing.

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

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

Schema description coverage is 100%, and every parameter has a useful description and default, so the schema does the heavy lifting. The description's example invocation shows a valid combination of required parameters, but it doesn't add meaning beyond the schema.

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

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

The description opens with 'Summarize what one specific contract has been doing lately', a specific verb+resource combination that clearly defines the tool's scope. It also contrasts itself with raw logs/transactions in the DON'T USE section, making it distinguishable from sibling tools like 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 gives explicit conditions such as wanting a contract-centric summary or top callers and interaction volume. The DON'T USE section explicitly excludes raw logs/transactions and general network activity, giving clear routing guidance even though sibling tool names aren't literally mentioned.

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 (readOnlyHint=true, destructiveHint=false) already signal a safe read operation, and the description adds useful behavioral context: it mentions bounded windows, scan_order semantics, safety caps (max_scan_blocks), and the need for a from_block for older contracts. It does not contradict annotations and enriches the agent's understanding of search behavior, though it could explicitly note what happens when no deployment is found.

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 (core purpose, common asks, when to use, don't use, examples) and is front-loaded with the primary action. Every section serves a distinct purpose, and the length is appropriate for a tool with 11 parameters. No redundant information.

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

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

Given the output schema exists (so return format is covered), the description covers all essential context: input parameters, usage scenarios, exclusions, and practical examples. It fully equips an agent to decide when and how to call 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 parameters. The description adds value through examples showing realistic parameter combinations (e.g., using from_block/to_block with scan_order, or search_depth_blocks), but it does not provide additional semantic detail beyond what the schema offers. The guidance on when to use from_block is already present in the schema itself, so the description doesn't significantly enhance parameter meaning.

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

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

The description clearly states the tool's specific function: locating the create trace and parent transaction that deployed a given EVM contract within a bounded window. It distinguishes itself from siblings like portal_evm_get_contract_activity (which covers activity after deployment) and portal_evm_query_traces, making the purpose unambiguous.

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

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

The description includes explicit 'WHEN TO USE' and 'DON'T USE' sections that specify exact scenarios and even point toward alternatives (e.g., 'You need all activity for a contract after deployment' implies using the activity tool). Examples further illustrate appropriate parameter combinations, leaving no ambiguity about when to invoke 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?

The annotations already indicate read-only and non-destructive behavior, so the description does not need to restate that. It adds useful execution context such as preferring swap-derived sources for factual prices, and clarifies that Uniswap v4 uses PoolManager Swap events rather than per-pool addresses.

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 for common asks, when to use, when not to use, and examples. The content is substantive and each section earns its place; the examples are repetitive only in a useful illustrative way.

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, the description does not need to explain return values. It provides enough context for selecting sources, orienting prices, and understanding v4-specific parameters, so an agent can invoke the tool confidently. Minor gaps remain around default network assumptions, but the schema covers defaults.

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

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

The input schema has 100% parameter coverage, so the baseline is strong. The description adds value by showing realistic JSON examples for v2/v3/v4 and Aerodrome, illustrating how pool_id vs pool_address are used and how price_in and include_recent_trades are set.

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

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

States a specific verb ('Build chart-ready EVM OHLC candles') and resource (supported DEX event sources including Uniswap v2/v3/v4 and Aerodrome Slipstream). It is clearly distinguished from analytics/log-query siblings by focusing on OHLC candles and trade tapes.

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 and DON'T USE sections that clarify when candle/trade data is appropriate versus scalar metrics or simple network activity. It does not name sibling tools explicitly, but the use-case boundaries are clear enough for an agent to route correctly.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, and the description does not contradict them. Beyond annotations, it discloses useful behavior: raw logs are kept available, inline decoding is optional, scan order can target earliest or latest matches, and decoded output can expose fields like decoded_log.decoded.token_id. This goes well beyond what the annotations alone convey.

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

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

The description is well-structured with clear sections: COMMON USER ASKS, FIRST CHOICE FOR, WHEN TO USE, DON'T USE, and EXAMPLES. Each section earns its place, and the concrete JSON examples are compact yet highly informative. For a tool with 25 optional parameters, this length is justified and easy to scan.

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

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

The description covers the tool's purpose, when to prefer it, when to avoid it, and gives representative example payloads for the most common use cases. With an output schema present, rich input schema descriptions, and annotations indicating a safe read-only operation, nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

Schema descriptions already cover 100% of the 25 parameters, so the baseline is 3. The description adds meaningful usage semantics through examples: using token_symbols with event='transfer' for USDC logs, using topic1 as the zero address plus scan_order='latest' and decode=true for NFT mint lookups, and using decode=true to expose decoded fields. This demonstrates parameter combinations in a way the schema alone does not.

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

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

The description opens with a specific verb and resource: 'Query raw EVM logs with address/topic filters, common event aliases, earliest/latest scanning, and optional inline decoding.' It clearly distinguishes this from querying transactions or token-transfer summaries, and the title 'Find smart contract events' reinforces the same scope. The tool is immediately recognizable as the log/event lookup sibling among the portal_* 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 WHEN TO USE bullets and a DON'T USE section naming the token-transfer tool as the alternative when only token transfers are needed. It also gives common user asks with concrete parameter examples, so an agent can confidently decide when to select this tool over siblings like portal_evm_query_transactions or portal_evm_query_token_transfers.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context: the tool abstracts the Transfer event signature, supports token symbols via token-list resolution, scans from earliest or latest, and is optimized for fast bounded-window queries. This goes beyond the annotations without contradicting them.

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

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

The description is longer than average but well-structured with clear sections: summary, common asks, when to use, don't use, and examples. The examples are highly valuable for a 15-parameter tool. There is minor redundancy among the WHEN TO USE bullets, but the overall structure earns its length.

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 no required parameters, full schema descriptions, an output schema, and safety annotations, the description is complete. It gives usage context, exclusions, and two concrete examples. Nothing essential for selecting or invoking the tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents each parameter well. The description still adds value by showing realistic parameter combinations in examples, such as using token_symbols with timeframe and limit for 'recent USDC transfers', and using scan_order:'earliest' with limit:1 for 'first recent USDC transfer'. This maps user intent to parameters more directly than the schema alone.

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: query token-transfer activity on EVM chains. It also clarifies what problem it solves (no need to remember Transfer event signatures) and the intended use cases (token movement and asset-tracing). This clearly distinguishes it from sibling query tools like portal_evm_query_logs or 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 description includes explicit WHEN TO USE and DON'T USE sections. It lists concrete scenarios such as recent USDC transfers, tracing suspicious or stolen funds, and first-transfer queries. It also gives the key exclusion: if arbitrary event logs beyond token transfers are needed, use a different tool. This gives an agent actionable 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 mark this as read-only and non-destructive, so the bar is lower, and the description still adds meaningful behavior: traces are expensive and windows should stay under 5,000 blocks, state diffs are not exposed, the parent transaction hash is attached to every row, and 'reward' only exists in proof-of-work history. No contradiction with annotations 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 front-loaded summary, clear section headers, and valuable examples. However, there is some redundancy between COMMON USER ASKS and WHEN TO USE, with the same use cases repeated in different phrasing, so not every sentence earns a unique 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 complex 23-parameter tool with an output schema and read-only annotations, this description is remarkably complete. It covers when to use, when not to use, example parameter sets, performance constraints, a cross-reference to portal_evm_query_transactions for finding blocks, and explicit exclusions like state diffs. Nothing critical is missing for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all 23 parameters. The description adds value beyond that by providing three concrete example JSON payloads that map common user asks to parameter combinations, and by clarifying filter categories and field presets at a task level. This is helpful but not essential given the schema completeness.

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 action and resource: 'Query raw EVM traces: internal calls, contract creations, self-destructs, and block rewards' and lists concrete filters. It clearly distinguishes this tool from sibling tools by positioning it below the top-level transaction and log surface, so an agent can tell it apart from portal_evm_query_transactions and portal_evm_query_logs.

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 are explicit and actionable, covering internal-call tracing, deployer lookups, incident analysis, and event-less ETH transfers, while excluding top-level transactions, event logs, and storage changes. The only gap is that it refers to 'those tools' without naming the specific sibling tools, though the intent is clear from context.

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

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

Annotations already declare readOnlyHint: true and destructiveHint: false, lowering the bar. The description adds genuine behavioral context beyond that: client-side token-symbol merging, 'Applied client-side while streaming Portal results' for transaction_type, scan-order semantics, and performance caveats on block ranges.

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 lengthy but tightly organized with labeled sections (COMMON USER ASKS, WHEN TO USE, DON'T USE, EXAMPLES). Each sentence carries use-case or boundary information, and the examples map directly to the listed use cases. The length is justified by the tool's 35-parameter 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 35-parameter tool with 0 required params, the description plus fully-covered schema and output schema leaves no ambiguity about inputs, behavior, or limits. Performance guidance is present, exclusion criteria are given, and examples cover 5 distinct invocation shapes. The only minor gap is that DON'T USE doesn't name the exact sibling tools for the excluded cases.

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

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

Schema description coverage is 100%, so the baseline is 3. Descriptions add real meaning beyond the schema: performance ceilings ('<5k blocks for fast <500ms responses'), conditional applicability ('Optional if limit <=100'), composition guidance ('use with scan_order=earliest and from_block to find the first typed transaction'), and the max_token_symbol_matches fallback meaning. A few entries like 'Include logs emitted by transactions' merely restate names, which keeps it from a 5.

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

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

States the verb and resource precisely: 'Query raw EVM transactions with optional logs, traces, state-diff context'. It differentiates from siblings like portal_evm_query_logs and portal_evm_query_traces by naming the exact evidence set it covers.

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 list enumerates eight explicit triggers (raw records, chain-specific fields, evidence pivots, first-of-type searches, top-N rankings, symbol resolution) and DON'T USE explicitly excludes quick-feeds and wallet summaries, which route to portal_get_recent_activity and portal_get_wallet_summary.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context beyond that: it returns the 'indexed' head rather than a live chain tip, works with latest or finalized finality, and returns either a block or slot depending on the network. It also clarifies what this tool is not for.

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 summary sentence is front-loaded and the labeled sections make it easy to scan. There is minor redundancy because 'FIRST CHOICE FOR' and 'WHEN TO USE' both cover the block-range use case, but overall it remains compact for the amount of guidance 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 simple two-parameter head lookup with an output schema and read-only annotations, the description covers purpose, parameter semantics, usage boundaries, and examples. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value with concrete examples mapping 'Latest head' and 'Finalized head' to the type parameter and showing network values like base-mainnet and ethereum-mainnet, going beyond the schema's terse 'Block type' and 'Network name or alias' 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 opening sentence states the exact operation: 'Get just the latest indexed head block or slot for a network.' It clearly identifies a specific resource and scope, and the 'FIRST CHOICE FOR' and 'DON'T USE' sections help distinguish it from broader query or status 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?

Explicit 'WHEN TO USE' and 'DON'T USE' bullets tell the agent to use this when only the current block/slot is needed or before building a raw block-range query, and to avoid it for sync-status or table-availability questions. It does not name the alternative tool for those status checks, so it falls just short of full alternative routing.

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

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

Annotations already declare readOnlyHint true and destructiveHint false, so the safety profile is covered. The description adds useful behavioral context by specifying the tool returns freshness, lag, heads, and available tables, and by scoping it to a single network. Minor behavioral details such as error cases or rate limits are not disclosed, but they are not essential for this read-only status 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 organized with clear sections for common asks, use cases, exclusions, and an example. There is some redundancy between the 'FIRST CHOICE FOR' and 'WHEN TO USE' sections, and the repeated 'caught up' phrasing, but overall it remains compact 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?

Given the tool has only one parameter, a full output schema, and read-only annotations, the description is complete. It tells the agent what the tool returns, when to use it, when not to use it, and provides a runnable example. Nothing critical 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?

The schema already fully documents the single 'network' parameter as 'Network name or alias', so the baseline is 3. The description adds value by providing a concrete example, 'Is Base caught up?: {"network":"base-mainnet"}', which clarifies the expected parameter format and 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?

The description states a concrete verb-resource relationship: it answers whether a network is caught up by returning indexing freshness, lag, heads, and available tables. It clearly distinguishes itself from sibling tools like portal_get_head by noting it is the first choice for network-level indexing status and not just the latest block.

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 and DON'T USE sections. The description tells the agent to use this tool when checking if a network is indexed, fresh, caught up, or behind, and explicitly says not to use it when only the latest block or slot number is needed, which clearly routes away from portal_get_head.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: chronological paging, newest-first ordering, bounded recent evidence timeline, and investigation pivots. It could elaborate on paging mechanics or what 'pivots' means, but with the annotation coverage this is solid.

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 well structured with clear headers, and the core purpose is front-loaded in the first sentence. There is some redundancy between FIRST CHOICE FOR and WHEN TO USE, but each section contributes actionable guidance and the examples are essential for correct invocation.

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 eight optional parameters, 100% schema coverage, and an existing output schema, the description fully equips an agent to select and invoke the tool. It provides common user asks, first-choice scenarios, explicit exclusions, and concrete payload examples, so nothing critical is missing 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value through concrete invocation examples, especially the special 'hyperliquid-fills' network value and the network/timeframe/limit combination, which goes beyond the schema's generic parameter 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 uses a specific verb and resource ('Get a simple recent-activity feed') and clearly scopes the tool to EVM, Solana, Bitcoin, or Hyperliquid. It also distinguishes itself from raw VM-specific query tools by positioning itself as the simple, first-pass feed, so it is not a tautology and 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?

The WHEN TO USE and DON'T USE sections explicitly state when to choose this tool (quick feed, newest activity first, incident triage) and when not to (raw logs, chain-specific fields, time-series charts). It identifies alternatives at a useful category level, pointing to raw VM-specific query tools and chart/time-series tools.

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

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

Annotations already mark this read-only and non-destructive, and the description adds behavioral context beyond them: it returns aggregated chart-ready metric buckets rather than raw records, defaults to a 6h interactive window, and supports compare-previous and grouped EVM contract trends. 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?

Well-structured with headers, front-loaded purpose, and scannable sections. Slight redundancy exists because COMMON USER ASKS overlaps with EXAMPLES, and FIRST CHOICE FOR largely repeats WHEN TO USE, but the repetition is not harmful.

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 a fully described schema and an output schema, the description is complete: it covers purpose, use cases, exclusions, defaults, and concrete examples. An agent has everything needed to select and construct a valid call.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a 4 by mapping common user asks to concrete payloads (e.g., Base transactions per 15m bucket and compare-two-periods examples). This adds usable meaning about parameter combinations beyond the bare schema definitions.

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

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

States a specific purpose: building simple activity charts and time-series views from aggregated metric buckets across supported VMs. The DON'T USE section distinguishes it from raw record-list and OHLC tools, so it is clearly differentiated 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?

Provides explicit WHEN TO USE and DON'T USE sections, naming the conditions that select this tool (chart-ready buckets, compare-current-vs-previous, grouped trends) and the conditions that rule it out (raw record lists, OHLC/DEX candles). It also calls itself FIRST CHOICE FOR the relevant scenarios, leaving little to inference.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses real behavioral details: mode semantics ('fast value is only for explicitly bounded previews' versus deep default), limit_per_type 'safely capped at 4 rows and remains cursorable' despite accepting up to 10, and response_format defaults ('compact' for readable investigation, 'summary' for headline flow, 'full' for all rows). These add genuine behavioral facts not present in the annotations.

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

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

The description is well structured with clear headed sections (COMMON USER ASKS, FIRST CHOICE FOR, WHEN TO USE, DON'T USE, EXAMPLES) and every section adds value. It is slightly redundant — COMMON USER ASKS, FIRST CHOICE FOR, and WHEN TO USE restate the same core message in similar phrasing — but the repetition is organized enough that it reads as emphasis rather than noise.

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 (so return values need no explanation), the description covers all operational context: pagination via cursor, cross-network support (EVM, Solana examples), optional vs required parameters (0 required), the fast/deep mode distinction, and the relationship to sibling raw-query tools. An agent has everything needed to call this correctly without opening other references.

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

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

Schema coverage is 100%, and the description enriches it further: examples demonstrate actual usage (e.g., {"network":"base-mainnet","address":"0xabc...","timeframe":"24h"}), clarifies cursor semantics ('Optional when continuing with cursor' on address/network), and disambiguates tricky fields like limit_per_type (capped at 4 despite max 10) and response_format (defaults to 'compact').

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

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

The description uses a specific verb and resource ('Summarize wallet activity and fund flow with shared overview, asset movement, counterparties, evidence pivots, and follow-up filters across supported networks') and explicitly differentiates itself from sibling raw-query tools like portal_evm_query_transactions via 'before drilling into raw records' (DON'T USE: 'You need every raw record'). An agent can immediately tell this is the high-level aggregation tool versus the detailed query 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 WHEN TO USE and DON'T USE sections are explicit and actionable: use when 'You want a single high-level answer about what one wallet has been doing', avoid when 'You need every raw record with full chain-specific fields'. This names the alternative behavior (raw record drilling, handled by sibling query_* tools) and gives concrete example invocations for both EVM and Solana networks.

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 useful behavioral context: it returns 'grouped aggregate sections' so the caller does not need to stitch raw fills, and it is scoped to network-level analytics rather than individual records. No contradiction found.

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

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

Well-organized and scannable: a one-sentence summary followed by COMMON USER ASKS, WHEN TO USE, DON'T USE, and EXAMPLES. It is somewhat repetitive because the examples and common asks cover the same network/timeframe shape, but every section 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 9 optional parameters, 100% schema coverage, an output schema, and readOnly/openWorld annotations, the description is complete enough for correct selection and invocation. It covers when to use, when not to use, and shows two minimal valid example payloads without needing to restate schema details.

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

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

All 9 parameters are fully described in the input schema, so the description does not need to carry this burden. The examples reinforce the network and timeframe fields but add no new parameter semantics beyond what the schema already states.

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

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

Opens with a specific verb and resource: 'Get the big-picture Hyperliquid fill analytics with top traders, volume by coin, fees, and PnL.' It names concrete output dimensions and distinguishes itself from fill/OHLC tools via the DON'T USE section, so an agent can identify it among sibling analytics/query 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?

Provides explicit WHEN TO USE bullets ('network-level Hyperliquid fill analytics', 'who traded the most...') and a clear DON'T USE bullet for 'individual fill records or OHLC candles.' It does not directly name sibling tools like portal_hyperliquid_query_fills, but the usage boundaries are 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 and destructiveHint=false, and the description adds useful behavioral context by noting the data source is fills, output includes OHLC/volume/VWAP, and buckets are chart-ready. It doesn't cover cursor pagination or timestamp edge cases, but the schema describes those parameters and the safety profile is already covered by annotations.

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

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

The description is well-organized with bolded sections, a front-loaded summary, explicit usage guidance, and a compact example. Every section earns its place and there is no filler or repetition beyond reinforcing the key 'chart-ready' concept.

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 a rich input schema and an output schema present, the description covers the essential context: when to use, when not to use, what data is produced, and a concrete example. No critical guidance appears missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already explains all eight parameters thoroughly. The description contributes an example showing how network, coin, duration, and interval combine, but it does not add substantial parameter semantics beyond what the schema provides.

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

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

The description opens with a specific verb and resource: 'Build chart-ready Hyperliquid trade OHLC candles with fixed buckets and auto intervals.' It clearly distinguishes this tool from siblings by scoping it to Hyperliquid and to OHLC candle construction rather than raw fills or analytics.

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 with concrete conditions and exclusions, including 'scalar time-series buckets or raw fills' as alternatives. It also provides a worked example ('BTC candles') showing the expected parameter call.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by emphasizing that this returns raw, individual fill rows rather than aggregated summaries, which sets expectations about output granularity. It does not add pagination or rate-limit notes, but those are less critical given the annotations and output schema.

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

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

The description is well-organized into COMMON USER ASKS, WHEN TO USE, DON'T USE, and EXAMPLES sections. The core purpose is front-loaded in the first sentence, and every section contributes to either selection or invocation guidance. The example is realistic and compact.

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 18-parameter tool with 100% schema coverage, an existing output schema, and clear annotations, the description is complete. It tells the agent when to use, when not to use, and shows a concrete invocation. There is no critical missing information for an agent to call 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 all 18 parameters are already documented in the input schema. The description adds little beyond referencing the filter dimensions (trader, coin, direction, builder, fee token) and providing one JSON example. It meets the baseline for schema-heavy definitions but does not go beyond 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 opens with a specific verb and resource: 'Query raw individual Hyperliquid fills' and immediately lists the included contexts (trader, coin, fee, PnL, builder). It also distinguishes itself from aggregated/candle tools in the DON'T USE section, so an agent can tell it apart from sibling analytics and OHLC tools without inspecting 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 section explicitly states the tool is for raw fill records and filtering by trader, coin, direction, builder, or fee token. The DON'T USE section explicitly warns against using it for big picture, top traders, grouped aggregates, or candles, which are alternative sibling tools. This is clear, actionable 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 annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, establishing this as a safe read-only lookup. The description adds useful behavioral context by clarifying it is a catalog/discovery tool, not a live-data query, and by framing its role as the first step before other queries. No 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 well structured with scannable sections: purpose, common asks, first choice, when/don't use, and examples. Each section is purposeful and the examples are directly actionable, making the length justified.

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

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

For a discovery tool with 6 optional parameters, no required parameters, and an output schema, the description fully covers when, why, and how to use it. The output schema handles return-value details, and the examples plus exclusion guidance complete the 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 100%, so the parameters are already documented. The description adds value by mapping common user asks to concrete parameter combinations (e.g., 'Show Solana mainnets' → vm+network_type) and providing example JSON payloads, which helps the agent construct 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 states a specific verb and resource: finding the right network or chain name across EVM, Solana, Bitcoin, Substrate, and Hyperliquid. It clearly differentiates this discovery tool from the sibling analytics and query tools, which assume the network is already known.

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 'FIRST CHOICE FOR', 'WHEN TO USE', and 'DON'T USE' sections, giving clear conditions for invocation and an explicit exclusion case. It names the alternative pattern (querying live data directly) and tells the agent when not to use 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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context: ambiguity is kept explicit, it maps symbols to token-list addresses, and it returns source-backed addresses rather than relying on memory. This goes beyond the structured annotations without contradicting them.

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

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

The description is well-structured with clear headers: COMMON USER ASKS, FIRST CHOICE FOR, WHEN TO USE, DON'T USE, and EXAMPLES. It is longer than average but every section earns its place by providing actionable routing information. The core purpose is front-loaded in the first sentence.

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 all entity kinds, network scoping, common user intents, exclusions, and provides examples. An output schema exists to handle return-value details, so nothing critical is missing. For a resolver tool with this complexity, the description is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value with concrete worked examples for each kind (e.g., resolving USDC, WETH, BAYC, Hyperliquid bitcoin), clarifying how network, kind, query, and limit interact. This makes parameter usage more concrete than the schema alone.

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 statement: 'Resolve user-facing blockchain entities into query-ready identifiers, with ambiguity kept explicit.' It names the resource (blockchain entities) and the verb (resolve), and the title reinforces the function. This clearly differentiates portal_resolve_entity from the many query-focused sibling 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 contains explicit 'FIRST CHOICE FOR', 'WHEN TO USE', and 'DON'T USE' sections. It lists concrete scenarios (resolving USDC, WETH, BAYC, Hyperliquid coins) and tells the agent exactly when not to call this tool, such as when an exact address or filter is already known. 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.