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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses important edge-case behaviors: ambiguous symbols return candidates ordered by verification and supply, symbols covering more than 100 coins return only a count due to index limitations, and coins published after the sync date are found only by a bounded live scan. This is substantial behavioral context an agent needs to interpret results correctly.

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

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

The description is front-loaded with purpose and then covers input formats and edge cases in a logical order. It is slightly dense but every sentence carries necessary information; no filler. A 5 would require even tighter phrasing, but this is well-structured for the complexity.

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

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

The tool has no output schema, so the description must convey what the response contains; it lists the main data fields and the ambiguous_symbol/count outcomes. It does not detail error responses or how to use candidates, but the provided information is sufficient for an agent to decide whether to call it and how to interpret common results. A 5 would require a bit more on response handling.

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 meaningful semantics for the query parameter by explaining how ambiguous symbols are resolved (candidate ordering), the >100-coin count-only behavior, and the sync-date/live-scan limitation. This goes beyond the schema's simple format description, justifying a 4.

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 a comprehensive analysis of a Sui token in one call' and enumerates the included data (metadata, price, 24h change, supply, top 5 holders). This clearly distinguishes it from price-only or balance-only siblings, and the 'Recommended for token research' label adds explicit intent.

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 marks the tool as recommended for token research and the schema description explicitly routes partial-name or symbol-part lookups to search_token. It does not enumerate when to prefer siblings like get_token_prices or get_balance, but the comprehensive-analysis scope and the one exclusion provide adequate usage guidance.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false. The description adds context by explaining the session-level effect: 'Enabled tools are callable at once.' It also warns against rebuilding tools manually, which is behavioral guidance. It does not contradict annotations and provides additional useful context beyond the simple read-only flag.

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

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

The description is long but well-structured. It front-loads the core instruction and trigger condition, then explains parameter usage, and finally lists the profiles with their tools. Each sentence serves a purpose, though the tool lists make it verbose. The structure is logical and scannable, so it earns a 4 rather than a 3.

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 meta-tool with multiple profiles and many sub-tools, the description is comprehensive. It covers when to use it, how to use it, what each profile includes, and the immediate effect (tools become callable). No output schema exists, and the description appropriately explains the outcome. Nothing critical is missing for an agent to correctly invoke it.

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

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

Although the schema already includes descriptions for both `profile` and `profiles`, the description goes far beyond by enumerating the exact tools available under each profile (e.g., forensics, developer, market). This mapping is not present in the schema and gives the agent the ability to decide which profile to enable based on the needed tool. This adds substantial semantic value beyond the schema's basic 'profile to enable' note.

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

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

The description clearly states the tool's purpose: 'Turn on more Sui tool profiles for this session.' It distinguishes itself from the sibling read/data tools by being a meta-tool that enables other tools. It also clarifies the context ('when a tool you need is not in your list'), making it unambiguous what it does and when it applies.

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

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

The description gives explicit usage guidance: 'When a tool you need is not in your list, call this first: it is disabled, not missing. Do not rebuild a tool by hand.' It also specifies how to pass parameters ('Pass `profile` or `profiles`: one name, several, or 'all''). This clearly tells the agent when to invoke this tool and how to use it, with 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?

Beyond the readOnlyHint annotation, the description discloses important behavioral traits: it searches every pool across multiple protocols and fee tiers, matches pairs in either order, and reports token_a/token_b as the pool's own order read from its type. 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?

Three focused sentences: primary purpose first, search scope second, and follow-up tool third. No filler or redundant restatement of the schema.

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

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

The description covers search scope, token ordering semantics, and the recommended next step via get_pool_stats, which implies the result contains pool_id. However, with no output schema, the exact return shape is not fully explicit, leaving a minor gap for an agent predicting the response.

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 covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra meaning for token_a/token_b by stating the pair is searched in either order and that returned token order is the pool's type order, which helps an agent pass arguments correctly.

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

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

