Arcadia Finance

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, and readOnlyHint=false. The description adds meaningful context beyond them: it uses a local private key from a PK env var and is intended only for dev, with production routed elsewhere. It does not elaborate on irreversibility or failure behavior, but the annotations already carry the destructive profile.

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 concise sentences with the most important safety information first. Every sentence adds value: dev-only scope, production alternative, and input source.

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 destructive and open-world, but the description covers the critical dev-only warning, private-key source, and production alternative. Parameter details are fully covered by the schema, and an output schema exists, so no further return-value explanation is required.

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 to, data, value, and chain_id. The description adds useful workflow context by saying the transaction object comes from any write_* tool, but it does not add parameter-level meaning beyond the schema.

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

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

The description states a specific verb and resource: sign and broadcast an unsigned transaction. It explicitly distinguishes this tool from sibling write_* tools by saying it takes their returned transaction object and submits it onchain.

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 an explicit when-to-use condition (after a write_* tool returns an unsigned transaction), an explicit when-not-to-use condition (production), and names concrete alternatives (Fireblocks, Safe, Turnkey). The DEV ONLY warning is front-loaded.

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 readOnly/idempotent/openWorld, but the description adds substantial behavior beyond them: the full status enum, which accounts are silently omitted, the failed_accounts error semantics and retry advice, what opens_at means, the absence of calldata/prices/simulation, and the Robinhood empty-list behavior. This is exactly the context annotations cannot convey.

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

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

Purpose is front-loaded and every paragraph carries operational content, but the description is dense and long, with an especially convoluted sentence about automations still running on old Slipstream managers. Nothing is truly waste, yet readability suffers compared to a tighter phrasing.

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 an output schema existing, the description covers the edge cases an agent actually needs: empty-vs-failed distinction, excluded accounts, chain coverage, and handoff to the write tool. Nothing required to call or interpret it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the wallet/account exclusivity. The description repeats that exclusivity and the chain meaning (Robinhood yields an empty list) but adds little syntax or format detail beyond the schema, so baseline 3 applies.

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 precisely what is checked: Arcadia accounts with upgradeable Aero positions (Slipstream V1->V3, old AERO), with scope qualifiers (chains, staked or not). It explicitly names the sibling it is not — 'For the plan and the transaction call write_account_aero_upgrade' — so the agent can distinguish check from execution without opening a 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?

Gives the routing rule between wallet_address and account_address, states when to escalate to write_account_aero_upgrade (including the specific case where read_asset_manager_current shows only metadexcl_v1 positions), and warns that an empty accounts list only means 'nothing to do' when failed_accounts is also empty. Alternatives and conditions are explicit, not inferred.

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 safety (readOnly, idempotent, non-destructive, openWorld), yet the description still adds real value: snapshot ordering ('oldest first'), timestamp units (unix seconds), value units (USD, human-readable not raw), and the crucial interpretation that an empty history is not a failure. It stops short of mentioning any cap on the `days` window or whether the series is paginated/truncated for long ranges.

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

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

Three short sentences, front-loaded with the core action, then output shape, then an edge-case clarification. Nothing is redundant and the empty-history note earns its place by preventing a false-negative interpretation.

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

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

With an output schema present, the description need not restate structure, yet it still disambiguates the two fields an agent would most likely misread (unix seconds, USD human-readable) and explains the empty-result case. Nothing needed to invoke or interpret the call 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% — all three parameters (account_address, days, chain_id with its chain list) are fully documented in the schema. The description adds no parameter-level detail beyond that, so the baseline of 3 is appropriate; its unit clarifications describe the response, not the inputs.

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 — historical net value for an Arcadia account — with scope (over time, time series of snapshots). It is clear what the tool does, but the close sibling read_account_pnl (also an account-metric time read) is never named, so an agent must infer the boundary from tool names alone.

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

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

Usage is only implied through 'Useful for charting account performance over a period,' which gives a motivation but no rule for when to pick this over read_account_pnl or read_account_info. No exclusions or prerequisites are stated.

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 declare read-only/idempotent/non-destructive; the description adds substantial behavioral context beyond them — the health-factor formula and its 1/0/<0 semantics, the shape of the automation object including inferred_intents, merkl state and deprecated_managers, and that superseded managers are cleared on save. That is exactly the depth a state-reading tool needs.

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?

Front-loaded with the overview and the health-factor explanation, but it then spends many sentences enumerating ten dex_protocol identifiers and spelling out unit conversions for return fields that the output schema already covers. Valuable but not tightly earned — a third of the text is reference material repeated per call.

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 tool over a complex DeFi account state, nothing an agent needs is missing: the interpretation of health_factor, the unit conventions for raw vs _usd fields, the meaning of the automation sub-object, and the sibling routing are all present. Any over-explanation of returns is redundant rather than incomplete.

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 chain_id documenting the accepted chain values and account_address defined, so the schema carries the parameter burden. The description adds no parameter-level detail (it discusses units for returned fields, not inputs), which places it at the 3 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?

States a specific verb ('Get full overview of an Arcadia account') and enumerates exactly the resources returned: health factor, collateral value, debt, deposited assets, liquidation price, automation status. This clearly separates it from siblings read_wallet_accounts, read_account_history and read_account_pnl.

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?

Names alternatives with explicit conditions: use read_wallet_accounts to list accounts for a wallet, read_asset_manager_current for full decoded per-manager config, and write_account_automations to configure or clear automations. The agent knows which sibling to pick without inferring.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: results are lifetime totals, negative cost_basis means net profit withdrawn, and USD versus raw token units are distinguished.

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 dense and front-loaded with the core PnL meaning, then quickly clarifies units and sign conventions. It is slightly packed but every sentence contributes useful 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?

An output schema exists, so return shape need not be fully re-explained, but the description still adds critical interpretation of fields and units. It is nearly complete for this read tool, with only sibling routing guidance 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 both parameters are already documented, including chain_id defaults and accepted values. The description adds no additional parameter meaning, which is appropriate given the schema's completeness.

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

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

States a specific verb and resource ('Get PnL ... for an Arcadia account') and distinguishes the scope as lifetime cost-basis and yield reporting. It is clearly separable from sibling reads like read_account_info and read_account_history.

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

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

