SQD

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 framing this as network-level aggregation and disclosing the app-rendering caveat that a successful result is 'not proof that the host rendered it.' 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 short headings and scannable bullets, and the core purpose is front-loaded. It loses a point for slight redundancy, as 'the big picture for Bitcoin right now' appears in both FIRST CHOICE FOR and WHEN TO USE.

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 9-parameter schema and existing output schema, the description provides an example invocation, explicit usage boundaries, metric categories, and app-integration context. An agent has enough information to select and call the tool correctly without major gaps.

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

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

The input schema covers 100% of parameters, so the schema already carries the burden. The description adds value with a concrete example payload and by mapping 'recent or explicit window' to the timeframe versus block/timestamp parameter options, which helps operationalize 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 a specific verb and resource: 'Get the big picture for Bitcoin block, fee, and address activity.' It clearly distinguishes itself from raw transaction retrieval through the DON'T USE section, making it easy to separate from sibling tools like 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 WHEN TO USE section enumerates explicit scenarios, and DON'T USE explicitly redirects when raw transactions are needed. This goes beyond implied usage and gives an agent clear criteria for choosing this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the description does not need to repeat safety behavior. It adds useful behavioral context by noting that inputs and outputs can be attached inline, that results are raw transaction records, and that results can open in the SQD Blockchain Activity Explorer. It does not detail pagination or finalization behavior, but those are partly covered by 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 description is well-structured with clear sections and front-loaded context. There is some redundancy between 'COMMON USER ASKS' and the 'EXAMPLES' section, but overall every section contributes to selection and invocation guidance.

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

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

For a 12-parameter tool with a full input schema, an output schema, and annotations already covering safety, the description is complete enough. It gives selection criteria, exclusions, concrete examples, and post-result context about the SQD app, so an agent has sufficient guidance to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by showing concrete parameter combinations in the examples, such as using timeframe with limit and include_inputs/include_outputs together. This helps an agent assemble valid calls even though it does not explain every individual parameter in prose.

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

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

The description starts with a specific action ('Query raw Bitcoin transactions') and a clear resource, and differentiates from sibling transaction tools by emphasizing Bitcoin, raw records, and inline inputs/outputs. This makes it easy for an agent to distinguish from EVM/Solana/Substrate transaction 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' and 'DON'T USE' sections explicitly state when to choose this tool: for raw Bitcoin transaction records and UTXO envelopes, and when not to: for quick wallet or network summaries. The examples further reinforce valid invocation patterns.

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 and non-destructive behavior. The description adds useful context that this exposes raw order-action events for debugging, and the schema notes the one-record limit as a verified safe response budget. This is enough behavioral context beyond the annotations.

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

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

The description uses clear labeled sections and front-loads the core purpose. It is slightly redundant because the COMMON USER ASKS item and the EXAMPLES section both show the same 'recent order action' scenario, but overall it is well-structured 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 13 parameters, rich schema descriptions, output schema, and annotation coverage, the description is adequate for an agent to understand when and how to call the tool. The example and sibling differentiation compensate for the large optional parameter surface.

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 main description does not add parameter-level meaning beyond the schema, though the example illustrates a valid combination of network, timeframe, and limit for a common ask.

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 queries Hyperliquid replica-command actions such as orders, cancels, and leverage updates, and explicitly distinguishes this from fills and analytics. This makes it easy to differentiate 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?

There is an explicit WHEN TO USE section for debugging replica-command records and needing raw order-action events, plus a DON'T USE section for public trading activity that better fits fills and analytics. This gives an agent concrete decision rules.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral framing: 'ADVANCED', direct raw-record access, and debugging-only intent, which clarifies that this is not a typical user-facing query tool. 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 well-structured with short labeled sections (ADVANCED, COMMON USER ASKS, WHEN TO USE, DON'T USE, EXAMPLES). Every section earns its place, the key warning is front-loaded, and there is no redundant repetition of schema content.

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

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