The first sentence, 'Find DeFi liquidity pools by token pair,' states a specific verb and resource. It then names the exact protocols searched (Cetus, DeepBook v2/v3, Turbos) and clarifies pair-order semantics, distinguishing it clearly from the sibling list.

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

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

The description gives clear context for when to use this tool by explaining its exhaustive search behavior across protocols and fee tiers, and it directs the agent to 'get_pool_stats on a returned pool_id for detailed stats,' showing the follow-up path. It doesn't explicitly state exclusions (e.g., when a pool ID is already known), but the guidance is otherwise 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 declare readOnlyHint and openWorldHint, and the description enriches this with detailed behavior: the distinction between coin_balance and address_balance, exclusion of staked and DeFi funds, reconstruction mechanics, null fields, and the meaning of 'complete' and 'reached_checkpoint'. No contradiction with annotations 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 long but every sentence carries essential information. It is well-structured, starting with the core purpose, then diving into nuances and edge cases. No filler or tautology; each clause adds value to an agent's understanding.

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

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

For a complex tool with 7 parameters and no output schema, the description covers all critical scenarios: current vs historical reads, reconstruction behavior, null cases, the meaning of anchors, and relationships to other tools. An agent has sufficient knowledge to invoke it correctly in any situation.

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

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

Schema coverage is 100%, but the description adds substantial semantics beyond the schema: it explains the effect of 'at' and 'at_checkpoint', the meaning of 'balance' vs 'coin_balance' vs 'address_balance', the max_transactions behavior and its impact on completeness, and the alias relationship between 'address' and 'owner'. This far exceeds the baseline for full schema coverage.

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

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

The description specifies the exact operation: get the liquid balance of one coin type for a Sui address or object, with a default coin (SUI). It clearly distinguishes from sibling get_wallet_overview (all coins at once) and provides context on what is excluded (staked SUI, DeFi). The purpose is unmistakable.

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

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

Explicitly states when to use alternatives: 'For every coin at once, use get_wallet_overview' and 'pair it with get_staking_summary and get_defi_positions before concluding anything.' It also clarifies when reconstruction is used and its limitations, giving the agent clear decision criteria.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety. The description adds behavioral context beyond annotations: it explains that omitting the epoch returns current epoch info, and passing one returns that specific epoch's details. This is useful behavior not covered by annotations. 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 two sentences with no filler. The first sentence front-loads the action and result fields; the second covers the optional parameter. Every word earns its place. This is an excellent model of concise, well-structured documentation.

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

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

For a simple read-only tool with two optional parameters and no output schema, the description is nearly complete. It lists the return fields and explains the epoch behavior. It doesn't describe the output format or types, but that's less critical here given the simplicity. The description gives an agent enough to call it correctly, though a note about default network behavior could be added (though schema already covers it).

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

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

Schema description coverage is 100% – both parameters (epoch and network) are fully described in the schema. The description repeats the epoch behavior but adds no new semantics beyond what the schema already provides. Since the schema carries the heavy lifting, the description contributes minimal extra parameter meaning, hitting the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Get current Sui network info' and enumerates the exact fields returned (chain ID, epoch, checkpoint height, timestamp, reference gas price). This is a specific verb+resource combination that easily distinguishes it from sibling tools like get_object or get_balance, which target different resources.

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

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

The description implies usage for network information queries but does not explicitly contrast with alternative tools or provide exclusion criteria. The optional epoch parameter is explained ('Optionally pass an epoch number to get details for a specific epoch'), but there's no guidance on when to prefer this tool over others. The context is clear enough for basic use, but no explicit when/when-not guidance is given.

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 and openWorldHint=true, so safety is covered. The description adds valuable behavioral context by stating it returns 'extracted position summaries (deposits, borrows, liquidity, fees) instead of raw on-chain data,' disclosing the output processing behavior. This goes beyond annotation data.

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

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

