unisafe LP insight

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

Annotations only cover readOnlyHint and openWorldHint; the description goes well beyond them by disclosing the three-tier resolution strategy (index, then Envelop history API, then log scan) and the fact that the response reports which source served the request and how current it is. That fallback and provenance behavior is exactly the kind of trait an agent cannot infer from the schema or annotations.

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

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

A single sentence front-loads the resource and what is returned, then appends the data-source behavior. It is dense but every clause carries information; no filler. A slight split into two sentences would read more cleanly.

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

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

With no output schema, the description must carry return-value context, and it does list the returned fields (open time, pool, lifetime fees, events) plus the source-provenance note. It omits details like pagination or ordering for the all-positions case, which is a minor gap for a read-only lookup.

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: salt is described as selecting the single-position mode versus the all-positions listing for a manager, which the schema's terse 'Position key' label does not convey. chainId and manager semantics are already fully documented in the schema.

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

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

Names a specific verb and resource (retrieve every position of a manager, or one position by salt) and enumerates the payload fields: open time, pool, lifetime fees, events. The sibling tools (list_operators, rank_pools, suggest_move) are unrelated operations, so no sibling disambiguation is needed and none is missing.

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 rather than stated: pass manager alone for all positions, add salt for a single one. There is no explicit when-to-use vs. alternative guidance and no stated prerequisites (e.g. whether the manager must be indexed), but the two invocation modes are discernible from the description.

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 the safe-read profile (readOnlyHint=true, openWorldHint=true), and the description adds real behavioral context beyond them: partial-failure handling (`stale` marks a copy served while a refresh fails), a concrete staleness threshold (gateway data over 3 hours old), and unpriced-token reporting via `tokens`/`derived`. Gaps remain — no error behavior for unsupported chains or gateway failures, and no note on rate limits or caching cadence.

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 question ('what things are worth on a chain') and split sensibly into purpose, usage, and response-field notes; every sentence carries information. The first sentence is nonetheless heavily nested with parentheticals, which slows parsing for an agent skimming for the call contract.

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

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

With no output schema, the description must carry return-value semantics, and it does explain the notable cases (stale copy, three-hour gateway staleness, derived stablecoin pricing, unpriceable tokens). It is less complete on the shape of the price map and per-operation cost entries, and on failure modes, which an agent calling with an arbitrary chainId would want.

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

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

Schema coverage is 100%, so both parameters are already documented; baseline 3 applies. The description adds only a little — that `tokens` also reports addresses it cannot price — while the other backticked names (`derived`, `stale`, `gatewayDataAt`) are response fields presented inline, which can momentarily read as parameters and slightly muddies the parameter/return boundary.

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 clause names the resource precisely (token USD prices, gas price, per-operation USD costs) and enumerates the operations covered (recenter, move, allocate, reinvest, claim). It also pins the scope detail that matters most — the native token/address zero is priced as the chain's WETH — so an agent knows exactly what comes back without opening the schema.

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

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

Usage is stated explicitly: use it to weigh whether an operation pays before simulating, and prefer a simulation's own gas estimate once one exists. That gives a clear when-to-use and a when-to-prefer-something-else. It stops short of naming a concrete alternative tool from the sibling set (e.g. suggest_move), leaving the routing inference to the agent.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description's added value is elsewhere — it does add it: the empty-list-means-none versus oracle-failure-is-an-error distinction is a behavioral trait an agent would otherwise misread. It doesn't mention latency or rate limits on the cross-chain fan-out, which for an openWorld multi-chain read would be useful.

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 resource and scope, then closes with the routing hint and the empty-versus-error caveat; every clause carries information. It runs a bit long as three dense ideas in two sentences, but nothing is wasted.

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 parameter, no output schema, and read-only annotations, the description covers what the agent needs: scope, exclusions, result shape (app link per entry), and empty-versus-error semantics. Return structure beyond 'app link for each' is left implicit, which is acceptable for a list 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% and the single `owner` parameter is fully documented in the schema, including the EOA-or-smart-account note, so the description adds little parameter-level meaning. Baseline 3 applies when the schema already carries the 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?