For an 11-parameter tool with no required parameters and an output schema, the description covers a common use case, gives an example payload, and provides explicit alternative routing. Output expectations are handled by the output schema, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a concrete example mapping network/timeframe/limit to 'Recent Base blocks', which helps the agent select parameters for a common ask beyond the 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?

The description states a specific verb ('Query') and resource ('raw block records') across EVM, Solana, or Bitcoin, and distinguishes itself from derived data like transactions, logs, or summaries. The title 'Inspect raw blocks' reinforces, but the description goes beyond it by naming exact scope and format.

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 ('debugging Portal coverage or block-level fields', needing raw records) and DON'T USE ('normal end-user question; prefer recent activity, time series, or raw transaction tools first'). It names alternative tool categories and gives routing guidance, so an agent can decide 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 provide readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds behavior beyond these annotations by noting that resolution is to the nearest indexed block or slot and that exact versus estimated resolution is part of the debugging purpose.

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

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

The description is well-organized with a one-line definition, common asks, when/when-not to use, and concrete examples. Each section adds value with no filler, and the purpose is front-loaded.

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

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

For a two-required-parameter tool with an output schema and complete schema coverage, the description provides enough context and examples to call the tool correctly. It also covers common network examples and the main misuse case.

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 already explains the timestamp formats, including natural language like '1h ago'. The description's examples are useful illustrations but do not materially expand on the parameter semantics already present in the schema.

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

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

The opening line states a specific action—resolve a timestamp—and the object is clearly the nearest indexed block or slot. This distinguishes it from sibling query tools like portal_debug_query_blocks and from general time-filtered 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?

The description includes explicit WHEN TO USE and DON'T USE sections. It tells the agent when this tool is appropriate and advises against it when natural timestamp querying is already supported by public tools, which is clear 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 cover read-only safety with readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond annotations: it explains the output's relationship to the SQD Blockchain Activity Explorer and cautions that a tool result is not proof the host rendered it. 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 well-structured with action-oriented headings and front-loaded purpose. There is minor redundancy between 'FIRST CHOICE FOR' and 'WHEN TO USE', but every section contributes useful routing or usage information, so it remains efficient for the tool's complexity.

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

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

For a tool with 9 optional parameters, a rich schema, and output schema, the description covers the essential decision context: what it returns, when to prefer it over alternatives, when not to use it, and a working example. The app-rendering note also sets correct expectations for downstream behavior.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters clearly. The description adds only a single example call showing network, timeframe, and limit together, which is helpful but not substantial enough to raise above the baseline for fully documented 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?

States a specific verb and resource: 'Get the big picture for network-wide EVM activity with ranked contracts and compact overview metrics.' This clearly distinguishes it from sibling query tools like portal_evm_query_transactions and portal_evm_get_contract_activity, which target raw records or single contracts.

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

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