Two sentences, no wasted words. The first sentence front-loads the core purpose and protocol list; the second explains the output format. Each sentence earns its place, and the structure is optimal for quick agent parsing.

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 simple parameters, full schema coverage, and helpful annotations, the description covers the essential information an agent needs: what the tool does, which protocols it scans, and what the response looks like. Minor gaps like pagination or empty-result behavior are not critical for this read-only tool, but slightly more detail on return limits would make it fully complete.

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

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

Schema description coverage is 100%, so the input schema already fully documents both parameters (address and network). The description does not add extra parameter-specific meaning beyond what the schema provides, but it does hint at the wallet-scoped nature of the lookup. Baseline 3 is appropriate.

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

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

The description clearly states a specific action ('Find DeFi positions'), the resource ('owned by a Sui wallet'), and the scope ('across major protocols' with a concrete list). It also distinguishes itself by noting it returns 'extracted position summaries' rather than raw data, which helps separate it from related sibling tools like get_balance or get_wallet_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 implies when to use this tool (when you need DeFi positions across the listed protocols) but doesn't explicitly mention when not to use it or point to alternatives. Given the large sibling list and overlapping tools like get_staking_summary, explicit exclusionary guidance would improve clarity.

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 annotation, the description discloses important behavioral nuances: it extracts NFT display metadata, adds address_balances and kiosk_cap_holder on latest version only, and warns that content.owner is self-declared and not kept in sync with actual KioskOwnerCap transfers. This is exactly the kind of context an agent needs to interpret results correctly.

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

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

The description is front-loaded with the core purpose and return fields, then adds precise caveats about version-sensitive data. Every sentence earns its place; the length is justified by the non-obvious behavior around address_balances and kiosk_cap_holder.

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?

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly: type, owner, version, content, digest, display metadata, and the version-dependent extra fields. It also covers the tricky current-state vs. historical-version distinction. Nothing essential is missing for an agent to invoke and interpret this tool correctly.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds extra meaning for the version parameter by explaining that extra fields are only present for the latest version and that current-state fields should not be read for historical versions. This goes beyond the schema's minimal 'Specific version to fetch.'

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 a Sui object by its ID.' It clearly distinguishes itself from sibling tools like list_owned_objects or get_transactions by focusing on fetching a single object and enumerating its returned fields.

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

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

The description gives clear context for when to call this tool: when you have a Sui object ID and want its details. It also explains the version-dependent behavior, telling the agent that address_balances and kiosk_cap_holder are only meaningful for the latest version. It does not explicitly name alternatives or exclusion criteria, but the usage context is strong.

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

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

Annotations already flag readOnlyHint and openWorldHint, and the description adds valuable behavioral context: staked SUI is invisible to get_balance, staking ties the wallet to a specific validator, and the return contents are summarized. 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 two sentences with no filler. The return-value summary is front-loaded, and the usage rationale follows naturally. Every sentence contributes distinct 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?

Even without an output schema, the description states the output shape, the fields returned, the total principal, and when calling is worthwhile. Combined with full schema coverage and the safety annotations, nothing essential is missing for a read-only 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 address and network are already fully documented in the schema. The description does not add parameter-specific meaning beyond the schema, which lands at the baseline.

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

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