Names a concrete resource (unisafe LP managers, Stable and Volatile) with scope defined as every chain the Envelop oracle indexes, and explicitly carves out what is excluded (other Envelop wNFTs). The phrase 'the way in when you know the owner and not the managers' separates it from the sibling list_operators that would answer a different question.

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 clear selection rule ('when you know the owner and not the managers') and states the exclusion of other Envelop wNFTs, so the agent knows when this list is the right one. It does not name list_operators or the inverse lookup case explicitly, so the routing is implied rather than complete.

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

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

Beyond the readOnlyHint=true annotation, it discloses real behavioural traits: operators can never withdraw (contract-enforced capability boundary), and that a `partial` answer on the scan path may include revoked operators while the index path never does. This staleness/completeness caveat is exactly the kind of context structured fields cannot convey; only auth/pagination details are absent.

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 tightly packed sentences with zero padding: scope first, then the capability constraint, then the result-caveat. Each sentence carries information an agent cannot get elsewhere.

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

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

With no output schema, the description usefully hints at the return shape (a set of addresses, possibly flagged `partial`), which is more than most read tools offer. It stops short of naming pagination or the distinction between scan and index paths, but nothing essential to calling 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%, with both chainId and manager fully documented including format examples and a contract-address pattern, so the baseline is 3. The description adds only the indirect implication that `manager` is the manager whose positions are rebalanced; no extra syntax or edge cases are supplied.

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

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

The description names the resource precisely — addresses authorised to rebalance a manager's positions — and states the scope ('currently authorised'), so an agent knows what the tool returns. It is a noun phrase rather than a verb+resource, and it never explicitly says 'list/retrieve', though the tool name plus sibling set (get_position_history, rank_pools, suggest_move) makes the intent 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?

There is no when-to-use statement, no preconditions (e.g. manager must exist / which chain), and no mention of alternatives among the siblings. The scan-vs-index note describes result behaviour, not when to select this tool over another.

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

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

Beyond the readOnly/openWorld annotations, the description discloses the data source and fallback behavior (`aprSource`: Uniswap gateway vs. subgraph's last complete day). It also explains how unscored pools are handled and warns that absence from the ranking does not imply a bad pool.

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 metric and ranking order, and each sentence contributes useful context. It is slightly dense but not padded, and the caveats about candidate pools and unscored pools earn their place.

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

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

With no output schema, the description still explains the return shape conceptually: ranked pools by Fee APR, best first, plus separately listed unscored pools with reasons. Given the readOnly annotations and fully covered parameters, it provides enough context to call and interpret the tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces that the manager scopes the candidate pool set, but does not add format or syntactic detail 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 names a specific verb and resource — ranking a manager's configured pools — and states the ranking metric: Fee APR over the last 24 hours, best first. It is clearly distinguishable from siblings like get_position_history, list_operators, and suggest_move.

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 important usage constraint: only pools fixed into the manager's set at creation are candidates for a move. However, it does not explicitly say when to use this tool instead of siblings such as suggest_move, nor does it name when-not-to-use 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 only say readOnlyHint and openWorldHint; the description adds substantial context beyond them — it returns numbers never calldata, names the bridge pool when currencies don't overlap, requires manager v2.2 for cross-currency suggestions, and warns that propose_move re-derives each number against chain state through policy and oracle guards. It also discloses that full ranking and caveats accompany every answer.

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 purpose is front-loaded in the first sentence and the safety-relevant caveat comes last, which is a sensible ordering. Four dense sentences are all substantive, though the bridge-pool sentence is long and could be tightened.

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

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

There is no output schema, so the description carries the return-value burden (destination pool, ticks, liquidity amount, bridge name, full ranking, caveats) and it does so thoroughly, while also explaining the downstream handoff. An agent has everything needed to call and interpret the tool.

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

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

Schema description coverage is 100%, so the schema already documents chainId, manager, salt, and minGainPct, including the default of 1. The description gestures at the gain threshold but adds no syntax or semantics beyond the schema, which is the expected baseline when 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: it compares the position's current pool against the manager's set and returns move numbers (destination pool, ticks, liquidity). It clearly marks the boundary as a suggestion generator whose output feeds propose_move. It does not however differentiate itself from the sibling rank_pools, which also deals with pool ranking.

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 clear context for when to reach for it (evaluating a move, with a minGainPct threshold implied by "when the gap is worth it") and explicitly routes downstream use to the envelop-mcp-lp propose_move tool. It stops short of naming alternatives or when-not-to-use conditions against siblings like rank_pools.

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