Provides explicit when-to-use guidance ('You want the big picture for activity on an EVM network') and a clear exclusion ('DON'T USE: You need chart buckets over time rather than ranked entities'). It also supplies a concrete example for a common ask, making the selection criteria actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly avoids repeating that. It adds behavioral context beyond annotations: the tool returns a summary rather than raw records, supports optional event activity, and explains the MCP App behavior with 'A tool result is ready for the App but is not proof that the host rendered it.' It omits auth/rate-limit details, but for a read-only summary tool this is a minor gap.

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

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

Well-structured with clear headings and a front-loaded core sentence. The COMMON USER ASKS section is slightly redundant with FIRST CHOICE FOR and EXAMPLES, and the MCP APP note adds length, but overall every major section earns its place and the definition remains 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 7 parameters and a rich output schema, the description gives complete orientation: core behavior, selection conditions, exclusions, a concrete example, and app-integration context. It does not explicitly map all time-range alternatives like to_timestamp and from_timestamp, but the schema covers those, so no critical decision is left ambiguous.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents all 7 parameters including enums, defaults, and accepted timestamp formats. The description only adds a concrete example with network, contract_address, and timeframe and does not introduce new semantic meaning beyond the schema, which is acceptable.

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 'Summarize' with a specific resource 'what one specific contract has been doing lately', plus concrete contents (recent interactions, unique callers, optional event activity). The DON'T USE section contrasts it with raw logs/transactions and general network activity, distinguishing it from siblings like portal_evm_query_logs and portal_get_recent_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?

Dedicated WHEN TO USE and DON'T USE sections give explicit decision rules: use when asking 'what has this contract been doing?' or needing top callers and interaction volume for one contract; do not use for raw logs/transactions or general network activity. This is explicit routing to alternatives rather than implied 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?

Beyond the readOnly/openWorld annotations, the description discloses the bounded-window search, create-trace semantics, alias support, and even the MCP App rendering caveat. It sets accurate expectations without contradicting the annotations.

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

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

The description is long, but every section earns its place and the main purpose is front-loaded. Headers and short lines make it scannable for an agent, and the examples are directly reusable as invocation sketches.

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

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

Given the rich input schema, output schema, and read-only annotations, the description covers selection, parameter use, examples, and the app-rendering caveat. An agent has everything needed to decide 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?

With 100% schema coverage, the schema already documents parameters, so baseline is 3. The description adds meaningful combinations via examples (e.g., from_block + scan_order='earliest' for old deployments, search_depth_blocks for recent ones) and clarifies alias usage like BAYC/Bored Apes.

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

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

The opening sentence names a precise verb+resource: locate the create trace and parent transaction that deployed a specific EVM contract address. The FIRST CHOICE and DON'T USE sections distinguish it from general contract-activity tools and from activity-after-deployment lookups.

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, DON'T USE, FIRST CHOICE, and EXAMPLES explicitly state when to call this tool versus looking at general contract activity, and they instruct users to provide from_block/from_timestamp for older contracts. This leaves little room for mis-selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral value by explaining the output is chart-ready candles plus a trade tape, noting source-specific caveats like Uniswap v4 using PoolManager Swap events filtered by pool_id, and clarifying that an App-ready result is not proof the host rendered it. 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 longer than ideal, but it is well-structured with clear headers (COMMON USER ASKS, WHEN TO USE, DON'T USE, EXAMPLES, MCP APP) and front-loads the core purpose. The examples are lengthy but earned their place given the 24-parameter surface area. Minor redundancy with schema descriptions keeps it from a 5.

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

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

Given the tool's complexity (24 params, 5 enums, multiple DEX sources, output schema), the description is remarkably complete. It covers source variants, realistic parameter bundles, source-specific addressing differences, exclusions, and even post-result behavior in the MCP App. The output schema handles return-value details, so nothing essential is missing for an agent 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 description coverage is 100%, so the baseline is 3. The description adds meaning through concrete JSON examples that show which parameter combinations are relevant per source: pool_address for v2/v3/Aerodrome, pool_id for v4, price_in for Aerodrome, and include_recent_trades for trade tape requests. This is useful beyond what the schema independently provides, though it does not detail every optional 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 opens with a specific verb and resource: 'Build chart-ready EVM OHLC candles plus a recent trade tape from supported DEX event sources.' It names concrete sources (Uniswap v2-style swaps, Uniswap v3/v4, Aerodrome Slipstream) and includes explicit common user asks, making it easy to distinguish from analytics, query, and time-series 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 WHENTOUSE / DON'T USE sections explicitly define when this tool is appropriate (OHLC candles, chart-ready candle data, recent trade tape) and when it is not (scalar metrics, simple activity charts). These exclusions also name the alternative tool categories, such as time-series or analytics, which gives an agent clear 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 establish read-only, non-destructive, open-world behavior, so the description only needs to add context. It adds meaningful behavioral detail: results are raw logs with optional decoded hints, scanning can begin from earliest or latest, and the MCP APP note discloses that a successful result is not proof the host rendered it.

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

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