Usage is implied by the name and description, but the description does not explicitly say when to use this instead of read_account_info or read_account_history. No exclusions or alternatives are 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds scope ('supported collateral assets') and hints at return shape ('compact list'), but says nothing about pagination limits, completeness of the list, or chain behavior beyond the schema default.

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 short sentences, front-loaded with purpose, followed by return shape and routing. Every sentence carries a distinct piece of information with 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?

With a full output schema, rich annotations, and complete parameter descriptions, the definition covers what an agent needs to call it correctly. The only modest gap is guidance on whether the returned list is exhaustive and whether chain_id changes the result set meaningfully.

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 both parameters are documented there, including the chain ID enum values. The description's 'use search to filter by symbol substring' merely restates the schema's 'case-insensitive substring match' and adds no new syntax or constraint information.

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 ('List supported collateral assets on Arcadia') and explicitly separates itself from the pricing sibling by name. An agent can distinguish it from read_asset_prices and the pool/strategy list tools without reading any 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?

Gives a concrete routing rule ('For USD prices, use read_asset_prices') and explains the search parameter's purpose. It lacks an explicit when-not condition (e.g. for non-collateral or wallet-held assets), but the alternative is clearly 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 declare readOnlyHint/idempotent, yet the description adds material behavior the agent could not otherwise know: the exact shape of returned manager data, Merkl claim state including unregistered reward tokens, and the critical failure semantic that read_ok=false means the result is unreliable rather than empty. That last point preempts a dangerous misread of an empty-looking response.

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?

Front-loaded with the core action, then the return contents, then the deprecated-manager escape hatch, then the read_ok caveat — a sensible ordering. The middle sentence is a dense parenthetical list of fields, which is slightly heavy but every clause carries information an agent uses.

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

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

An output schema exists, so return values did not need spelling out, yet the description covers the ambiguity an output schema cannot: the deprecated bucket's remediation path and the read_ok=false/empty distinction. For a read-only, two-parameter tool with full annotation coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, with chain_id even enumerating chain values inline, so the description is not required to carry the parameters. It adds no syntax or format detail for account_address or chain_id beyond stating results are 'on-chain configuration' — baseline 3 for a fully documented 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?

States a specific verb and resource ('Read which asset managers are currently enabled on an account') and scopes the result precisely to active vs. superseded deployments. That active/deprecated split, plus the reference to sibling read_asset_manager_intents via 'the intents they map to', lets an agent distinguish it from the other read_* tools without opening a 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?

Explicitly routes the follow-up action for deprecated managers: 'pass their addresses to write_account_automations_delta to clear them, or run write_account_automations which disables them as part of the save' — a genuine when-this-then-that rule with a named alternative. It stops short of stating when to prefer this over read_asset_manager_intents, so it is strong context rather than a full decision tree.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description adds real value by explaining the two return modes (catalog-only vs. per-account availability with blocking compatibility rules) and the dependency that position_id requires an account scoping. It does not mention rate limits or result size, so not a 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?

Three tight sentences, catalog described first, then the two optional escalation paths, then a closing clarification of the default. No wasted words.

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

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

For a read-only 3-parameter listing tool with a full output schema and complete annotation coverage, everything an agent needs to choose parameters and predict the response shape is present.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining that account_address toggles an entirely different response mode rather than just filtering, and that position_id further narrows that mode. chain_id is left to the schema, which is reasonable.

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 ('List the automation intents Arcadia supports') and immediately narrows scope by noting it returns the parameters each intent accepts. This cleanly separates it from sibling read_asset_manager_current (current state) and write_account_automations (mutation) 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?

Explicitly gives conditional usage: 'Pass account_address to also get per-account availability', 'Pass position_id as well to scope availability', and 'Without account_address this returns the catalog only.' It never names a sibling tool as the alternative, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered structurally. The description adds the useful detail that multiple addresses can be batched in one call and that results are keyed by address, but says nothing about behavior on unknown/unsupported addresses, cross-chain price differences, or rate limits — meaningful for an openWorld 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?

Three short sentences, front-loaded with the core purpose and with zero filler. The third sentence about the return shape is slightly redundant given an output schema exists, but it does not bloat the definition.

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-param read with rich annotations and a declared output schema, the essentials are present, but the description never mentions that prices are chain-scoped or that chain_id defaults to Base — a real omission given the tool prices assets across four chains. Edge-case behavior (unpriced assets) is also unaddressed.

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 both parameters are documented there, including the enumerated chain IDs, so the description is not required to compensate. It restates the comma-separated address format (already in the schema) but adds nothing to clarify chain_id's default of 8453 or its effect on pricing.

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 USD prices' for 'asset addresses' — which is concrete and clearly separable from siblings like read_asset_list (enumeration) or read_wallet_balances (holdings). It stops short of naming or contrasting those siblings explicitly, so an agent must infer the boundary itself.

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

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

The description implies the usage context (batch price lookup) and explains how to supply multiple addresses, but gives no when-to-use/when-not guidance, no pointer to read_asset_list for discovering addresses, and no mention of when chain_id matters.

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, idempotentHint, and openWorldHint, so safety is covered; the description adds the valuable sequencing trait that this should be fetched ahead of multi-step flows. It stops short of describing output size/shape, but an output schema exists to cover that.

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?

Front-loaded with the action and the precondition in the first two sentences. The trailing topic list duplicates the enum descriptions, so it is slightly longer than strictly necessary, but no sentence is pure 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 single optional-enum documentation tool with 100% schema coverage and an output schema, the description supplies everything an agent needs: what it returns, when to invoke it, and how to pick a topic.

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% with an enum and per-value descriptions, so the baseline is 3. The description adds marginal value by framing each topic by its use case (e.g., 'selection – how to evaluate and parameterize strategies'), though it largely restates the 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?

States a specific verb and resource ('Get Arcadia workflow guides and reference documentation') and enumerates the concrete content available (addresses, catalog, templates, parameters). It is clearly distinguishable from the read_/write_ data tools in the sibling list, which return live state rather than guidance.

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 says when to call it ('before multi-step workflows – opening LP positions, enabling automation, closing positions') and when you need specific data like contract addresses or strategy parameters. This gives the agent a clear trigger condition that maps onto the write_* workflow 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety is fully covered structurally. The description adds only the pagination note, which is mild extra context. An output schema exists, so return-value explanation is not required, making 3 appropriate.

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 short sentences with no filler; the core capability comes first and the disambiguation follows. Every clause carries information an agent needs.

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?

