Odyssey Loopr

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

Adds substantial behavior beyond the annotations: the server never holds keys or sends transactions, the build expires after 180 seconds via `expiresAt`, builds are single-use, and specific 422 outcomes (`simulation_reverted`, `insufficient_balance` with token/required/available) are disclosed. These are consistent with readOnlyHint=true (nothing is written; the owner signs) and idempotentHint=false (a rebuild produces a different address), so there is no annotation contradiction.

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

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

Despite its length, every sentence carries distinct operational value — mode requirements, custody model, expiry, single-use constraint, simulation gate, zap-in semantics, and error codes. It is front-loaded with the core purpose before the safety caveats, so an agent gets the essentials from the opening clause.

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 19-parameter tool with no output schema, it covers the critical gaps: it names `steps` and `expiresAt` in the return, explains the two-direction field discipline, and flags the zap-in denomination change. It does not describe slippage, approvalMode, or maxPriceImpact defaults beyond what the schema states, but those are adequately covered at 95% schema coverage.

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 already 95%, so the baseline is 3, but the description adds real meaning: fields of the opposite direction are refused rather than ignored, exactly one of withdrawAmount/withdrawAll must be supplied on pull, and with `tokenIn` set the `amount` is denominated in `tokenIn` decimals. That last point is a subtlety the schema alone does not convey.

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

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

The first sentence names a specific verb (build) and resource (adjustment steps) and splits the two modes with their required fields: push needs collateralToken/amount/borrowToken/leverage, pull needs token/tokenOut plus one of withdrawAmount/withdrawAll. It is unambiguous what the tool produces (unsigned transaction steps). It never names the sibling it supersedes or pairs with (build_open vs build_adjust, quote_adjust), leaving sibling separation implicit.

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?

Strong when-to-use guidance: build immediately before signing rather than as a plan, never replay a build, and pass `steps` to `simulate` and check `ok` before asking for a signature. It also gives a retry path via `forceSwapper` when simulation fails. It stops short of naming `quote_adjust` as the tool to use when the owner is still deciding, which is the natural alternative given the sibling list.

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=true and idempotentHint=false; the description goes well beyond them by explaining the 180-second expiry with the `expiresAt` field, single-use semantics and why rebuilding changes the predicted position address, and the caveat that a successful build does not guarantee a successful transaction. The 'server never holds keys or sends transactions' line is consistent with readOnlyHint and reinforces rather than repeats it.

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

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

Four tight sentences, front-loaded with what is returned and who signs, then the expiry, single-use, and simulate caveats in order of operational risk. No filler or restatement of the name.

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?

Covers the things that would cause real failures: expiry, non-replayability, unsigned output, and the simulate gate, and with no output schema it still explains the return shape (`steps`, `expiresAt`). The gap is the borrowAmount value format and the role of optional marketId, which an agent must read from a thin or absent schema description.

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?

At 67% schema description coverage the schema already documents owner, chainId, strategyId, and positionAddress, so a baseline 3 is appropriate. The description adds nothing about the undocumented parameters (borrowAmount units/decimals, marketId optionality) and its mentions of `steps`, `expiresAt`, and `ok` are output fields, not 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: 'Build the steps that borrow more against a position', and clarifies the output is UNSIGNED transaction steps. This separates it from build_open/build_repay/build_close by scope, but it never names the closest sibling (quote_borrow) or explains build-vs-quote, so an agent must infer that distinction from sibling 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?

Gives concrete timing guidance ('build immediately before signing, not as a plan for later'), a hard constraint ('never replay one'), and a required follow-up workflow ('pass `steps` to `simulate` and check `ok`'). It stops short of explicitly routing to quote_borrow when the user only wants a preview, which is the one obvious alternative an agent would weigh.

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 readOnlyHint=true / idempotentHint=false annotations: it discloses the 180-second expiry with the `expiresAt` unix-ms field, single-use semantics (rebuilding an open predicts a different position address), that the server holds no keys and never sends transactions, and that a successful build does not guarantee a successful transaction. No contradiction with annotations, since building unsigned steps is genuinely a read of the chain state plus local assembly.

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?