The description starts with a specific verb and resource ('Get a wallet's staking positions') and enumerates exactly what the tool returns: every StakedSui object with validator pool, principal, activation epoch, and total principal. It also explicitly contrasts itself with the sibling get_balance, so an agent can tell them apart.

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

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

It names the conditions to call (investigation or net-worth check) and the reason: staked SUI does NOT appear in get_balance, so a wallet can look nearly empty while holding a large staked position. This explicitly gives when-to-use and cites an alternative, providing 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses a detailed source fallback chain (Aftermath → DefiLlama → Pyth), conditional historical behavior based on PYTH_API_KEY, null handling for 24h change, output fields (source, confidence, sample time), and an `unpriced` list with reasons. It also warns that unverified coins are never matched by symbol, which is critical for correct invocation. 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 a focused block with the core operation front-loaded in the first sentence. Every subsequent sentence adds distinct, non-redundant information: source ordering, API key condition, output shape, unpriced handling, and coin type requirement. There is no filler or repetition of schema details.

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

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

Despite having no output schema, the description compensates by explaining return fields (source, confidence, sample time, unpriced with reasons) and the precise inputs needed (full coin type strings, optional `at`). Combined with complete schema coverage of all parameters, an agent has all information required 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 baseline is 3. The description adds meaningful nuance beyond the schema: it explains that `at` toggles historical pricing, requires full coin type strings, and clarifies that unverified coins are only priced by exact coin type, not symbol-matched feeds. This extra guidance raises the score above baseline.

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

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

The description names a specific verb and resource: 'Get USD prices for Sui tokens,' and immediately specifies the temporal behavior ('current by default or at a past moment when `at` is set'). This leaves no ambiguity about the tool's function, and no sibling tool covers token pricing, so the purpose is distinct and 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 gives clear context on when to use each mode ('current by default or at a past moment when `at` is set') and notes that no API key is needed, which informs an agent's decision to use this tool without external setup. It does not explicitly name alternative tools, but no sibling offers price lookup, so this is a minor omission rather than a practical gap.

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

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

Annotations only indicate readOnlyHint and openWorldHint, so the description carries the burden of disclosing behavior. It does so richly: explaining how protocols are identified (events and Move calls), the meaning of protocols_from_events_only, address-balance movements, gas source, created_for, coins_delivered_to, and mutated_capabilities. This far exceeds the annotations and provides deep insight into what the tool does and why.

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

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

The description is a long, dense paragraph with many clauses and qualifiers. While it is packed with information, it is not concise and could benefit from bullet points or clear separation of fields. The first sentence is clear, but the subsequent flow is hard to parse quickly. It is comprehensive but sacrifices readability for completeness.

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 (many output fields and nuanced behaviors) and the absence of an output schema, the description does an excellent job of covering all essential aspects. It explains each major return field and its implications, including edge cases like obfuscated wrappers, address-balance movements, and capability mutations. Nothing critical appears missing for an agent to correctly understand and invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema, particularly for max_event_field_bytes, by explaining the default behavior (all fields returned) and when to set it (intentional bounding) and that skipped fields are reported. It also clarifies that the digest is Base58 and network defaults to mainnet, though these are already in the schema. Overall, the description enriches parameter understanding.

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

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

The description clearly states the tool gets a Sui transaction by digest and enumerates the specific return fields (sender, status, gas, balance changes, protocol-aware decoded actions, events with decoded fields). This distinguishes it from siblings like get_transactions (which likely lists multiple) and query_transactions (which searches/filters). The unique selling point—no need to hand-write GraphQL for event fields—is explicitly called out.

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 strong contextual cues about what the tool returns, allowing an agent to infer when it's appropriate (e.g., when needing decoded events or protocol-aware actions). However, it does not explicitly name alternatives or state when not to use it, unlike the high-caliber example that named a specific sibling. The guidance is clear but not as explicit.

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

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

Annotations only supply readOnlyHint=true and openWorldHint=true; the description adds substantial behavioral context beyond them: pagination mechanics (order, next_cursor, oldest_shown/newest_shown), address_poisoning check scope, the subject_flow vs token_flow distinction, counterparty truncation at 25, and the alias scan's 5-minute cache and incomplete-scan flag. No contradiction with annotations.

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

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

The description is long, but it is front-loaded with the purpose and recommendation, then follows a logical flow (ordering, pagination, decoding, row fields, edge cases). Every sentence carries unique information for a complex tool with no output schema, so the length is earned rather than padded.

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 no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: page metadata (order, timestamps, next_cursor), row semantics (subject_flow vs token_flow, counterparties, coin_verified), and edge cases (signed_as_alias, alias_scan_as_of, signed_as_alias_unavailable). Given the tool's complexity (5 parameters, no output schema), 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 covers 100% of parameters so baseline is 3, but the description adds real semantic value beyond the schema: it explains that 'order: oldest' starts from the address's first transaction, and that next_cursor must be passed with the same order to continue. This clarifies cross-parameter dependency that the schema leaves implicit.

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

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

The first sentence states a specific verb and resource ('Get decoded transaction history for a Sui wallet') and immediately lists the distinctive outputs (protocol names, action descriptions, token flow). It differentiates from siblings by emphasizing 'decoded' and explicitly pointing to query_transactions as the alternative, so an agent can tell them apart.

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

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

The description opens with '(Recommended for wallet activity)' and later states 'Prefer this over query_transactions when exploring what a wallet has been doing,' naming the specific sibling and the condition that selects this tool. This is explicit when-to-use guidance with an alternative named.

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

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

Annotations already provide readOnlyHint and openWorldHint, lowering the bar. The description adds valuable behavioral detail: the not_found handling for unreadable digests, the batch performance benefit, and the exact list of returned fields (sender, status, timing, balance changes, Move call targets, events with decoded fields, protocols). This goes beyond annotations and gives the agent a clear expectation.

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 core capability, but it is somewhat verbose, blending purpose, return details, and usage guidance into a long paragraph. It earns its length by covering multiple important aspects, but it could be tightened without losing value.

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

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

For a batch tool with two parameters and no output schema, this description is remarkably complete. It specifies the batch limit (50), the handling of missing digests (not_found), the content of the response per transaction, and the exact routing rule versus the single-transaction sibling. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are already well-documented in the schema. The description adds minimal extra semantic detail beyond restating the batch concept and the not_found behavior. It does not introduce new parameter-level nuance, so a baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('Read') with a specific resource ('up to 50 Sui transactions') and the required parameter ('digests'). It explicitly contrasts with siblings like get_transaction, making its purpose unambiguous.

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

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

It gives explicit when-to-use guidance: 'Use this whenever you hold several digests at once' and explicitly names the alternative: 'For ONE transaction, or for a transaction with more than 50 events, prefer get_transaction.' This is exactly the level of routing an agent needs.

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

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

Annotations already cover read-only and open-world hints, lowering the burden. The description adds meaningful behavioral detail by listing what the overview includes (token balances, SuiNS name, staked SUI, kiosk/NFT count, recent transactions) and how include_prices changes the output. 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 front-loaded with the most important usage signal ('Recommended first tool for wallets'). Every sentence earns its place: what it returns, how to get prices, and when to use it.

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 overview tool, the description is largely complete: it lists return contents, explains the optional price flag, and gives usage positioning. Parameters are fully covered by the schema, and annotations cover safety. Minor gaps like output shape or pagination are acceptable given no output schema.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds only marginal reinforcement for include_prices ('Set include_prices=true for USD values'), which does not meaningfully exceed the schema's existing description.

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

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

The description uses a specific verb and resource ('Get a comprehensive overview of a Sui wallet') and enumerates the exact contents returned. It distinguishes itself from siblings by positioning itself as the recommended first tool and the entry point before drilling into specific 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 clearly states when to use it: 'Recommended first tool for wallets' and 'Start here before drilling into specific tools.' It gives clear context for selection, though it does not explicitly name sibling alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds valuable context: it returns a type classification with a contextual summary (balance + SuiNS for wallets, module list for packages, stake info for validators). This goes beyond the annotations and helps the agent understand what to expect.

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

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

The description is concise and front-loaded with the most important information ('Recommended first step'). It uses a clear structure: purpose, return value, and usage guidance. Every sentence earns its place.

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

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

For a read-only classification tool with 2 parameters and full schema coverage, the description is quite complete. It explains the return value and how to use it. The only minor gap is that it doesn't explicitly state what happens if the address is invalid or not found, but that's a minor issue given the openWorldHint annotation.

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 both parameters. The description doesn't add much beyond what the schema provides, but it does imply the address parameter is the main input. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: to identify what a Sui address is (wallet, package, validator, or object). It uses a specific verb ('Identify') and resource ('Sui address'), and distinguishes itself from siblings by being the recommended first step before deciding which other tools to call.

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

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

The description explicitly says to use this tool before deciding which other tools to call, positioning it as a triage step. It also lists the categories it can classify, which helps an agent know when it's appropriate. It doesn't explicitly name alternatives, but the context of being a first step is strong 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 openWorldHint=true, so the safety profile is known. The description adds meaningful behavior beyond that: it scans both kiosks and direct-owned objects, deduplicates, and returns counts. This tells the agent what data sources are covered and what output shape to expect. It does not disclose pagination or error behavior, but the added context is sufficient.

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

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

The description is short and front-loaded, with the core purpose in the first sentence and behavioral detail in the second. The third sentence 'Backed by GraphQL' adds little decision-relevant information and is arguably expendable, keeping this from a 5. Overall, it is tight and readable.

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

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

With two parameters, full schema coverage, and no output schema, the description adequately explains the return shape (deduplicated collection types with counts) and coverage scope (kiosks plus direct-owned objects). It omits only minor details such as ordering or empty-result behavior, which are not essential for correct invocation.

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

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

Schema description coverage is 100%, with address and network both documented. The description adds no new parameter-level meaning beyond restating the wallet ownership context. Baseline 3 is appropriate because the schema already carries the parameter documentation burden.

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

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

States a specific verb and resource: 'Get a lightweight summary of NFT collections owned by a wallet.' The detail about returning deduplicated collection types with counts distinguishes it from sibling tools like list_nfts, which likely returns individual NFTs. The scope is clear and immediately actionable.

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

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

The description implies when to use it: when the agent needs a wallet's NFT collection summary rather than individual NFTs or full object listings. However, it does not explicitly name alternatives like list_nfts or list_owned_objects, nor does it state when not to use this tool. Context is clear but exclusion guidance is missing.

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

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

Annotations only state readOnlyHint=true and openWorldHint=true. The description adds meaningful behavioral context: GraphQL-backed with single query per kiosk page and no fullnode rate-limit risk, pagination semantics (next_cursor omitted when enumeration is complete), return contents (display metadata plus raw Move structs), and limit behavior. No contradiction with annotations; rich transparency is provided.

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

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

The description is longer than average but every sentence carries operational value: scope, return shape, backend rationale, pagination details, limit, and alternative tool. Information is front-loaded with the core purpose before implementation details. Slight redundancy with schema (e.g., limit default) exists, but the overall structure is 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?

Given there is no output schema, the description adequately covers expected return fields (display metadata and raw Move contents) and pagination contract. It also names the network default and the alternative tool for count-only needs. For a read-only paginated list tool, nothing critical is missing for an agent to select and 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 coverage is 100%, so each parameter is already documented. The description adds practical semantics beyond the schema: cursor is 'from a prior response', next_cursor omission signals completion, and limit is capped at 1000 with default 50. This improves an agent's ability to form correct pagination loops, justifying a score above the baseline 3.

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

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

The description uses a specific verb-resource pair: 'List NFTs owned by a wallet', and expands scope with 'including kiosk-stored NFTs'. It clearly distinguishes this from sibling list_nft_collections (explicitly a count-only summary) and from list_owned_objects (which covers all objects, not just NFTs). A model can infer exactly what this tool does without opening the schema.

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

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

The description explicitly recommends this tool for NFTs, explains the pagination invocation pattern, and names the cheaper alternative list_nft_collections. However, it does not contrast with list_owned_objects or explain when to prefer that sibling instead. The guidance is strong but not exhaustive across all relevant siblings.

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

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

Annotations already mark the tool as read-only, so the bar for behavioral transparency is lower. The description adds useful context by noting that this tool lists 'raw' objects and does not resolve kiosk storage or extract display metadata, which sets expectations beyond the structured annotations.

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

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

The description is only two sentences with no filler. The core function is front-loaded in the first sentence, and the alternative routing is packed efficiently into the second. Every sentence earns its place.

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

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

For a read-only listing tool with a complete schema, the description covers the essential purpose, filtering, pagination, and alternatives. It does not describe the return shape, but the absence of an output schema and the presence of full parameter descriptions make this acceptable.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters including owner, address alias, limit, cursor, network, and object_type. The description mentions 'optional type filter and pagination' but does not add meaningful detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' and resource 'raw objects owned by a Sui address,' and explicitly differentiates from list_nfts and get_wallet_overview. This allows an agent to distinguish the tool from sibling tools at a glance.

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 routing guidance: use list_nfts for NFTs and get_wallet_overview for wallet summaries, implying list_owned_objects is for general raw object queries. This directly tells the agent when to use this tool versus alternatives.

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

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

The description is unusually transparent about pagination ('order', 'oldest_shown'/'newest_shown', 'next_cursor'), version-matching behavior, and the PTB over-attribution pitfall. However, it references `function_scope` as if it were a usable parameter even though it is not present in the schema, which introduces confusion.

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

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

The description is front-loaded with the core purpose and organized into digestible paragraphs with clear warnings. It is longer than typical, but most sentences earn their place; the `function_scope` sentence is unearned and inaccurate, keeping it from a perfect score.

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

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

For a 12-parameter tool with no output schema, the description covers the return-page format, pagination contract, filter constraints, version semantics, and attribution warning, which is strong contextual coverage. The only meaningful gap is the misleading `function_scope` reference; otherwise an agent would have enough information 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?

The schema already documents all parameters, so the bar is high, and the description adds real value: mutual exclusivity among affected_address/affected_object/function, exact-version versus all_versions behavior, and why include_functions matters for attribution. The phantom `function_scope` mention slightly weakens an otherwise strong parameter explanation.

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 Sui transactions with specific filters...' and enumerates the filter dimensions. The word 'raw' plus the explicit pointer to get_transaction_history separates it from the wallet-activity sibling without needing the schema.

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

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

It gives direct routing: 'For human-readable wallet activity, prefer get_transaction_history instead' and 'prefer the protocol's own events (query_events) when measuring per-protocol flow.' It also states the hard constraint that only ONE of affected_address, affected_object, or function may be used, and when to enable all_versions and include_functions.

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 and openWorldHint annotations, the description discloses concrete behaviors: unresolvable names return null with a `name_note` explaining why, and malformed names produce errors. The identity warning is exceptional, informing the agent that SuiNS names are self-chosen, unverified, and potentially deceptive — critical context for an investigative 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 front-loaded with the primary purpose and parameter constraint, then immediately covers edge cases and the identity warning. Every sentence earns its place: the warning, while long, is essential behavioral context that prevents misuse. No redundancy or filler.

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

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

For a two-mode lookup tool with no output schema, the description covers all critical aspects: input requirements, return behavior (null vs error), and the trust implications of SuiNS names. The network parameter is fully specified in the schema. Nothing an agent needs to correctly invoke and interpret this tool is missing.

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

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

The schema already describes all three parameters (100% coverage), so the baseline is 3. The description adds meaningful value by stating the mutual exclusivity constraint (at least one of name/address) and clarifying edge-case behavior for the 'name' parameter, which goes beyond the bare schema 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 states a specific action: resolve a SuiNS name to an address or reverse-lookup an address to a name. It names the resource (.sui domain) and the two modes (forward/reverse), which clearly distinguishes it from sibling tools like get_object or identify_address without ambiguity.

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

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

It explicitly states that at least one of 'name' or 'address' must be provided, which is a key usage constraint. It also describes valid vs invalid inputs (registered/expired names resolve to null, malformed names are errors). However, it does not explicitly compare to alternatives or state when not to use this tool, so it lacks explicit exclusions.

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