Rich annotations plus a full output schema mean the description need only state purpose, pagination, and the sibling branch, all of which it does. Nothing required to call this 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%, and both limit and offset carry their own defaults and meanings there. The description's '(paginated)' merely gestures at this without adding syntax, bounds, or ordering details beyond the schema. Baseline 3 is correct.

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 ('Get'), a specific resource ('Arcadia points leaderboard'), and a scope qualifier ('paginated'). It explicitly separates itself from read_wallet_points, so an agent can route between the two without opening either 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?

Names the alternative tool (read_wallet_points) and the condition that selects it (a specific wallet's points balance), which is the key routing decision among the siblings. It does not mention other exclusions, such as whether date ranges or filtering are unsupported, but the primary branch is clear.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered and the description need not restate it. The description adds that the response includes APY history over time, hinting that the time window shapes the payload, but says nothing about rate limits, cost of wide `days` windows, or error behavior for unknown addresses/unsupported chain IDs.

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 short sentences, front-loaded with what the tool returns, then the use case, then the prerequisite tool. Each sentence carries distinct information with no restated annotations 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?

An output schema exists, so return-shape explanation is unnecessary, and the schema handles all parameter detail. What remains thin is behavioral edge cases (invalid pool address, unsupported chain) and the fact that pool_address is required, but for a read-only lookup tool the description is otherwise sufficient to call 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% – all three parameters, their defaults, and the valid chain IDs are documented in the schema. The description only loosely reinforces `days` via "APY history over time" and adds no syntax or constraint detail beyond the schema, so baseline 3 applies.

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?

Specific verb+resource ("Get detailed info for a single lending pool") with the scope narrowed to one pool and the payload characterized (APY history over time). It also names the sibling read_pool_list for discovery, so an agent can separate it from the list tool and from read_strategy_info without opening a 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?

"Use read_pool_list to discover pool addresses" gives an explicit prerequisite and routes the agent to the correct sibling, and "comparing pools" clarifies the analytical use case. There is no explicit when-not guidance (e.g., whether it is worth calling for many pools at once), so it stops just short of full coverage.

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 goes beyond standard structural details by defining the business metrics (TVL, utilization, available liquidity) and providing critical behavioral constraints on data representation (all rates are decimal fractions, e.g., 1.0 = 100%). This adds high value to the AI's interpretation of the expected output data.

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

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

The tool uses two concise sentences that front-load the purpose and then immediately address usage and differences from siblings, achieving maximum information density 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?

Given that this is a read-only tool (confirmed by annotations) and the input schema is small, defining the key fields and how they are scaled (decimal fractions) provides the AI with all the necessary context to correctly interpret the results.

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?

While schema coverage is 100%, the description adds semantic value by detailing the specific chains supported by the 'chain_id' parameter (Base, Unichain, Optimism, or Robinhood). This helps the agent decide if the default or a specific override is necessary.

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 states its function is to 'List all Arcadia lending pools.' It clearly distinguishes this action from the sibling tool, read_pool_info, by stating the alternative is for specific pool APY history.

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

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

It provides explicit guidance on when to use this tool: 'All Arcadia lending pools.' It also provides a clear exclusion/alternative path: 'For APY history on a specific pool, use read_pool_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 that this is a read-only, idempotent, non-destructive, open-world call. The description adds meaningful domain behavior: APY is presented per range width, narrower ranges imply higher APY but more rebalancing cost/risk, and APY values are decimal fractions. It does not discuss error behavior for invalid IDs or chain mismatches, keeping it from a 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 description is three compact sentences: purpose first, then the ID-discovery alternative, then the important APY formatting convention. Every sentence carries actionable information with no filler.

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

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

Given an output schema, read-only annotations, and full schema coverage, the description provides enough context to call the tool correctly. It covers what detail is returned, how to obtain the required ID, and how to interpret APY 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 schema documents chain_id's allowed values and the strategy_id field. The description still adds useful meaning by telling the agent to discover strategy IDs via read_strategy_list, compensating for the otherwise terse 'Strategy ID' schema 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: retrieving full detail for a specific LP strategy by ID. It also enumerates the main contents (APY per range width, pool info, configuration), which clearly distinguishes it from list/recommendation 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?

It explicitly routes ID discovery to read_strategy_list, which is a useful alternative and prerequisite. However, it does not fully specify when to prefer this over read_strategy_recommendation or read_pool_info, so it falls short of exhaustive when/when-not 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 readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real context: paginated return shape, that each strategy carries 7d avg APY for its default range, and the decimal-fraction convention (1.0 = 100%). It omits anything about rate limits or response size ceilings, keeping it short of a 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?

Five short sentences, front-loaded with purpose and the recommended call, then pagination, then the units caveat, then the sibling pointer. Nothing is redundant padding.

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 an output schema exists and annotations cover the safety profile, the description supplies everything else an agent needs: scope of the list, pagination strategy, unit convention for APY, and where to go for depth.

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 limit, offset, chain_id and featured_only are already documented; the description only restates the pagination mechanics and the featured_only recommendation. Baseline 3 is appropriate since the 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?

States a specific verb and resource ('Get Arcadia LP strategies') and explicitly distinguishes itself from the sibling read_strategy_info, which handles per-strategy detail. An agent can route between them without opening either 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?

Gives an explicit recommended first call ('featured_only=true for curated top strategies') and names the alternative (read_strategy_info) with the condition that selects it (APY per range width). Covers both when-to-use and waking-the-other-tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description goes beyond them by disclosing the APY basis (1d, unlike the list tool), the decimal-fraction convention for APY values, and the USD unit of weekly_earning_difference — real conventions an agent would otherwise get wrong.

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 short sentences, purpose front-loaded, followed by the disambiguation rule and the unit conventions. Every sentence carries information the schema and annotations do not.

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

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

An output schema exists and the annotations are rich, so the description only needs to cover the non-obvious points — which it does (APY basis, decimal fraction, USD units). It could add a prerequisite note (e.g. the account must exist and be indexed) but is otherwise complete for a read-only, two-parameter 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%, with both account_address and chain_id documented plus default values, so the baseline is 3. The description adds nothing about the parameters themselves; all its extra value is about output-field interpretation rather than input semantics.

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

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

States a specific verb and resource ('Get a rebalancing recommendation for an Arcadia account') plus the outcome ('suggests asset changes to optimize yield'). It also explicitly distinguishes itself from the sibling read_strategy_list by explaining the different APY basis.

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 1d-vs-7d APY note implicitly tells the agent when this tool will disagree with read_strategy_list, which is useful routing context. However, there is no explicit 'use this when the user asks for rebalancing advice' statement or named alternative for strategy lookup, leaving the when-to-use decision partly inferred.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds value by disclosing the return granularity ("a summary of each account (address, name)") and pointing to where richer fields live, though it says nothing about behavior on an unknown wallet address (empty result vs error).

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 short sentences, front-loaded with the core action, followed by return shape and the routing hint. No filler or restated name/title.

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 annotations covering read-only safety, an output schema defining return values, and full schema parameter coverage, the description supplies exactly the missing piece: the escalation path to read_account_info. Nothing an agent needs to call this correctly is absent.

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 wallet_address and chain_id both documented including the enumerated chain ID values, so the schema carries the parameter burden. The description only reinforces the ownership semantics of wallet_address and adds no format or default information beyond the schema. Baseline 3 applies.

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 ("List all Arcadia accounts owned by a wallet address") with an explicit ownership scope, which separates it from sibling listing tools like read_wallet_balances. It also names the companion detail tool, so the boundary between this and read_account_info is unambiguous.

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

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

Explicitly routes the agent: use this for the account list, then call read_account_info with a specific account_address for health factor, collateral, and debt. The when-to-use-this vs when-to-use-the-alternative distinction is stated rather than inferred.

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, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description contributes genuine context beyond them — the tool's role as a pre-flight check to prevent redundant on-chain approvals — though it says nothing about latency, batching, or behavior for unknown token addresses.

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

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

Two sentences, zero waste: the capability first, then the workflow rule. Nothing is buried or repeated from the structured fields.

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?

Annotations carry the safety profile, the schema fully documents all four parameters including chain options, and an output schema exists so return values need no explanation. Everything an agent needs to call this correctly is present.

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

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

Schema description coverage is 100% and each parameter already documents itself (chain IDs, owner vs spender, token list). The description only restates 'spender address' and adds no format, batching, or validation semantics, so it sits 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?

Specific verb+resource: 'Check ERC20 token allowances for a spender address', scoped to a particular owner/spender/token triple. It distinguishes itself from read_wallet_balances (balances) and write_wallet_approve (mutation) without requiring a schema read.

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 names the sibling it precedes (write_wallet_approve) and states the decision rule: skip approving if the current allowance is already sufficient. This is a clear when-to-use plus a concrete branch condition, 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 declare readOnlyHint/idempotentHint/destructiveHint/openWorldHint, so the safety profile is covered. The description adds real context beyond them: it reads directly from chain via RPC multicall and returns both raw (wei) and formatted balances, which clarifies cost/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?

Three sentences, each earning its place: purpose, mechanism, prerequisite usage, then return format. Front-loaded with the core operation and free of 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?

An output schema exists, so return values need not be explained, yet the description still summarizes the raw/formatted shape. Combined with complete annotations and schema, an agent has everything needed 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% (chain_id lists valid chains, wallet_address and token_addresses documented), so the schema already carries parameter meaning. The description adds no syntax or format detail beyond the schema, making the baseline 3 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?

States a specific verb and resource ('Get native ETH and ERC20 token balances for a wallet address'), covering both native and ERC20 scope. An agent can readily distinguish it from siblings like read_wallet_allowances (allowances, not balances) even though no sibling is named explicitly.

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 by naming the write tools it should precede (write_account_add_liquidity, write_account_deposit) and the rationale (verify sufficient tokens). No when-not-to-use or explicit alternative reference, but the positive routing 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered elsewhere. The description adds nothing beyond that — no mention of rate limits, caching, or behavior for unknown/unregistered wallet addresses.

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

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

A single front-loaded sentence with zero wasted words; the resource and scope come first. It is efficient, though the brevity reflects under-specification rather than tight editing.

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 one fully documented parameter and an output schema covering return values, the description is minimally sufficient to call the tool. It leaves gaps around what a missing/zero balance looks like and how this relates to the leaderboard tool, but nothing critical 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?

There is a single required parameter with 100% schema description coverage ('Wallet address to get points for'), so the schema already carries the semantics. The description only restates 'for a specific wallet address' and adds no format or validation detail (e.g. address format, chain).

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 ('Get') and resource ('Arcadia points balance') scoped to a specific wallet address, which is enough to distinguish it from most siblings. It does not explicitly differentiate itself from the similar read_point_leaderboard tool, keeping it below a 5.

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 no guidance on when to use this versus alternatives such as read_point_leaderboard, nor any preconditions or exclusions. It is purely a statement of function; usage must be inferred from the name.

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 give generic hints (non-read-only, idempotent, open-world); the description adds substantial behavior: 30-second calldata validity, retry-at-least-once on price-move reverts, price-warning/accept_price_checks gating with no transaction returned, and expected_value_change units. Annotation contradiction is absent — building a tx with idempotentHint=true is consistent. Minor gap: it doesn't say whether a build has side effects or gas implications beyond the approval step.

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?

Front-loaded with the core multi-step summary and sibling exclusion, then layered detail. It's dense and nearly every sentence carries operational value, but the price-warning paragraph is long and repeats the confirmation rule in slightly different forms.

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 9-param, multi-step, open-world mutation tool, the description covers preconditions (allowances), postconditions (tenderly sim fields, expected_value_change), failure modes, and retry policy. With an output schema present, return-value explanation is a bonus rather than a need.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds value by explaining how parameters interact (deposits array vs use_account_assets, multiple positions in one tx) and clarifies the accept_price_checks lifecycle. That's meaningful semantics beyond the per-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?

States a specific verb+resource ('build add liquidity transaction') and characterizes it as an atomic multi-step flash-action with enumerated components. It explicitly distinguishes itself from the closest sibling by saying 'Do NOT call write_account_deposit separately.'

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?

Gives explicit sequencing (check allowances with read_wallet_allowances, then write_wallet_approve), capital-source selection (wallet deposits vs use_account_assets vs both), account-type applicability (margin vs spot), and points to read_guides('strategies') for workflows. It also specifies retry behavior and the multi-step price-warning confirmation flow.

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 say this is a non-read-only, open-world, non-destructive write; the description adds substantial operational context beyond that: calldata is time-sensitive and must be rebuilt on a price revert, the transaction requires the owner's signature, multisends are grouped under max_gas_per_tx, accounts share one upgrade budget, and simulation failures are surfaced as plan-with-error. It also explains what happens to existing positions and AERO balances rather than leaving state changes implicit.

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?

Purpose and scope are front-loaded in the first sentence, and nearly every subsequent sentence carries an operational rule for a genuinely complex multi-state workflow. It is a dense unbroken block of roughly 350 words with no visual separation of the status branches, which makes it harder to scan than it needs to 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 multi-account, multi-state, transaction-building tool, the definition covers the state machine, error branches, chain support, signature ownership, post-confirmation verification via read_account_info, and the meaning of a missing transaction. An output schema exists, yet the description still gives enough detail to act on the plan without needing to inspect it.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantic value: choices must come from a prior call's options with disabled_reason null, accounts yields one plan per account sharing a budget, and min_block should be the block of the just-confirmed transaction. Only slippage's contract-vs-EOA default is left to 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 sentence states a specific verb and resource ('Upgrade one Arcadia account to Aero (MetadexCL V1) in one flashAction') and enumerates exactly what moves: Slipstream positions and old AERO balances. It distinguishes itself from the read-only sibling by pointing at read_account_info for source data, so an agent can route correctly without opening a 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 gives an explicit decision tree for the backend-reported states (ready / choices_required / waiting / not_open), including what to do with items[].status and items[].reason, when to re-call with choices, when to sign a partial transaction, and the explicit exclusion 'do not retry in a loop'. It also names recovery paths for 422 pool-not-selectable and Tenderly unavailable.

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?

Goes well past the annotations by disclosing the key footgun that the intents array is a full desired state and anything omitted is DISABLED, plus that a single enabled:false turns everything off. It also enumerates the backend-enforced compatibility rules, the error-first behavior (errors[].reason, adjust and retry), and the three cases that deliberately return no transaction (no_changes_needed, simulated revert, preview_only). Only note: destructiveHint=false arguably understates a call that removes automations, but the description itself surfaces that risk.

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?

Long but front-loaded: the core action and the save/preview distinction come first, then intents, then validation rules, then return behavior. Every block is substantive, but several rules (token assignment, recipient/convert restrictions) are restated from the schema, which is some avoidable 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 complex 11-parameter mutation with nested intent unions it covers everything an agent needs: intent semantics, mode trade-offs, autofill behavior, validation failures, and the returned { valid, errors, warnings, human_summary, plan, diff, transaction } shape, which reinforces rather than replaces the 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 coverage is 100%, so the baseline is 3, but the description earns more by explaining what each intent kind means (compound_fees, claim_rewards, add_to_lp, claim_merkl, rebalance), what position_id auto-fills (protocol, is_staked, token0/token1, reward_tokens), and the cross-intent constraints. Some of that overlaps the already-detailed schema descriptions, which caps it below 5.

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

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

Opens with a specific verb and resource: "Configure an account's automations from a list of intents and return the unsigned setAssetManagers transaction." It immediately separates itself from write_account_automations_delta (delta toggling) and read_asset_manager_intents (capability discovery), so an agent can pick correctly without opening a 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?

Explicitly states when to use 'save' (something signable) versus 'preview' (validate/show a plan, no transaction, does not read chain state), and when to switch to write_account_automations_delta for a single toggle. It also prescribes a prerequisite: call read_asset_manager_intents first to see what the account can enable.

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 this is a non-read-only, non-destructive, idempotent, open-world write. The description adds real behavior beyond that: the return is an unsigned setAssetManagers transaction, backend rule violations are returned as errors and never written on-chain, and superseded/unreadable managers are force-disabled in the same transaction. It doesn't cover what happens to automation state on partial failure, but the transaction-semantics note is substantive.

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?

It is long, but for a five-way intent union with backend invariants the length is largely justified, and it is front-loaded: the delta-vs-full-state contrast and the enable/disable split come before the intent catalogue. Some sentences restate schema text and could be trimmed without loss.

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

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

An output schema exists, so return values need not be explained, and everything else an agent needs — prerequisite reads, disable procedure, cross-field validation rules, and the position context auto-fill — is present. Nothing material is missing for correct invocation of a complex write 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 would be 3; the description still contributes by explaining the intent semantics (compound_fees, claim_rewards, add_to_lp, claim_merkl, rebalance) as a coherent narrative and by clarifying that position_id lets the backend fill protocol/tokens/reward_tokens while explicit values win. Much of this overlaps the schema, so it earns only a modest lift over 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?

States a specific verb and resource ('Apply an explicit change to an account's automations') and immediately contrasts with the sibling write_account_automations: delta vs full desired state. An agent can tell which of the two write tools to pick from the first sentence alone.

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?

Gives explicit when-to-use ('switch one automation on or off without restating the others') and a concrete when-not plus alternative (full-state writes go to write_account_automations). It also spells out the disable workflow — read_asset_manager_current, take the address, pass it in `disable` — and states that enabled:false inside `enable` is rejected.

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?

Adds real behavioral context beyond the annotations: the output is an unsigned transaction rather than an executed borrow, the tool performs validation and rejects spot accounts, and only margin accounts with a creditor qualify. Annotations already cover safety/idempotency, so this is strong complementary disclosure, though it doesn't mention the subsequent signing/submission step or what happens on insufficient margin beyond rejection.

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?

Four tight sentences, front-loaded with the core action, then exclusions, then prerequisites. Every sentence carries actionable information with no filler or repetition 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?

For a transaction-building tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what it builds, which account types qualify, what it rejects, which sibling to use instead, and the pre-call verification step.

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 meaning by tying account_address to collateral semantics and referencing the read_account_info fields (collateral_value, used_margin) an agent must check before choosing an amount. It does not add syntax or format detail for amount/pool_address, but the schema handles those.

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

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

Opens with a specific verb and resource: 'Build an unsigned transaction to borrow from an Arcadia lending pool against account collateral.' It immediately differentiates itself from the closest sibling (write_account_add_liquidity) that could otherwise be confused for the same borrowing behavior.

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 NOT to use it ('NOT needed for leveraged LP: write_account_add_liquidity handles borrowing internally when leverage > 0') and names the alternative. It also gives a pre-call workflow: verify positive free margin via read_account_info, with the concrete condition (collateral_value must exceed used_margin).

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?

Goes well beyond the annotations: tokens remain in the account after closing, calldata is time-sensitive (30s signing window), retry-at-least-once guidance on price-movement reverts, and pre-broadcast validation via tenderly_sim_url/tenderly_sim_status. Annotations only cover readOnly/openWorld/idempotent flags, so this text supplies the substantive behavioral context.

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

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

Front-loaded with the atomic-close claim, then the priority rule, then modes, then timing caveats — a sensible ordering. Slightly verbose with some restatement between the mode bullets and the fallback paragraph, but nearly every sentence carries an operational fact.

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 6-parameter mutation tool with an output schema, it covers the decision path, mode semantics, post-close state, timing constraints, and retry behavior. Nothing an agent needs to invoke and follow up 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 still adds meaning by framing close_lp_only as a fallback strategy and by noting multiple receive assets with custom distribution. It doesn't add format details for assets/chain_id/slippage 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?

States a specific verb and resource ("Atomic flash-action that closes an Arcadia account position in ONE transaction") and enumerates the three bundled steps. It is unmistakably distinct from siblings like write_account_remove_liquidity or write_account_swap, which it names.

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 routing: "ALWAYS try this tool first when closing/exiting a position", with a named fallback list and the failure condition that triggers it. It also explains the two-mode workflow (close_lp_only true as step 1 then false) and the follow-up write_account_withdraw.

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

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

The annotations already disclose readOnly=false, destructive=false, idempotent=true, and openWorld=false. The description adds meaningful context beyond those hints: it specifies that the operation builds an unsigned transaction rather than sending one, explains version-dependent behavior and creditor ignoring, and notes deterministic CREATE2 address prediction. It stops short of covering auth requirements or failure cases.

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 three dense sentences with zero wasted text. The core action is front-loaded, followed by version semantics and the return-value note.

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 full schema coverage, an output schema, and annotations, the description is largely complete. It covers the action, version distinctions, and deterministic address return. A minor gap is that it does not explicitly connect this unsigned transaction to the dev_send tool or mention prerequisite wallet state.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description still adds substantial meaning: account_version 3 maps to a V3 margin account, 0 or 4 maps to a V4 spot account, and creditor is ignored for V4. This clarifies parameter interactions beyond the field-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?

The description gives a precise verb and resource: 'Build an unsigned transaction to create a new Arcadia account via the Factory contract.' It also clarifies the account-creation variants, making it distinguishable from sibling write_account_* tools that deposit, withdraw, or otherwise mutate an existing account.

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 explains how account_version selects between V3 margin and V4 spot accounts, which is useful decision guidance. However, it does not explicitly state when to use this tool versus alternatives such as dev_send or read_wallet_accounts, nor does it mention prerequisites like needing an existing wallet or approval before creation.

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

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

The description adds real behavioral context beyond annotations: no wallet tokens required, calldata expires in ~30 seconds, retry at least once on price-movement reverts, and a tenderly_sim_status gate that forbids broadcast on failure. However, the annotations already declare non-read-only, idempotent, non-destructive, open-world behavior, and the description does not discuss approval requirements, gas, or what happens to residual collateral. Strong on operational warnings, but not a complete behavioral picture.

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 core action and the two sibling alternatives are front-loaded, followed by time-sensitivity and simulation-gate warnings in a logical order. It is slightly verbose with layered NOTEs and parentheses, but nearly every sentence carries actionable constraints.

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

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

An output schema exists, and the description still flags the essential return fields (tenderly_sim_url, tenderly_sim_status) and their pre-broadcast semantics, plus retry behavior. For a multi-step flash-action builder with subtle timing constraints, this is sufficient for an agent to call it safely.

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

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

Schema description coverage is 100%, so all seven parameters (chain_id, creditor, slippage, amount_in, numeraire, asset_from, account_address) are already documented in the schema. The description mentions the conceptual flow (collateral sold, debt token repaid) but adds no syntax, units, or default guidance beyond what the schema provides. Baseline 3 applies.

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: sells account collateral to the debt token and repays atomically. It explicitly distinguishes itself from write_account_repay (wallet-funded repayment) and write_account_close (position-closing batch), so an agent can select it without opening any 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?

Explicit routing rules: use write_account_repay to pay from wallet tokens, use write_account_close when closing a position, and use this tool only for standalone repayment while keeping the position open. Both alternatives and the exclusion condition are 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 declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, yet the description adds real context: the output is an *unsigned* transaction (nothing is broadcast), allowances must be in place or the call fails downstream, and account version is auto-detected on-chain with an override. It does not cover what to do with the returned unsigned tx (sign/broadcast, e.g. via dev_send) or failure modes, so not a 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?

Four tight sentences, front-loaded with the core action, then exclusions, then prerequisites, then an edge case. No sentence is redundant with the title or 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?

For a 7-parameter mutation with 100% schema coverage, annotations and an output schema, the description covers prerequisites, the sibling alternative, and version handling. The remaining gap is the lifecycle after building the unsigned tx — an agent must infer that it needs a separate signing/broadcast step.

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 3 is the baseline; the description still adds meaning by framing the asset arrays as ERC20 tokens vs ERC721 NFT LP positions and by explaining the account_version auto-detect/override behavior. It leaves the asset_ids/asset_types/asset_amounts alignment rules entirely to 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?

States a specific verb and resource: 'Build an unsigned transaction to deposit assets into an Arcadia account as collateral', plus the supported asset classes. It also explicitly distinguishes itself from the sibling write_account_add_liquidity, so an agent can route without opening schemas.

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

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

Gives an explicit negative condition ('NOT needed before write_account_add_liquidity: that tool deposits from wallet atomically') and a concrete prerequisite chain naming the exact tools to call first (read_wallet_allowances, then write_wallet_approve). This is when/when-not/alternatives all in one.

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?

Discloses behavior beyond annotations: the resulting state (position open, tokens retained), the time-sensitivity window (sign/broadcast within 30s), revert handling with an explicit retry-at-least-once instruction, and that the response carries tenderly_sim_url/tenderly_sim_status. Annotations only say non-readOnly, openWorld, idempotent, non-destructive – the description supplies the operational consequences.

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?

Front-loads the partial-vs-full distinction, then the alternative, then the timing/retry caveat. Three short paragraphs, each earning its place. Slightly long for its content but no filler sentences.

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 mutating, time-sensitive transaction builder, it covers outcome state, sibling routing, timing constraints, failure/retry behavior, and available validation artifacts, while the output schema handles return shape. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including chain_id options and the uint128 adjustment constraint. The description reinforces the adjustment-vs-close distinction but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('PARTIALLY decreases liquidity from an LP position') and disambiguates from its nearest sibling write_account_close by explaining what full exit does. An agent can distinguish it from write_account_add_liquidity or write_account_close without opening either 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?

Explicit when-to-use (partial reduction, position stays open) and when-not-to-use, naming the alternative (write_account_close for full exit with burn+swap+repay+withdraw). Also gives a retry policy for reverts, leaving nothing 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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false; the description adds the ERC20 allowance prerequisite and the wallet-vs-collateral funding distinction, which are real behavioral facts. The only remaining gap is whether this submits or merely builds an unsigned transaction, though the annotation title 'Build Repay Transaction' already signals that.

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?

Four short sentences, each front-loading a distinct decision: funding source, alternative tool, approval workflow, and debt lookup. Zero filler.

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

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

With an output schema present and four fully described parameters, the description covers what an agent needs to call this correctly, including the allowance prerequisite that would otherwise cause a failed call. Only the build-vs-submit distinction is left implicit.

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

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

Schema description coverage is 100%, and each parameter is documented with examples (pool addresses, chain IDs, raw units and 'max_uint256'). The description adds nothing about parameter format or defaults, so the baseline 3 is appropriate.

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

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

States a specific verb (repay debt) plus resource (Arcadia lending pool) and the funding source (wallet tokens), which immediately separates it from the collateral-based sibling. An agent can identify the correct tool without opening either 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?

Explicitly names the alternative (write_account_deleverage) and the condition that selects it, and lays out the prerequisite sequence: read_wallet_allowances, then write_wallet_approve if needed, with read_account_info for debt. This is a full when/when-not/alternatives routing guide.

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?

Goes well beyond the annotations. It discloses that returned calldata is time-sensitive with a 30-second sign/broadcast window, that Tenderly simulation may be unavailable for this endpoint, and protocol-specific routing (Aero CL metadexcl_v1: spot accounts via the Arcadia wrapper, margin accounts via the staked module). These are operational facts an agent cannot derive from the schema or the readOnly/openWorld 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?

Front-loaded with the action framing, then prerequisites, retry policy, and protocol caveat in a sensible order; virtually every clause carries information. It runs long as a single dense block and the trailing Aero CL note is harder to parse than the rest, but there is no filler.

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

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

For a mutating, time-sensitive transaction builder, the description covers the selection logic, prerequisite lookup, timing constraint, retry behavior, simulation caveat, and protocol routing. An output schema exists and the description already characterizes the return as calldata, so return-value detail need not be repeated.

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 meaning beyond it: `asset_address` is overloaded to mean the non-staked PM when staking and the staked PM when unstaking, which the schema text ('Position manager contract address') does not convey. Chain support is echoed from the schema rather than extended, so it stops short of a 5.

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

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

Opens with a specific verb set (stake, unstake, claim) plus the resource (LP position) and the atomic-transaction framing, so the agent knows exactly what is built. It is clearly distinguishable from siblings like write_account_add_liquidity or write_account_remove_liquidity, which operate on liquidity rather than an existing LP position NFT.

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 routes the agent via the `action` enum and states which `asset_address` to pass for staking vs unstaking (non-staked PM vs staked PM). It also names a prerequisite (verify the position exists with read_account_info before signing) and prescribes failure handling: retry at least once immediately after a price-movement revert.

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 non-read-only, open-world, non-destructive, idempotent. The description adds context annotations cannot carry: calldata expires in 30 seconds, reverts should trigger rebuild-and-resign with at least one retry, and broadcasting must be blocked when tenderly_sim_status is 'false'. That is substantial safety-critical disclosure.

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

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

Front-loads purpose in the first sentence, then the alternative routing, then the time-sensitivity and simulation gate. Dense but nearly every clause carries operational meaning; the retry instruction runs slightly long but is still functional.

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

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

An output schema exists, so return values needn't be enumerated, yet the description still calls out the two fields that matter for safety (tenderly_sim_url, tenderly_sim_status). For a 6-parameter mutation tool with open-world behavior, nothing an agent needs before calling 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 all six parameters are already documented in the schema (chain IDs, slippage in bps, raw units, token addresses). The description adds no parameter-level detail, so baseline 3 applies.

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 — swapping assets within an Arcadia account via one atomic transaction — and explicitly contrasts itself with the sibling write_account_close. An agent can distinguish it from write_account_borrow/repay/withdraw without reading schemas.

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

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

Gives an explicit exclusion ('If you are closing a position ... prefer write_account_close which batches everything atomically') and an explicit inclusion ('Only use this tool for standalone swaps within an active position'). It also adds operational guidance on retry behavior, which is rare and valuable.

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 say it is non-read-only, non-destructive, and idempotent; the description adds what those hints cannot: revert semantics tied to collateralization, an ownership precondition, the max_uint256 restriction, and on-chain version auto-detection with an override. This is exactly the extra behavioral context a caller needs before building a transaction.

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?

Four sentences, each carrying distinct information: purpose, authorization, revert condition, amount constraint, and version handling. The primary action is front-loaded and nothing is redundant with the title or annotations.

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

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

With an output schema present, return values need no explanation, and the description covers the risky edge cases (debt/undercollateralization, owner-only, exact amounts). The one gap is that it never says the output is unsigned and requires a separate submission step, which matters for a 7-parameter transaction-building 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, and the description adds meaningful guidance on top: amounts must be exact values from read_account_info rather than sentinel max values, and account_version is normally auto-detected. It does not clarify the asset_ids/asset_types pairing or chain_id choices, which remain schema-only.

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 concrete verb and resource: build an unsigned transaction to withdraw assets from an Arcadia account to the owner's wallet. That scope cleanly separates it from siblings like write_account_deposit, write_account_borrow, and write_account_repay without needing to open any 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?

Gives real eligibility conditions (only the account owner can withdraw) and a failure condition (reverts if the account has debt and the withdrawal would leave it undercollateralized), plus a concrete directive to source exact amounts from read_account_info instead of max_uint256. It stops short of naming alternatives or noting that the produced transaction must then be submitted via a send path such as dev_send.

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 a non-readonly, non-idempotent, non-destructive write; the description goes beyond by clarifying it BUILDS an unsigned transaction (not execute) and that approval must precede it. That unsigned-vs-executed distinction and the approval dependency are meaningful behavioral context the annotations wouldn't convey.

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

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

Three sentences, front-loaded with the action, then mechanics, then prerequisite, then a pointer to related reads. No filler; every clause carries actionable 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?

An output schema exists (so return shape needn't be explained) and annotations cover the safety profile; the description supplies the approval prerequisite and yield-check follow-up. Slightly short of 5 only because the unsigned-transaction handoff workflow (sign/send via dev_send?) isn't stated.

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

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

Schema coverage is 100%, so baseline is 3; the description earns extra by explaining that assets are the pool's underlying (USDC/WETH/cbBTC) and that receiver receives minted tranche shares, adding intent beyond the raw 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?

Precise verb+resource: 'Build an unsigned deposit transaction into an Arcadia lending tranche (ERC-4626)' and explains the lender mechanics (deposit underlying, receive interest-accruing shares). It doesn't explicitly contrast with write_pool_redeem, but it does route to adjacent siblings (write_wallet_approve, read_pool_list/read_pool_info), so differentiation is implied rather than spelled 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?

States a concrete prerequisite ('Requires prior ERC-20 approval to the tranche (see write_wallet_approve)') and points to read_pool_list/read_pool_info for yield checks. Clear usage context, though it never says when NOT to use it or explicitly names write_pool_redeem as the inverse operation.

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 annotations, the description discloses that the tool builds an unsigned transaction, burns tranche shares, returns the corresponding underlying including accrued interest, and requires the owner to be the shares holder. It does not disclose submission behavior, approval requirements, or failure modes, but adds meaningful context over the annotation safety profile.

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 action and resource, then adds only the essential mechanics and role constraints. Every sentence contributes useful information with no wasted text.

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

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

With an output schema present, full schema coverage, and annotations covering the safety profile, the description is complete for correct invocation. It covers the unsigned-transaction nature, share burning, underlying return including interest, and owner/receiver roles.

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

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

Schema description coverage is 100%, so all five parameters are already well documented. The description reinforces the owner-as-shareholder and receiver-destination semantics but adds no syntax or format detail beyond the schema; baseline 3 applies.

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: builds an unsigned redeem transaction for an Arcadia lending tranche (ERC-4626), withdrawing underlying by burning shares. It is clearly distinct from deposit/read tools by its redeem/withdraw framing, though it does not explicitly name the sibling alternative write_pool_deposit.

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

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

Usage is implied by the redeem/withdraw description and the prerequisite that the owner must be the shares holder. It does not explicitly say when to prefer this over write_pool_deposit or other withdrawal paths, nor does it spell out when-not conditions.

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 cover safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=false), and the description adds key context beyond them: the transaction is 'unsigned' (not broadcast), and it is a prerequisite step whose generated call varies by asset type. It doesn't detail return shape, but an output schema exists so that burden is lifted.

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 tight sentences, front-loaded with the core action, then per-asset-type branching, then the prerequisite chain and the read_wallet_allowances tip. No wasted prose.

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?

Annotations declare the safety profile, output schema handles return values, and the schema fully documents all 5 parameters. The description supplies the workflow ordering and per-asset-type behavior, so an agent has everything needed 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 coverage is 100%, so the baseline is 3, but the description adds meaning by explaining how asset_type drives the generated function (approve vs setApprovalForAll) and confirming amount is ERC20-only. This maps parameters to behavior beyond the 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?

States a specific verb and resource ('Build an unsigned approval transaction') and immediately describes the two behavior modes: approve(spender, amount) for ERC20 and setApprovalForAll(operator, true) for ERC721/ERC1155. This clearly distinguishes it from sibling write_* tools that consume the approval.

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 names prerequisites ('Required before write_account_deposit or write_account_add_liquidity') and gives a when-not rule: call read_wallet_allowances first and skip if allowance is sufficient. Both the enabling alternative and the skip condition are stated, leaving little 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?

Goes well beyond the annotations by disclosing that this returns ordered unsigned transactions (an approve only when the allowance is short, then depositLiquid with the Hyperlane fee as value), the 0.044 AERO-per-VELO rate, and that the AERO lands at the same address on Base. This is exactly the execution-model context annotations (readOnlyHint/idempotentHint) cannot convey.

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

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

Front-loads the core action and follows with the transaction sequence, preconditions, and error taxonomy in a tight block. Density is high but every clause carries operational value; the error-reason enumeration is the only part that borders on long.

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

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

An output schema exists, so return values need no explanation, and the description still covers the transaction shape, value/fee handling, chain restriction, account-vs-wallet precondition, and failure modes. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so 3 is the baseline; the description adds real meaning on top by naming the conversion rate and confirming the AERO recipient address is the owner_address. It does not restate format details (raw 18-decimal units) but the schema already covers those.

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?

Names a specific verb+resource+chain pair: upgrade VELO on Optimism to AERO on Base via the Velodrome migration. It also distinguishes itself from the sibling write_account_aero_upgrade by stating that VELO inside an Arcadia account is not handled here.

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 preconditions and alternatives: use write_account_withdraw first if the VELO sits in an Arcadia account, the upgrade is optional because VELO stays usable, and it is Optimism (chain_id 10) only. It even decodes the 'upgrade unavailable' failure reasons so the agent knows when not to retry.

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