Six dense sentences, front-loaded with the action and input contract, then constraints (expiry, single-use), then the safety caveat. No filler; each sentence carries an operational rule an agent must follow.

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 tells the agent what comes back (unsigned steps, `expiresAt`) and what to do next (simulate). Only minor gaps remain, such as what an expired or already-used build returns as an error shape.

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 71% and the description closes the most important gap: `rewards` must be passed exactly as quote_claim returned them, and `compound` mode requires `slippage` (a conditional requirement absent from the schema). Remaining params (owner, chainId, positionAddress, strategyId) are left to the schema's own 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?

"Build the steps that claim rewards" names a specific verb (build) and resource (claim steps), and immediately clarifies the return type: UNSIGNED transaction steps. An agent can distinguish it from quote_claim (which produces the rewards data) and from build_open/build_borrow (other build targets) 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?

Explicit sequencing is given: take `rewards` from quote_claim, build immediately before signing, then pass `steps` to `simulate` and check `ok` before requesting a signature. It also states when-not behavior: don't build as a plan for later (180s expiry) and never replay a build.

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 traits annotations cannot express: unsigned output only, server never holds keys or sends transactions, 180-second expiry with the expiresAt field, single-use builds, and no guarantee of on-chain success. This aligns with idempotentHint=false; readOnlyHint=true is consistent since the server only constructs payloads. A minor gap is that it does not state auth/permission requirements for the owner.

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, front-loaded with the action, each carrying a distinct constraint (custody, expiry, single-use, simulate-first). Dense but no filler, though the parenthetical expiresAt note slightly crowds the expiry sentence.

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

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

No output schema exists, and the description compensates by naming the returned steps and expiresAt field plus the simulate handoff. It is nearly complete for a build tool; what remains thin is guidance on quote_close vs build_close and any permission prerequisites for the signing owner.

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 owner, chainId, slippage, strategyId, forceSwapper, receiveToken, and positionAddress. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies. Its value instead lands in output/behavior explanation.

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

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

States a specific verb and resource ('Build the steps that close a position in full'), and the 'in full' qualifier separates it from partial-exit siblings like build_adjust. Combined with the sibling list (quote_close, build_open), an agent can tell immediately which tool produces a full close.

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 strong sequencing guidance: build immediately before signing rather than treating it as a plan, rebuild rather than replay, and pass steps to simulate before requesting signatures. It does not explicitly compare against quote_close or explain when to quote vs build, which is the main remaining routing gap.

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

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

Annotations declare readOnlyHint=true and idempotentHint=false; the description is consistent, explaining the server holds no keys and sends nothing, and that builds are single-use so replaying predicts a different position address. It adds behavior beyond the annotations: the 180-second expiry via `expiresAt`, the 422 `simulation_reverted` for zap-ins, and the 422 `insufficient_balance` payload shape.

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 purpose and the safety-critical constraint (expiry, single-use, simulate before signing) are front-loaded and each sentence carries operational information. It is dense and long, and the error-code sentences could be trimmed slightly, but little 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?

For a 13-parameter, 7-required mutation builder with no output schema, the description covers return semantics (unsigned steps), lifetime, replay hazards, simulation guidance, and two error codes. Some lower-traffic parameters and the `expiresAt`/steps output shape are left implicit, but nothing critical for correct invocation is missing.

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

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

With 69% schema coverage, the schema documents most parameters, but the description adds real meaning for `tokenIn` (build-only zap-in, amount switches to tokenIn decimals, simulated by the build) and clarifies the leverage/borrow constraint. It leaves `tokenInSwapper`, `borrowToken`, `collateralToken`, and slippage defaults to the schema, so it is strong but not exhaustive.

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 the steps that open a leveraged position', and immediately clarifies the output is UNSIGNED transaction steps. It distinguishes itself from build_adjust by noting that adding collateral without borrowing belongs to adjust, so an agent can route correctly among the build_* 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?