The description is long but highly structured with labeled sections: COMMON USER ASKS, FIRST CHOICE FOR, WHEN TO USE, DON'T USE, EXAMPLES, and MCP APP. The opening sentence is an efficient summary, and every bullet or example adds practical information 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 25-parameter tool with an output schema and strong annotations, this description covers user intents, selection criteria, exclusions, concrete parameter recipes, and app-integration caveats. An agent has everything needed to call the tool correctly and avoid common mistakes.

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 real value beyond the schema. It explains common event aliases, provides complete JSON examples, and shows how to combine topic1, scan_order, decode, and limit to get ERC721 mint token_id and transaction_hash.

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 specific verb and resource ('Query raw EVM logs') and lists distinctive capabilities: address/topic filters, common event aliases, earliest/latest scanning, and inline decoding. It also explicitly names what it is not for ('DON'T USE: You only want token transfers'), helping agents distinguish it from siblings like portal_evm_query_token_transfers 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?

WHEN TO USE and DON'T USE sections give explicit selection criteria, including the alternative token-transfer tool. Examples map common user asks to concrete parameter choices, so an agent knows when to call this tool versus a sibling.

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

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

Annotations already establish readOnly/openWorld/non-destructive behavior. The description adds useful context beyond that: it explains the convenience of avoiding Transfer topic hashes, supports earliest-scan ordering for 'first transfer' questions, and discloses the MCP App integration behavior including the caveat that a result is not proof the host rendered it.

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-organized with clear headers: purpose, common asks, when to use, don't use, examples, and app behavior. The first sentence is front-loaded and efficient, though the 'COMMON USER ASKS' and 'EXAMPLES' sections partially overlap, making it slightly less concise than it could be.

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

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

For a tool with 15 optional parameters and an output schema, the description provides robust selection guidance, exclusions, examples, and post-result app context. The output schema covers return-value expectations, so the description does not need to restate them; nothing essential for correct invocation is missing.

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

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

The input schema already documents all 15 parameters thoroughly, so the baseline is 3. The description adds value with concrete examples mapping common user intents to parameter combinations, such as token_symbols + timeframe + limit for 'recent USDC transfers' and scan_order:'earliest' for 'first recent USDC transfer', plus the filter-by-token/sender/recipient guidance.

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 differentiates itself by noting it removes the need to remember Transfer event signatures. The WHEN TO USE bullets further pin it to ERC-20 transfer filtering and asset-tracing, which clearly separates it from siblings 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 description has an explicit WHEN TO USE section with five concrete conditions and a DON'T USE section that rules out arbitrary event logs. It tells the agent exactly when this is the fastest and easiest option and when to go elsewhere, 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?

Annotations already mark this read-only and non-destructive; the description adds useful context about raw evidence retrieval, ranking, aggregation, and the MCP App result-rendering caveat. It does not contradict the annotations and supplies more behavioral color than the schema alone, though it omits details like pagination/cursor behavior that might matter in practice.

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 purpose, but it is lengthy and the COMMON USER ASKS list partially overlaps with the EXAMPLES section. The MCP APP paragraph is somewhat tangential to invoking the tool correctly, though not wastefully so.

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 35 optional parameters, no required fields, and an output schema, the description covers the essential decision space: raw transaction needs, common filters, special first/ranked/aggregate queries, token-symbol resolution, and when not to use it. Combined with 100% schema coverage and an output schema, an agent has enough context 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 coverage is 100%, so the baseline is 3; the description adds real value by showing parameter combinations through JSON examples (e.g., transaction_type + scan_order + from_block for the first EIP-2930 tx, and to_token_symbols + method + order_by for token calls). It doesn't exhaustively explain all 35 parameters, but it doesn't need to because the schema already does.

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 transactions'—and clearly frames transaction-level investigations with optional logs, traces, and state diffs. It differentiates itself from 'convenience tools' but does not explicitly name sibling tools like portal_evm_query_token_transfers or portal_evm_query_logs, so the contrast is implied rather than stated.

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

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

A dedicated WHEN TO USE section lists concrete scenarios, and DON'T USE states exclusions such as quick recent feeds or wallet-level summaries. The guidance is strong and practical, but the alternative tools are not named, leaving the agent to map 'wallet-level summary' to portal_get_wallet_summary on its own.

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 bar is lower. The description adds useful context that the result is the 'indexed' head and that this is not suitable for determining whether a network is caught up, which alerts the agent to limitations beyond the structured hints.

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

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

The description is well-structured with short, scannable sections and a front-loaded core statement. Every section earns its place, and the JSON examples are the only extra weight, which is justified.

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

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

The tool is simple, annotations cover safety, the schema covers parameters, and an output schema exists. The description fills the remaining practical gaps: when to use it, what not to expect, and concrete request examples. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds value with concrete examples showing exactly how to request latest versus finalized heads, and explicitly maps the common user asks to the 'type' parameter, improving clarity beyond the raw enum.

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 specific verb and resource: 'Get just the latest indexed head block or slot for a network.' The word 'just' and 'head' clearly distinguish this from sibling analytics, network-info, and query tools without needing to name them.

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

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

Provides explicit WHEN TO USE and DON'T USE sections. It tells an agent exactly when this is the first choice (before manual block ranges), and when to avoid it (checking sync status or table availability), leaving no ambiguity.

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 details about what the call reports: indexing freshness, lag, heads, available tables, chain family, and real-time status. It does not contradict annotations and provides meaningful operational context beyond 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 and front-loaded with the primary purpose. Each labeled section, such as FIRST CHOICE FOR, WHEN TO USE, and DON'T USE, adds distinct value, and the example is concrete without being verbose.

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 one required parameter, a complete input schema, and an output schema, the description covers the key decision points: when to use, when not to use, and what to expect. The example seals the net as fully usable by an agent for the common user ask.

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 parameter with a description and 100% coverage. The description adds a concrete example value "base-mainnet" but does not explain network formats, aliases, or validation rules. This meets the baseline but does not elevate parameter understanding 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 explicitly defines the tool as answering "is this network caught up?" with indexing freshness, lag, heads, and available tables. It also states it is the first choice for network-level indexing status and explicitly excludes the latest-block use case, making it clearly distinguishable from portal_get_head and analytics 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 section gives concrete scenarios, and DON'T USE identifies when to avoid it for simply needing the latest block or slot number. However, the alternative tool for that case is not named directly, so the guidance is strong but not fully explicit about sibling selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the bar is lower. The description adds valuable behavioral context: newest-first ordering, bounded evidence timelines, chronological paging, and the SQD Blockchain Activity Explorer app integration caveat. It does not contradict annotations and goes beyond the schema by explaining result 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 longer than average but front-loads the core purpose and then uses clearly labeled sections for user asks, first-choice conditions, when-to-use, don't-use, examples, and app behavior. There is some redundancy between FIRST CHOICE FOR and WHEN TO USE, but each section earns its place by giving the agent decision-ready 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 has 8 optional parameters, a full schema, output schema, and safety annotations, the description covers the remaining gaps thoroughly: supported network categories, example requests, exclusion cases versus raw query tools, paging behavior, and post-result app behavior. Nothing an agent needs to invoke this 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 baseline is 3. The description adds beyond the schema through concrete examples mapping user asks to parameter values, such as {'network':'base-mainnet','timeframe':'1h','limit':10} and {'network':'hyperliquid-fills','timeframe':'1h','limit':10}. This clarifies how the network and timeframe parameters should be used in context.

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

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

The opening sentence states a specific verb ('Get') and resource ('simple recent-activity feed across EVM, Solana, Bitcoin, or Hyperliquid') with distinctive characteristics: chronological paging and investigation pivots. It also explicitly differentiates from raw VM-specific query tools and chart/time-series tools, making sibling separation clear.

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

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

The description has explicit WHEN TO USE and DON'T USE sections, names the alternative categories (raw logs/instructions/chart-over-time tools), and provides concrete example invocations. It gives the agent clear decision criteria for selecting this tool over siblings like portal_evm_query_logs or portal_get_time_series.

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

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

Beyond the readOnly and non-destructive annotations, the description adds meaningful behavior: default 6h interactive window unless a longer window is requested, the distinction between fast and deep modes, and the MCP App caveat that a successful result is not proof the host rendered it. This materially improves agent expectations.

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

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

The description is long but tightly organized with labeled sections, front-loaded purpose, and no filler. Headers like COMMON USER ASKS, WHEN TO USE, DON'T USE, and EXAMPLES make it scannable and every section earns its place for a tool with this many parameters.

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 an output schema, the description covers selection criteria, defaults, exclusions, examples, mode behavior, and app integration. Nothing necessary for correct invocation appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value above the schema by showing realistic parameter combinations in examples and clarifying duration defaults and mode semantics. This earns a 4 without duplicating schema detail.

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

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

The description states a specific verb and resource: 'Build simple activity charts and other time-series views across supported VMs, including compare-previous windows and grouped EVM contract trends.' This clearly differentiates it from sibling tools like OHLC, raw transaction queries, and contract-activity tools. Examples further cement the intended 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 'WHEN TO USE' and 'DON'T USE' sections give explicit decision rules, including exclusions for raw record lists and DEX pool candles/OHLC. The 'FIRST CHOICE FOR' list and concrete examples make selection straightforward without needing to open 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?

Annotations already declare the tool read-only and non-destructive, and the description adds useful behavioral context: results can open in the SQD Blockchain Activity Explorer, a tool result being ready is not proof the host rendered it, and the response is a summarized wallet investigation rather than raw records. There is no contradiction with the annotations.

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

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

The description is organized with clear headings, short bullets, and concrete examples. Every section earns its place, and the most important information is front-loaded in the opening 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 when to use, when not to use, example invocations, and app-rendering caveats. Since the input schema fully documents all 11 parameters and an output schema exists, nothing an agent needs to invoke this 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 coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by giving realistic parameter combinations for EVM and Solana, including network aliases like 'base-mainnet' and 'solana-mainnet' and timeframe examples like '24h' and '6h', which helps an agent form 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 and resource: 'Summarize wallet activity and fund flow' and lists concrete output facets such as counterparties, evidence pivots, and follow-up filters. This clearly distinguishes it from sibling raw-query and analytics tools like portal_evm_query_transactions or portal_evm_get_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 provides explicit WHEN TO USE, DON'T USE, FIRST CHOICE FOR, and COMMON USER ASKS sections. It tells an agent exactly when to pick this tool and warns against using it when raw chain-specific records are required, which prevents confusion with sibling transaction-query 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 communicate read-only, open-world, non-destructive behavior. The description adds useful behavioral context beyond the annotations: it is network-level aggregate analytics, returns grouped sections, and can open in the SQD Explorer with coverage/freshness details. It does not dwell extensively on pagination or rate limits, but the output schema exists to cover return structure.

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, user asks, when/don't-use, and examples. It earns most of its length, though the final MCP APP paragraph is somewhat tangential to tool selection and invocation, and the two examples are nearly identical.

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 nine-parameter tool, the schema fully documents parameters, and the output schema covers return values. The description supplies selection guidance, exclusions, examples, and integration behavior, leaving no critical gap for an agent deciding whether and how to call this tool.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters meaningfully. The description adds example payloads and common-ask mappings, but those examples mostly reuse the same network/timeframe arguments and do not meaningfully enrich understanding of cursor, section_limit, mode, or response_format beyond what the schema 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?

The description opens with a specific verb and resource: 'Get the big-picture Hyperliquid fill analytics with top traders, volume by coin, fees, and PnL.' It clearly distinguishes this aggregate tool from raw-fill and OHLC tools via the 'DON'T USE' section, so an agent can immediately tell what it does and what it is not.

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 scenarios, including network-level analytics and grouped aggregates without stitching raw fills. The 'DON'T USE' section explicitly excludes individual fill records and OHLC candles, pointing the agent toward the correct sibling tools without ambiguity.

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: candles are built 'from fills', intervals are auto-chosen with documented bucket mappings, and results are chart-ready and app-compatible. It also honestly notes that a tool result 'is not proof that the host rendered it.'

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 headings and an example, but it has redundancy: 'COMMON USER ASKS: BTC candles' is essentially repeated by the EXAMPLE block. The 'MCP APP' paragraph adds context about app integration but is tangential to tool invocation and adds 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 six-parameter, all-optional tool with an output schema, the description covers purpose, usage boundaries, a concrete example, and non-trivial interval behavior. It doesn't narrate cursor pagination or the user parameter in detail, but those are already described in the input schema, and the output schema handles return values.

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 meaningful value beyond the schema: it explains 'auto' interval defaults concretely (1h→5m, 6h→15m, 12h→30m, 24h→1h), provides a complete JSON example, and clarifies 'duration' semantics with 'past 30 minutes' style phrases.

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 object: 'Build chart-ready Hyperliquid trade OHLC candles with fixed buckets and auto intervals.' It clearly identifies the resource (Hyperliquid trade fills), the output (OHLC/volume/VWAP candles), and the domain-specific scope, distinguishing it from generic OHLC tools and scalar time-series 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' sections state the appropriate conditions: candles for one Hyperliquid coin and chart-ready OHLC/volume/VWAP from fills, while excluding scalar time-series buckets and raw fills. It does not name sibling tools explicitly (e.g., portal_get_time_series or portal_hyperliquid_query_fills), so it stops short of the strongest alternative-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 declare readOnlyHint=true and destructiveHint=false, and the description consistently says 'Query' rather than implying mutation. It adds useful behavioral context beyond annotations by emphasizing raw, individual fill rows and noting that the result is app-ready but not proof of host rendering.

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

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

Despite length, the description is tightly structured with labeled sections and no filler; the core verb/resource sentence is first, and every section earns its place. The example is compact and action-relevant.

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 18-parameter, zero-required tool with a rich input schema and output schema, the description covers invocation contexts, exclusions, a realistic example, and app behavior. The schema handles all parameter semantics, and the output schema removes the need to describe return values in prose.

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 and the schema carries parameter documentation. The description adds value on top by grouping parameters into semantic categories (trader, coin, fee, PnL, builder) and providing an executable example that shows how timeframe, coin, and limit combine.

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

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

The opening sentence names a specific action ('Query raw individual Hyperliquid fills') and resource (fills with trader, coin, fee, PnL, and builder context), and the DON'T USE section explicitly distinguishes it from aggregate/candle tools. This is more precise than the title and separates it from analytics and OHLC 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?

Dedicated WHEN TO USE and DON'T USE sections state exactly when raw fill records are needed and rule out aggregate/analytics use cases. The example for common asks shows a concrete filter invocation, and the exclusions ('big picture, top traders, grouped aggregates, or candles') map to sibling analytics/OHLC 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 provide readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds behavioral context beyond annotations: the tool is a pre-query discovery step ('FIRST CHOICE FOR: finding the correct network before any other query'), supports VM/network-type/real-time filtering, and is non-authoritative for live data. Minor gap: no mention of pagination/ordering behavior, though cursor is in the schema.

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

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

The description is well-structured with labeled sections (COMMON USER ASKS, FIRST CHOICE FOR, WHEN TO USE, DON'T USE, EXAMPLES). Each section earns its place: it covers purpose, selection criteria, exclusions, and usage examples without repetition, and it front-loads the core scope in the first sentence. Length is appropriate for a 6-param discovery tool with many siblings.

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 6 optional parameters, the output schema, and the large sibling family, the description is remarkably complete. It explains what the tool does, when to prefer it, when to avoid it, and how to combine parameters via examples. The output schema exists, so return-value documentation is redundant here. Nothing essential for an agent to call this 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 baseline is 3. The description adds value by mapping user intents to concrete parameter combinations (e.g., {'query':'base','limit':10}, {'vm':'solana','network_type':'mainnet'}) and by explaining high-level filter themes ('VM family, network type, or real-time availability'). This goes beyond the schema's item-level 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?

Description opens with a specific verb and resource: 'Find the right network or chain name to use across EVM, Solana, Bitcoin, Substrate, and Hyperliquid.' It also distinguishes itself from sibling data-query tools via the 'DON'T USE' section ('You already know the exact network and want live data from that network'), so an agent can clearly identify this as the discovery/lookup 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?

Explicit 'WHEN TO USE' and 'DON'T USE' sections give concrete conditions: use when unsure of network name/alias or when filtering by VM/type/availability; avoid when you already know the exact network and need live data. This directly routes the agent away from alternatives like portal_evm_query_transactions and portal_get_network_info.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the baseline burden is lower. The description adds valuable behavioral context: ambiguity is kept explicit, results are source-backed rather than guessed, and the tool maps symbols to token-list addresses and disambiguates bridged variants. This meaningfully informs agent expectations 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 longer than average but well-structured with clear section headers and scannable bullets. Every section earns its place, and the critical usage guidance is front-loaded. There is minor redundancy between the 'COMMON USER ASKS' examples and the later 'EXAMPLES' block, but the latter adds JSON payloads, so the repetition is acceptable.

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 multi-kind resolver with network scoping and ambiguity handling, the description is unusually complete. It covers when to use the tool, when not to, concrete request examples across four kinds, and key behavioral nuances like source-backed addresses and explicit ambiguity. The output schema handles return-value documentation, so nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value with concrete JSON examples and semantic clarifications: 'query' can be a symbol, alias, or even 'bored apes'; 'network' can be an alias like 'base' or 'arbitrum-one'; 'kind' ranges from token to hyperliquid_coin. These examples make parameter usage tangible beyond the schema's field descriptions.

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

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

The description opens with a specific verb and resource: 'Resolve user-facing blockchain entities into query-ready identifiers.' It names concrete domains (token symbols, contract aliases, protocol names, pool identifiers, Hyperliquid coins), which clearly distinguishes it from sibling query and analytics tools that consume already-resolved identifiers.

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 'FIRST CHOICE FOR', 'WHEN TO USE', and 'DON'T USE' sections. It tells an agent exactly when to call this tool (user names a symbol/contract/protocol needing an address) and when not to (when exact address/pool id/protocol slug/coin filter is already available). This is exemplary 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 declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds value by explaining that a successful result can open in the SQD Blockchain Activity Explorer and that the result being ready does not prove the host rendered it. It also notes the analytic scope rather than raw records. This is useful but not exhaustive behavioral detail, hence 4 rather than 5.

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

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

The use of labeled sections (COMMON USER ASKS, FIRST CHOICE FOR, WHEN TO USE, DON'T USE, EXAMPLES, MCP APP) makes the description scannable and front-loaded with the core purpose. Some redundancy exists: FIRST CHOICE FOR largely repeats the first WHEN TO USE bullet, and COMMON USER ASKS overlaps with EXAMPLES. Still efficient 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?

Given a 10-parameter tool with a 100%-described schema, read-only annotations, and an output schema, the description covers what an agent needs to decide when to invoke it and how to form a request. It supplies use cases, exclusions, concrete examples, and an app-integration caveat. No crucial selection or invocation context appears to be 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?

Input schema covers 100% of parameters with descriptions, so the baseline is 3. The examples (network, timeframe, include_programs) illustrate valid request shapes, but the main description does not add deeper semantics about modes, cursors, or timestamp formats beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: Get the big picture for Solana throughput, fees, wallet activity, and optional top-program usage. It also draws a clear boundary from raw transaction/instruction records, distinguishing this analytics tool from its 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 explicitly state when to choose the tool (big picture, network health snapshot, throughput/fee/success-rate analytics) and when not to (chart buckets or raw transaction/instruction records). Examples show realistic invocations, so an agent has concrete guidance for correct use.

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