Gives explicit when-to-use rules: build immediately before signing (180s expiry), never replay a build, and pass `steps` to `simulate` and check `ok` before requesting a signature. It also names the alternative path (adjust an existing position for non-borrowing collateral adds) and explains the zap-in path via `tokenIn`.

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 annotations, it discloses the 180-second `expiresAt` window, single-use semantics with the concrete consequence of address drift on rebuild, the fact that the server never holds keys or sends transactions, and the exact 422 `insufficient_balance` payload shape. The replay warning and the 'successful build is not a successful transaction' caveat are exactly the traits 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?

Purpose is front-loaded in the first clause, then constraints follow in descending importance. It is dense but nearly every clause is load-bearing; the parenthetical error-shape detail is slightly heavy for a description but earns its place by enabling error handling without a failed 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 10-parameter, 6-required builder with no output schema, the description covers lifecycle (expiry, single-use), safety (no keys, unsigned), verification (simulate/`ok`), and the main failure mode. The remaining gaps are the amount units and the quote-vs-build relationship, which matter for a financial tool but are secondary to what is already documented.

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 already 80%, so the schema documents owner, slippage units, strategyId provenance, and the mode-scoped optional params. The description still adds value the schema lacks: slippage is conditionally required for `auto`, and the balance precondition is tied to which modes pull owner funds. It does not explain `repayAmount` / `withdrawAmount` units, which remain unstated in both places.

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?

"Build the steps that repay debt" states a specific verb (build) and resource (repay steps), and the mode sentence clarifies the two repay paths. It does not, however, distinguish itself from the sibling quote_repay or from build_close, so an agent must infer the quote-vs-build split on its own.

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?

Strong operational guidance: build immediately before signing rather than as a later plan, pass the result to `simulate` first, `auto` requires slippage while `manual` repays from the owner's wallet. What is missing is the upstream routing — nothing says to call quote_repay first or when to prefer build_repay over build_close for a position being wound down.

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 and idempotent, so the safety profile is covered. The description adds genuinely non-obvious behavior: the single-position return shape and the crucial caveat that a null `position` with `errors` means an unreadable chain rather than a missing position, which prevents a false negative conclusion.

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 dense sentences, front-loaded with purpose, then preconditions, then the special case. Every clause carries information, though the backticked return-shape detail makes the second sentence heavy for a general reader.

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 correctly describes the single-position return object and its error semantics. It does not describe the list-mode return shape, but the opening sentence names the key fields (health, leverage, PnL), which is enough for an agent 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 50% and positionAddress has no schema description, but the description supplies the missing semantics: it must be combined with chainId and not chainIds, and it changes the return shape. It also communicates the 'one of chainId/chainIds is required' constraint that the schema does not enforce.

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 ('List an owner EOA's Loopr positions') and names the data returned (health, leverage, PnL). It is clearly distinguishable from the build_*/quote_* siblings, which construct transactions rather than read state.

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 hard precondition ('Requires chainId or chainIds') and explains the two modes: owner+chain for a list, positionAddress+chainId for a single position. It omits any statement about when to prefer a sibling tool, but the list-vs-single routing is explicit.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: the derivation is deterministic and chain-independent ('the same on every chain'), which tells the agent results can be cached and reused across chains. It stops short of describing the return shape or deployment assumptions.

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 tight sentences with the core behavior front-loaded and the determinism property as a supporting clause. No wasted words or hedging.

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 one-parameter read tool, the description covers what is computed but not what is returned (a bare address versus an object), and there is no output schema to fill that gap. It is adequate but leaves the agent guessing about the response shape.

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 0% and the single 'eoa' property has no description, so the description carries the burden. It does clarify that the input is an EOA (as opposed to the derived SCA), which is a meaningful distinction, but gives no format guidance (hex vs checksummed address) or validation expectations.

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 ('Derive') and a specific resource ('the smart contract account (SCA) that holds Loopr positions'), plus the input it derives from (an EOA). This is clearly distinguishable from siblings such as get_positions or get_strategy, which read state rather than derive an address.

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: the agent can infer this is the lookup to perform when it needs the SCA address before calling position or build/quote tools. There is no explicit when-to-use statement, no mention of alternatives, and no note on error behavior for EOAs without a deployed account.

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 idempotentHint, so safety is covered. The description adds one genuinely useful behavioral fact — that strategyId alone can be ambiguous on a chain and that token parameters resolve the collision — but says nothing about behavior when the lookup fails, returns multiple, or what shape the result takes.

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, front-loaded with the action and followed by the one conditional that matters. Nothing is repeated and no wording 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?

This is a simple read tool with no nested objects, but there is no output schema and the description never indicates what a strategy object contains or what happens on a miss. Combined with the unexplained token format, an agent can construct the call but not fully anticipate the response.

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

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

Schema coverage is 50%: chainId and strategyId are documented, but borrowToken and depositToken are bare strings. The description compensates by defining those two as optional disambiguators used when a strategyId is not unique on a chain, which is real meaning the schema lacks. It does not, however, say whether the token values are addresses or symbols.

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?

"Get one strategy" states a verb and resource and the word "one" signals single-record retrieval as opposed to the sibling list_strategies, but it is barely more than a restatement of the title "Get strategy". It never names list_strategies explicitly or otherwise differentiates itself from the many build_/quote_ siblings.

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

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

The only usage guidance is conditional and parameter-level: pass depositToken/borrowToken when several strategies share a strategyId on the same chain. There is no statement about when to call this rather than list_strategies, though the schema's "Strategy id from list_strategies" hint supplies an implicit workflow.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful context by naming the returned metrics, but it omits the notable behavioral fact that delisted/disabled strategies are excluded by default (includeDisabled), and says nothing about result volume or ordering.

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, front-loaded with the resource and payload, followed by the filtering capability. No filler or redundant 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?

With no output schema, the description usefully compensates by enumerating the fields returned. It falls short only on the includeDisabled default and any hint about result size, both relevant for a filterable 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 75%, so the schema largely documents the parameters itself. The description maps three filters (chain, deposit asset, protocol) onto assets/chainIds/protocols, which adds little beyond the schema, and it completely omits includeDisabled, the one parameter whose default semantics are non-obvious.

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 ('List') and resource ('Loopr leveraged strategies') and enumerates the fields returned (APY, leverage bounds, deposit/borrow tokens, TVL). It is clearly the plural/collection counterpart to the get_strategy sibling, though it never names that sibling 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?

'Filter by chain, deposit asset or protocol' implies how to narrow results, but there is no explicit when-to-use guidance, no mention of when to call get_strategy instead, and no note that all filters are optional and the call returns everything by default.

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

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

Annotations already declare readOnlyHint true and idempotentHint false, so the safety profile is covered. Beyond that, the description discloses genuinely non-obvious behavior: the tool returns a quote envelope, quotes expire after 180 seconds, and expiresAt is in unix milliseconds — critical for an agent that must act before expiry. It could still mention whether the quote is bound to slippage, but the expiry semantics are the important addition.

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 operation and direction semantics, then the return/expiry contract, then the amount format. No filler and nothing buried at the end that an agent needs first.

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 seven-parameter, five-required quoting tool with no output schema, the definition covers the return envelope, expiry timing, direction semantics, the leverage dependency, and amount encoding. It omits guidance on slippage defaults and on sequencing with build_adjust, which keeps it short of complete.

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

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

Schema coverage is 86 percent, so the baseline is 3, and the description exceeds it. The schema lists leverage as optional and never encodes the conditional requirement that 'push' needs leverage; the description supplies exactly that rule. It also restates that amounts are base-unit integer strings, reinforcing the format beyond the pattern in the schema.

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

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

The description pairs the specific verb "Quote" with a concrete resource: adjusting collateral, split into 'push' (add) and 'pull' (withdraw). The sibling list contains build_adjust and simulate, which are the natural confusions, and the description never explicitly says it only returns a quote rather than executing one, so differentiation is implied by the name rather than stated.

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

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

It gives a real usage condition by tying 'push' to a leverage requirement, which tells the agent when the extra parameter is mandatory. However, it never states when to pick this over build_adjust or simulate, nor does it say a quote must precede a build, leaving the routing decision 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=true and idempotentHint=false, and the description goes meaningfully beyond them: it names the return shape (a quote envelope), identifies the `expiresAt` field as unix milliseconds, and states the 180-second expiry window, which explains why the tool is non-idempotent. It adds useful context on unit encoding, though it does not say whether the quote must be consumed by a specific build/simulate step or what happens if it lapses.

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, front-loaded with the action, followed immediately by the two facts an agent cannot get from the schema: envelope shape with expiry, and amount encoding. No filler or restatement of the name.

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 five-parameter quote tool with no output schema, the description covers the return envelope and expiry well enough to call it correctly. The notable gap is workflow placement — nothing ties the resulting quote to build_borrow or simulate, and it does not say whether the optional marketId needs to match an existing position's market.

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 80%, and the description fills the one real gap by stating that amounts are base-unit integer strings — the `borrowAmount` parameter has no description in the schema, so this prevents a decimals-vs-base-unit mistake on the most error-prone input. The remaining parameters are already documented in the schema and need no repetition.

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?

"Quote borrowing more against a position" gives a specific verb (quote) and resource (borrowing against an existing position), which distinguishes it from the open/close/repay quote siblings by implying an incremental borrow on a live position. It stops short of naming the sibling it should not be confused with, such as quote_adjust, so the differentiation is inferential rather than explicit.

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 when-to-use guidance: it never says to call this before build_borrow, never contrasts it with quote_adjust or quote_open, and never notes prerequisites such as holding an existing position. An agent must infer the quote-first workflow entirely from the naming convention across 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=true and idempotentHint=false, so the safety profile is covered; the description adds real value by disclosing the 180-second expiry and that `expiresAt` is unix ms. It does not describe auth requirements, rate limits, or what happens if a stale quote is passed downstream, so it enriches but does not fully characterize 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?

Four short sentences, front-loaded with the purpose and mode semantics, then chaining guidance, then expiry and unit conventions. Every sentence carries distinct information with no restatement of the 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 no output schema, the description usefully covers the return envelope, the `rewards` field, and expiry semantics, and it explains the conditional slippage parameter. Missing only edge conditions such as expired-quote failure behavior or supported chains.

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 80%, and the description goes beyond the bare enum by explaining what each `mode` value does and that 'compound' requires slippage. It also flags that amounts are base-unit integer strings, though it does not restate the slippage decimal-vs-fixed-point convention.

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: 'Quote claiming rewards', and names the downstream consumer (build_claim), which separates it from the build_* siblings. It never explicitly says it does not submit a transaction, so the quote-vs-execute boundary is implied by naming convention rather than stated.

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

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

Gives concrete when-to guidance through the two modes ('send' pays the owner, 'compound' swaps into the position and requires slippage) and explains that the returned `rewards` feed build_claim. There is no explicit exclusion such as 'do not use to execute; use build_claim' or a note on which chains/positions are supported.

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 establish that this is a read-only, non-idempotent operation. The description adds useful behavioral context by noting the quote envelope, unix-ms expiresAt, 180-second expiry, and base-unit integer amount format.

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

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

The description is short and front-loaded: it first states the operation, then the return/expiry behavior, then amount formatting. Every sentence carries useful information without repetition.

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 quote-generation tool with no output schema, the description covers the key return envelope, expiry, and amount units. It could be more complete by explaining how the returned quote is consumed, such as whether it feeds into build_close.

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

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

Schema coverage is 100%, so all four parameters are already documented, including slippage and strategyId. The description adds only general amount-format context and does not clarify individual parameter meanings 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 action and scope: generating a quote for closing a position in full. It distinguishes itself from sibling quote tools by specifying a full close rather than an adjustment, borrow, repay, or open.

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 phrase 'closing a position in full' implies when the tool is relevant, but it does not explicitly compare it with quote_adjust, build_close, or other siblings, nor does it state prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=false, and the description stays consistent with that (quoting, no state change). It adds genuinely useful behavior beyond the annotations: the return is a quote envelope, expiresAt is in unix ms, quotes expire after 180 seconds, and all amounts are base-unit integer strings.

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 resource and its outputs, then return envelope and expiry, then the unit convention. No redundant restatement of the name or 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?

For a 7-parameter, 5-required preview tool with no output schema, the description covers the key outputs, the expiry contract, and unit formats. The main remaining gap is not explaining how the quote relates to the build_open call that consumes 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 86%, so most parameters are already documented in the schema, including the leverage and slippage semantics. The description only reinforces unit conventions ('amounts are base-unit integer strings') and says nothing about the undocumented collateralToken or borrowToken parameters beyond what the schema already covers.

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 (quote) and resource (opening a leveraged position) and enumerates what the quote computes: expected collateral, debt, health factor and liquidation price. It does not explicitly distinguish itself from the sibling build_open, though 'Returns a quote envelope' implies a preview-only counterpart.

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 rather than stated; the description never says 'use this before build_open' or contrasts with quote_adjust/quote_repay. The 180-second expiry note is the only procedural guidance, hinting that the quote must be consumed promptly, which is useful but indirect.

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 annotations, it discloses crucial operational behaviors: the return of a quote envelope, the expiration mechanism (unix ms format), and the fixed expiration window (180 seconds). This provides high-value context for execution.

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 highly efficient. It front-loads the purpose, clearly defines the behavioral trade-offs of the modes, and concludes with output metadata, with 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?

Given the complexity of a multi-mode financial quoting tool, the description is complete. It covers input constraints (mode-specific logic), output format (envelope), and output lifecycle (expiration time).

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

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

The description adds valuable semantic information, specifically that the amounts are 'base-unit integer strings' and specifies that slippage requirements are tied to the 'auto' mode. This compensates for the 29% coverage gap in the schema.

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

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

The description clearly states the purpose is 'Quote repaying debt.' It effectively distinguishes itself from sibling tools by explaining the mechanism of debt repayment ('auto' vs 'manual').

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 how to use the 'auto' mode (via flash-loan swap and requires slippage) versus the 'manual' mode. This tells the agent exactly which scenario the tool is designed for.

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 readOnly/openWorld/non-idempotent; the description adds real substance on top: failure reporting is per-step, the return carries an `ok` flag and revert reasons, and `share` defaults to 'failure-only' so passing simulations are never published. It could go slightly further on fork conditions or latency, but the mutation-safety and privacy profile is well covered.

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 its precondition, then the invocation constraint, then the check-on-ok contract, then the retry path, then the privacy default. No sentence is filler; each adds a distinct 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?

With no output schema, the description still explains the meaningful return surface (`ok`, per-step revert reasons) and the side effect of `share`, which is enough to use the tool correctly. Minor gaps remain around what a fork simulation does not catch, but the essential contract 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 only 50%: `from` and `expiresAt` are documented, `share` is an undocumented enum. The description compensates for the biggest gap by explaining `share`'s default and privacy implication, and clarifies provenance constraints for `steps`/`expiresAt` (must be passed exactly as returned by a build_* tool). The internal step shape remains unexplained, but the schema's required fields plus labels carry much of that.

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 (simulate) on a specific resource (built steps on a Tenderly fork) and names the precondition (owner's address, before anyone signs). It is clearly distinguishable from the sibling build_*/quote_* tools because it consumes their output rather than producing it.

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 sequencing: call after a build_* tool, pass steps and expiresAt verbatim, check ok, and never ask anyone to sign a failing build. It also names a concrete remediation path (rebuild with forceSwapper: true for swap-route failures) and scopes that remedy to the specific sibling tools where it applies.

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