Vitro

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds genuine context by itemizing what the analysis surfaces (weekend gaps, USDG pause/freeze risk), which an agent cannot infer from the schema. It does not describe the output shape, but with no output schema that is the main remaining gap.

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

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

Two sentences, no filler. The risk-factor list comes first (what you get), the input modes second (how to call it) — correctly front-loaded for an agent deciding whether to invoke.

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 4-param, single-required-field read tool with full schema coverage and no output schema, this is nearly complete: it says what is analyzed and which parameters select which mode. Missing only edge-case behavior, such as precedence when both owner and hypothetical inputs are provided.

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, but the description adds meaning the per-parameter descriptions don't: that owner and collateral/debtTokens are alternative modes rather than independently combinable inputs. It does not resolve what happens if both modes are supplied simultaneously.

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 ('Plain-language risk for a position') and enumerates the exact risk dimensions covered: liquidation distance, weekend gaps, expiry, settlement rules, USDG pause and freeze risk. That scope distinguishes it cleanly from get_position (raw state) and quote_position (pricing) among the 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?

Explicitly defines the two invocation modes — pass 'owner' for a real position, or 'collateral' and 'debtTokens' for a hypothetical one — which is the key routing decision. It stops short of naming an alternative sibling (e.g., use get_position for raw numbers) or stating when this analysis is unnecessary.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that events are indexed and paginated, but it does not explain ordering defaults, cursor behavior, or result shape beyond what annotations provide.

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

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

The description is a single, front-loaded sentence with no filler. Its brevity is appropriate, though it leaves several parameters unexplained.

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 8 optional parameters, low schema coverage, and no output schema, the description is too thin to fully prepare an agent to call the tool correctly. It does not explain pagination mechanics, ordering, block-range filtering, or cursor semantics.

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 only 25%, so most of the 8 parameters are not documented in the schema. The description says "filterable and paginated" but does not explain limit, order, cursor, account, fromBlock/toBlock, or what the type parameter accepts beyond the schema's own list.

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 resource (indexed events) with concrete event examples and notes filtering/pagination. It is clear what the tool returns, though it does not explicitly distinguish this read tool from the many sibling tools, most of which are unrelated get_/prepare_ operations.

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 "filterable and paginated" implies that this is a list/query tool, but there is no explicit guidance on when to use it versus alternatives, nor any when-not conditions. Usage is inferable but not spelled out.

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 the safety profile is covered. The description adds that the measurement is relative to the chain head, which is real context, but says nothing about what 'lag' means operationally (blocks, seconds, boolean) or what a healthy versus unhealthy response looks like.

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 no filler. The only weakness is that 'Proof indexer' is clipped phrasing that costs a moment of parsing.

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

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

With no output schema and no parameters, the description carries the burden of explaining what comes back, and it does not — an agent cannot tell whether it will receive a numeric lag, a boolean health flag, or a status string. For a low-complexity diagnostic tool this is acceptable but leaves a real gap.

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 tool takes zero parameters, so there is no parameter semantics to compensate for; the baseline of 4 applies. The description correctly implies no inputs are needed.

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 resource (the proof indexer) and a specific measurement (progress and lag versus chain head), which is clearly distinct from every sibling tool (markets, positions, prepare_*). The verb 'Proof' is unusual phrasing, but the intended meaning (check indexer sync state) is recoverable.

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: an agent can infer this is a diagnostic/precondition check used to confirm the indexer is caught up before trusting other data. There are no explicit when/when-not statements and no guidance on how to act on a lag result.

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 and openWorld, so the safety profile is covered. The description does add real context by disclosing hybrid sourcing (Proof API snapshot plus a live on-chain price/phase check), which hints at freshness and network dependency, but it says nothing about behavior for unknown markets or partial source failures.

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 no filler; the core fact (one market) leads. The parenthetical 'Proof API' is slightly cryptic but compact.

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 convey what comes back; it sketches three things (market detail, live price, phase) but leaves 'detail' undefined, so an agent cannot anticipate the returned fields or structure.

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 single parameter has 100% schema coverage, including an address-or-symbol description and an example (NO-NVDA). The description adds nothing beyond that, which is the expected baseline when the schema does the work.

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 resource (a single market) and states what is returned: market detail plus a live price and phase check. Implicitly contrasts with list_markets by emphasizing 'one market in detail', but the terminology ('Proof API') is jargon an agent may not resolve.

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: pick this when you need detail on a single market rather than a listing. There is no explicit when-to-use/when-not, no mention of list_markets as the alternative, and no prerequisites or failure 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 already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real context beyond that: results are a hybrid of an external indexer (Proof) and live on-chain reads, which tells the agent the two halves may have different freshness. It stops short of stating staleness or failure behavior, 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?

Two sentences, no filler. The data-source and returned-field summary comes first, and the optional-parameter rule is placed last where it is most actionable. Every clause carries 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?

There is no output schema, so the description carries the return-value burden, and it does list the components returned (collateral, debt, residual, claimable, synth balance, indexed history). For a two-parameter read tool with full annotation coverage this is close to complete; only units, freshness guarantees and behavior for an unknown market are 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 both parameters are already documented, including that market accepts an address or a symbol like NO-NVDA. The description still adds value the schema lacks by defining the semantics of omitting market (return all markets). That is a small but meaningful increment over the baseline 3.

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

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

The description names the resource precisely and enumerates the exact data returned: indexed history from Proof plus live collateral, debt, residual, claimable and synth balance. That is far more specific than the tautological title. It does not, however, explicitly distinguish itself from the nearest sibling, quote_position, which an agent could easily confuse with a read-only position lookup.

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?

"Omit market for all markets" is a genuine usage instruction for the optional parameter, so some guidance is present. But there is no statement of when to prefer this over quote_position, nor any prerequisite or error condition guidance. Usage is implied rather than 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?

Beyond the annotations (which confirm it is a safe, read-only, idempotent operation), the description provides critical operational context, specifying that the tool handles both past results (settlement details) and present/future states (settlement windows).

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 definition is highly efficient, delivering maximum informational density in a single, well-structured sentence without redundancy.

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 simple 1-parameter input schema and the richness of the annotations, the description is perfectly complete. It provides all the necessary context for an AI agent to know exactly when and why to invoke this specific 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?

The schema defines the `market` type, but the description adds crucial semantics by providing examples (e.g., 'NO-NVDA') and clarifying that the input can be either a market address or a symbol, greatly aiding parameter interpretation.

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 precisely defines the dual purpose of the tool: retrieving historical settlement data (round id, price, etc.) or checking the current status and future schedule of settlement windows. This is highly specific and clearly distinguishes it from list-based or preparation tools in the sibling set.

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?

While it doesn't explicitly contrast against every sibling, it establishes a clear domain for use—settlement status and historical records—which implicitly guides the agent's use case away from position management or trade preparation tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds no behavioral context beyond the field list: no indication of snapshot freshness, aggregation window, units, or whether the figures are live vs. cached — notable gaps for an openWorldHint data 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?

It is a single short fragment with no padding, so nothing is wasted. But it is under-specified rather than concise: a sentence frame ('Returns protocol-wide ...') would have cost two more words and removed the ambiguity about scope.

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 and no parameters, the description is the only source of information about the return value, and it names four metric families without units, structure, or scope. For a parameterless stats endpoint, an agent still cannot tell what shape the response takes or whether 'per-market use of caps' is keyed by market id.

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 tool takes zero parameters, so the schema baseline of 4 applies. The description's field enumeration is consistent with a parameterless aggregate call.

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 enumerates what the tool returns (TVL, treasury fees, liquidations, per-market cap usage), which tells an agent the resource is protocol-level statistics. However, it is a noun fragment with no verb and no scope statement (protocol-wide vs. filtered by market/account), and it does nothing to distinguish it from siblings like get_health, get_market, or get_series_settlement.

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 guidance on when to call this versus get_health, get_market, or get_events. The agent must infer from the metric list alone that this is the aggregate-dashboard call, and there is no statement of 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 readOnly, idempotent, non-destructive and open-world behavior, so safety is covered. The description adds useful provenance (Proof API) and the returned field set, but says nothing about volume, ordering, or whether the result is paginated — which matters since it claims to return ALL markets.

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 dense sentence with the resource front-loaded and the returned fields packed into a compact list. No waste, though the telegraphic phrasing leaves the key 'all markets, optionally filtered' nuance unstated.

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

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

For a simple read-only list tool with no output schema, the description covers the source and the fields returned, and annotations carry the safety profile. Minor gaps remain around pagination, ordering, and the existence of the status filter, but an agent could call this correctly as-is.

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?

One optional parameter with 0% schema description coverage; the enum values are self-explanatory but the description never mentions that a status filter exists. Worse, 'All Vitro markets' can read as implying an unfiltered result set, so the description does not compensate for the coverage gap.

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 the specific resource (Vitro markets) and enumerates the payload it returns (status, expiry, caps, totals, price), so an agent knows exactly what comes back. Sibling differentiation is only implicit — it never states how it differs from get_market or list_series, though the plural name conveys listing.

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?

No when-to-use, when-not-to-use, or alternative routing is given. The agent must infer that this is the discovery tool versus get_market for a single market, and nothing tells it whether filtering by status is preferred over listing everything and filtering client-side.

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 the safety profile is covered. The description adds useful scope context — that both current and past series are returned along with settlement data — but says nothing about result volume, ordering, or whether unfiltered calls return everything.

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 short sentence fragment with zero redundancy and the most informative content (scope plus returned fields) up front; it errs toward under-specification rather than verbosity.

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-optional-filter read tool with no output schema, the description conveys the returned fields reasonably well, but it leaves the agent guessing whether parameters are filters, whether results are paginated, and how it relates to the settlement-specific sibling.

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%: 'asset' is documented as a ticker in the schema, while 'state' is an undescribed current/past enum. The phrase 'current and past' loosely maps to the state filter, but the description does not explain that asset is a filter or confirm that both parameters are optional.

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 (series) and the fields returned (settlement round, price, settler), so the retrieval intent is inferable, but it is a noun-phrase fragment with no verb and no differentiation from siblings like get_series_settlement or list_markets, which also deal with series data.

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 guidance on when to use this tool versus get_series_settlement, list_markets, or get_events, and no statement about whether the filters are optional or what happens when none are supplied.

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, and the description adds real value beyond them: returns UNSIGNED transaction data, simulates against the latest block, refuses if it would revert, and never signs or sends. This resolves the apparent tension between a mutating-sounding name and readOnlyHint=true. It stops short of describing failure payloads or what happens on simulation refusal.

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 dense sentence with the precondition front-loaded and every clause carrying information: the branches, the return shape, the simulation guard, and the no-signing guarantee. 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?

No output schema exists, and the description compensates by naming the return fields (to, data, value, gas). Combined with the simulation and refusal behavior, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both parameters (owner, market) are already documented including the symbol-or-address flexibility. The description adds no parameter-level meaning beyond the schema, so the 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 specific operations (withdrawResidual, redeem synth, claim top-up) and the resource (post-settlement position/wallet). It distinguishes itself implicitly by saying the tx is for "the user's own wallet," implying the prepare_mandate_* siblings cover delegated variants, but never names them 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?

"After settlement" gives a clear triggering condition, and the enumerated branches (withdrawResidual / redeem if open / claim top-up) tell the agent which case applies. It does not explicitly exclude or name the alternative prepare_mandate_close_and_redeem, so routing between the two requires 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: discloses the 11 USDG minimum, cap enforcement, fresh-price requirement, pre-flight simulation against the latest block, and explicit refusal on revert. 'Never signs or sends' reinforces and explains readOnlyHint=true rather than contradicting it, since unsigned transaction data is returned.

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 the action and followed by constraints and return shape. No filler and nothing restated from 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?

Even without an output schema, the description names the returned fields (to, data, value, gas) and the failure mode (refused if simulation reverts), so an agent knows both what it gets back and how the call can fail.

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 owner, market, collateral, and mintTokens are already documented with examples. The description adds only the 11 USDG floor for collateral and mentions 'tokens' generically for mintTokens, which is marginal value 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+resource ('Open or add to a position') and enumerates the composed steps (USDG approval, then create with collateral/tokens). The phrase 'for the user's own wallet' implicitly separates it from the prepare_mandate_create_position siblings, but 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?

Usage is implied through preconditions (11 USDG minimum for new positions, 'if needed' approval) and the ownership scoping, but the description never says when to choose this over prepare_mandate_create_position, quote_position, or get_position when deciding whether to open versus inspect a position.

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 an approval step may be inserted, that both caps are checked, that the result is UNSIGNED calldata (to, data, value, gas), that it is simulated against the latest block and refused on revert, and that it never signs or sends. These are exactly the behavioral facts an agent needs and none are in the annotation set.

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, zero filler: action first, then guards, then return shape, then the safety boundary. Every clause carries information the agent would otherwise have to guess.

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 return payload (to, data, value, gas) and adds the failure semantics (refused if simulation reverts). Nothing needed to call or interpret this three-parameter tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by framing amount as the deposit input and noting that both caps are checked against it, telling the agent that an out-of-range amount will fail rather than silently clamp. Minor value-add over the schema, hence 4 rather than 3.

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

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

States a concrete verb and resource ('Add collateral to an existing position') plus the underlying call sequence (approval then deposit). The phrase 'for the user's own wallet' implicitly separates it from the prepare_mandate_deposit sibling, so an agent can place it in the family 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 implied by 'add collateral to an existing position', which tells the agent the position must already exist, but there is no explicit 'use this instead of prepare_mandate_deposit / prepare_create_position' guidance. With 22+ siblings including a near-duplicate mandate variant, the missing routing sentence is a real 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?

Goes well past the annotations: it discloses that limits are checked, output is simulated first, results are UNSIGNED and never signed or sent, and that the call returns EIP-712 typed data rather than a transaction above the approval threshold. It also flags a failure mode (contract owners rejected) that the agent could not infer from readOnlyHint/idempotentHint.

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 post-settlement action sequence and then branches into the threshold behavior in a single tight paragraph. Dense but waste-free; the 'paid to the account' clause and the Safe example each pull weight.

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

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

With no output schema, the description carries the return-value burden and does: unsigned transaction data normally, EIP-712 typed data above threshold, simulation performed first. Together with the refusal case, that covers everything an agent needs to invoke and interpret this 5-parameter, nested-object 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 3 is the baseline, but the description adds workflow meaning the schema does not: the approval object exists only above the threshold, and the returned typedData is what the owner signs. Session key ownership ('Not held by this server') is already in the schema, so no extra credit there.

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 the concrete operations (withdrawResidual, redeem and claim) and the timing condition (after settlement) plus the destination (paid to the account). That distinguishes it from the plain prepare_close_and_redeem and from prepare_mandate_withdraw_residual, though it never explicitly contrasts itself with those siblings by name.

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?

'After settlement' establishes the precondition, and the threshold branch explains which path the caller will get and when the owner-signature path applies. It also states a hard exclusion (refuses when the owner is a contract such as a Safe), but it never tells the agent when to pick this over prepare_close_and_redeem or a narrower prepare_mandate_* 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?

Beyond the annotations, the description discloses critical behavioral traits: the owner is irrevocable with no recovery, the contract is unaudited, the operation is simulated first and refused on revert, and the output is unsigned transaction data that is never signed or sent. This is exactly the kind of safety and lifecycle context an agent needs before invoking the tool.

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

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

The description is dense but front-loaded: it defines the resource, then layers constraints and output behavior in short, purposeful sentences. Every sentence contributes unique 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 the absence of an output schema and the complexity of an irreversible, unaudited smart-account creation flow, the description covers the essential gaps: prerequisites, irreversibility, simulation behavior, unsigned return format, and never signing or sending. An agent has enough information to call it correctly and understand the consequences.

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 the owner and salt parameters are already well documented in the schema. The description adds only marginal context by tying the owner to 'the owner's own wallet' and the simulated sender; it does not elaborate on the salt's behavior beyond what the schema states.

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

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

The description opens with a specific verb and resource: 'Create a mandate account', and immediately defines what a mandate account is. It clearly distinguishes this from sibling operations like prepare_mandate_create_position or prepare_mandate_deposit by focusing on account creation 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?

It gives clear context for when the tool is usable ('Refused while mandates aren't enabled on this server') and an important exclusion ('Existing positions can't be moved into it'). However, it does not explicitly name alternative tools or state a recommended sequence, such as using this before grant-session or deposit operations.

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: results are simulated first, the output is unsigned (never signed or sent), there is an approval threshold that switches the return type to EIP-712 typed data, and the tool hard-refuses for contract owners. That is exactly the operational context an agent needs before calling, none of which annotations 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 dense sentences, front-loaded with the action and followed by the two conditional branches and the safety guarantee. No filler and 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?

For a 7-parameter tool with a nested approval object and no output schema, the description covers the return shape (unsigned tx data vs. EIP-712 typed data), the preconditions, and the failure mode. An agent can decide whether and how to call it without further guessing.

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 genuinely adds meaning about the approval object — it only applies above the threshold and pairs with typedData from a prior call. It does not mention approvalTtlSeconds or clarify the market/collateral/mintTokens interplay.

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 action (open or add to a position via create(collateral, tokens) through the mandate account) and names the key mechanism — account-set allowance — that separates it from the plain prepare_create_position sibling. It never names that sibling outright, so the differentiation is implied 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?

Gives clear when-conditions: normally returns unsigned tx data, above the approval threshold returns EIP-712 typed data, and it refuses when the owner is a contract such as a Safe. The exclusion is explicit, but it offers no routing advice toward related siblings like prepare_mandate_create or prepare_mandate_set_limits.

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: the simulation step, the 'never signs or sends' guarantee, the two distinct return shapes (unsigned tx vs EIP-712 typed data), and the hard failure mode for contract owners are all disclosed. These are exactly the behaviors an agent needs to avoid treating this as a signing tool, and they are consistent with readOnlyHint=true.

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 action and the return contract, then the branch and the refusal case. No filler and 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 carries the return-value burden and does so by naming both possible payloads. Combined with the threshold branch and the contract-owner refusal, an agent has everything needed to call this correctly or recognize when it will fail.

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 100%, so the baseline is 3; the description adds value by explaining that the nested 'approval' object is only used above the threshold and that it carries the owner's EIP-712 signature — the schema states the field shape but not the triggering condition. Minor gap: it doesn't clarify amount precision or market symbol resolution beyond what the schema says.

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+resource ('Add collateral to the account's position') and immediately characterizes the return as UNSIGNED transaction data, which separates it from the read-only siblings like get_position. It doesn't explicitly name the adjacent write siblings (prepare_deposit, prepare_mandate_withdraw_collateral) to route the agent, 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?

Gives clear conditional guidance: the session-key path is the default, the EIP-712 owner path applies 'above the approval threshold', and the tool 'refuses when the owner is a contract, such as a Safe' — a genuinely useful exclusion. It stops short of naming alternative tools for the Safe/contract case, leaving the agent to infer where to go.

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 substantial context beyond the annotations: it returns UNSIGNED transaction data for the owner's wallet, simulates first and refuses on revert, never signs or sends, the server never holds the key, and replacing a session restarts its mint budget. These are exactly the operational facts an agent needs and that readOnlyHint/idempotentHint alone 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?

Four short sentences, front-loaded with the core action, then the caveats (budget reset, key custody, unsigned/simulated output, no signing). No filler and nothing repeated from 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?

There is no output schema, but the description explains the return well ('unsigned transaction data for the owner's own wallet; simulated first and refused if it would revert'). For a prepare-style, five-parameter tool whose schema is fully documented, this covers 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%, so account, markets, sessionKey, validForSeconds, and the optional actions list are already documented in the schema. The description only echoes 'listed markets' and 'until it expires' without adding format, defaults, or interaction rules beyond what the schema states, so the baseline of 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 first sentence names the exact verb and resource ('let a session key act for the account') plus scope ('inside its limits, on the listed markets until it expires'). That is clearly distinguishable from sibling grant-lifecycle tools such as prepare_mandate_set_limits (caps) and prepare_mandate_revoke_session (teardown).

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 context is implied well: you call this to authorize a session key, and 'inside its limits' signals that limits must already exist, which the schema makes explicit by pointing at prepare_mandate_set_limits. The description doesn't state exclusions or name an alternative path (e.g., when to prefer revoking and re-granting), so it stops 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?

Goes well beyond the annotations: it discloses that the call ignores session limits and works with every session key revoked, that it returns UNSIGNED transaction data, that it is simulated first and refused if it would revert, and that it never signs or sends. Those are exactly the traits an agent needs before invoking a prepare-style tool, and they are consistent with readOnlyHint=true and destructiveHint=false.

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 what the tool does, then the 'all' special case, then the owner-only behavior, then the return contract. No sentence is redundant and each adds distinct information.

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

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

There is no output schema, and the description covers the return (unsigned transaction data, simulated, refused on revert) as well as the execution boundary (never signs or sends). With all four parameters required and fully described, nothing material is missing for a correct call.

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 each parameter already documents itself, including the 'all' option for tokens. The description reinforces the 'all' semantics and the owner-only constraint but adds no new syntax, formatting, or edge-case detail beyond the schema, so the 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?

Opens with a specific verb and resource: burn synth held by the account to reduce its debt, plus the 'all' shorthand. It also scopes itself as owner-only, which separates it from the session-key path, but it never names the sibling (prepare_mandate_repay) it is the alternative to, leaving the agent to infer the split.

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?

'For the owner only' and 'prepares exactly this one market call and nothing else' give context, and the 'all' behavior is stated. However, there is no explicit when-to-use-this-vs-prepare_mandate_repay rule (e.g. no session key vs. session key), so the routing decision is implied rather than 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?

Adds substantial context beyond annotations: it clarifies the readOnlyHint=true is because it "never signs or sends" and only returns UNSIGNED transaction data, discloses a simulate-first/refuse-on-revert safeguard, and notes the owner address gate. This resolves the otherwise confusing readOnly flag on a transaction-building 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?

Purpose is front-loaded in the first sentence and every later sentence carries a distinct constraint (max semantics, owner-only, single call, unsigned output, simulation). Slightly dense with the quoted "max" aside breaking the flow, but 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?

With no output schema, the description correctly tells the agent the return is unsigned transaction data and that reverts are refused up front, which is what's needed to act on it. It leaves the exact response shape/pagination unstated, a minor gap for a 4-param transactional 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 baseline is 3; the description adds meaning by explaining that "max" means "the most the market allows" and by reinforcing that only the owner address is accepted. It does not elaborate on market symbol resolution or amount formatting 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?

Specific verb+resource ("Move collateral from the position to the account") plus a scoping clause ("prepares exactly this one market call and nothing else") that separates it from the compound prepare_mandate_close_and_redeem sibling. The "For the owner only" framing distinguishes it from the session-key variant prepare_mandate_withdraw_collateral.

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 the selecting condition clearly: this is the owner path that "works with every session key revoked, ignores session limits, and still follows the market's rules," which implies the sibling collateral-withdraw tool is the session-key path. It stops short of naming that alternative explicitly, so the agent must infer the pairing from 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?

Adds substantial context beyond the annotations: it returns UNSIGNED data only, simulates first and refuses on revert, never signs or sends, bypasses session-key revocation and session limits, and still enforces market rules. This reconciles readOnlyHint=true with an operation that ultimately moves funds by making explicit that only calldata is produced.

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 timing precondition, then actor scope, then scope limitation, then return semantics — four short sentences with no filler. Every clause carries decision-relevant 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?

With no output schema, the description still tells the agent what comes back (unsigned transaction data for the owner's wallet), how failure manifests (simulated first, refused on revert), and that it is single-call scoped. Nothing needed 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%, and the schema already documents owner ('Refused for any other address'), market (address or symbol), and account. The description's 'for the owner only' restates the owner constraint rather than adding format or usage detail beyond the schema, so the 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 ('prepare... close the account's position and pay the residual to the account') and pins the triggering condition ('After settlement'). The owner-only framing ('works with every session key revoked, ignores session limits') functionally separates it from the session-key withdraw siblings without needing to name them.

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

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

Gives clear conditions for use: only after settlement, only for the account owner, and only for this single market call. It does not explicitly name the alternative to reach for in the non-owner or pre-settlement case, so the agent must infer the fallback from sibling names rather than being routed.

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, the description discloses important behavior: it burns synth to reduce debt, supports 'all', works with stale prices, checks account limits, simulates first, returns unsigned transaction data for the session key, switches to EIP-712 typed data above the approval threshold, and refuses contract owners. It also clearly states it never signs or sends, which is consistent with readOnlyHint=true and destructiveHint=false.

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 then adds only operationally useful details such as stale-price handling, simulation, approval-threshold behavior, and contract-owner refusal. Every sentence contributes to correct invocation without redundant restatement.

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

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

The description is complete enough for a complex prepare tool with nested approval data and no output schema: it explains the two possible return modes and key constraints. It could be slightly richer about the returned transaction/typed-data shape, but the critical behavioral context 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%, so the schema already documents the parameters well. The description reinforces the meaning of 'all' and the approval-threshold behavior, but most parameter semantics are already available in the structured schema, making this a baseline 3.

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

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

The description states a specific verb and resource: burn synth held by a mandate account to reduce its debt, and it explains the returned unsigned transaction or EIP-712 data. It does not explicitly differentiate itself from the sibling prepare_mandate_owner_repay, so it falls short of full sibling-aware clarity.

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 some usage context: 'all' repays the whole debt, it works while price is stale, and it refuses when the owner is a contract such as a Safe. However, it does not explicitly say when to choose this tool over alternatives like prepare_mandate_owner_repay, leaving relative usage implied rather than 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?

Goes well beyond the annotations: it discloses that the call returns UNSIGNED transaction data, is simulated first and refused if it would revert, takes effect only in the next transaction, and never signs or sends. This resolves the apparent tension between 'stop' and readOnlyHint/destructiveHint=false by making the prepare-only nature explicit.

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 action and scope, followed by timing and safety semantics. 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?

With no output schema, the description usefully characterizes the return as unsigned transaction data and warns of simulation refusal. It leaves open the exact payload shape and the required follow-up signing step, but an agent has enough to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real value by stating the mutual exclusivity between a single sessionKey and the 'all: true' switch, which the schema does not express. It does not clarify what happens if neither is 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?

States a specific verb (stop/revoke) and resource (session key), plus the two modes of scope (single key vs all). An agent can distinguish it from prepare_mandate_grant_session without inspecting 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?

It gives a selection rule for the scope flag ('all: true' for every key), which is genuine usage guidance. But it never says when to prefer this over siblings or what preconditions must hold (e.g. that account is required, or that a signing/sending step must follow).

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 substantial behavior beyond the annotations: it returns unsigned transaction data, simulates first, refuses if simulation would revert, never signs or sends, binds session keys rather than the owner, and refuses an invalid minimum ratio. These details are consistent with readOnlyHint=true and destructiveHint=false.

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

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

The description is compact and front-loaded: the core action appears first, followed by refusal behavior, signing behavior, and return semantics. Each sentence contributes 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 7-parameter preparation tool with no output schema, the description covers the essential context: what it configures, optional market caps, validation refusal, unsigned output, simulation, and the fact that it never signs or sends. The schema handles detailed parameter definitions.

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 high at 86%, so the baseline is 3. The description still adds useful cross-parameter semantics, notably that market caps are optional and that the minimum ratio is refused if at or below any market's own minimum.

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 resource: setting an account's limits and optional per-market caps. It is clearly distinct from sibling tools like prepare_mandate_create or prepare_mandate_grant_session, though it does not explicitly name those siblings for contrast.

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 'Set an account's limits' and by the optional marketCaps behavior, but the description does not explicitly state when to choose this tool over related mandate tools or any prerequisites/exclusions beyond the ratio refusal rule.

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?

Despite readOnlyHint=true, the description adds substantial behavior: checks account limits, returns simulated unsigned transaction data for the session key, returns EIP-712 typed data above the approval threshold, refuses contract owners, and never signs or sends. No contradiction with annotations.

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

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

Front-loads the core action and conditions, with every sentence carrying operational information. Some domain jargon ('the lag', 'first round') is dense, but the description is appropriately sized for a complex tool.

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 prerequisites (expiry, lag condition), return behavior (unsigned transaction vs EIP-712 typed data), refusal rules for contract owners, and the no-sign/no-send guarantee. With no output schema, this is complete enough for an agent 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 coverage is 100%, so all five parameters are already documented, including the approval object and sessionKey. The description confirms the conditional role of approval but adds no syntax or format details beyond what the schema provides.

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

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

States a specific verb and resource: prepare a mandate settlement through the account, only after expiry. It explicitly distinguishes itself from the sibling prepare_settle (ordinary wallet), so an agent can select it 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 says other settlement paths are not agent actions and names prepare_settle for ordinary wallets. Also gives clear when-not conditions: only while the first round landed inside the lag, and it refuses when the owner is a contract such as a Safe.

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 explains that the tool returns UNSIGNED transaction data for the owner's own wallet, that it simulates first and refuses on revert, and that it never signs or sends. These are exactly the behavioral facts an agent needs before committing to a prepare_* call, and they are consistent with readOnlyHint=true and destructiveHint=false.

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: what it sends, what is excluded, and what it returns. The scope constraint is front-loaded before the behavioral notes, with no wasted 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?

No output schema exists, but the description explicitly characterizes the return value (unsigned tx data) and the failure mode (refused if simulation would revert), and annotations cover the safety profile. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so all three parameters (token default USDG, amount as decimal or "all", account address) are already documented in the schema. The description adds no parameter-level detail beyond that, 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+resource (send idle tokens from the account to its owner) and draws the key boundary that collateral in a position is not idle, which differentiates it from the withdraw_collateral siblings. It stops short of naming the sibling tools explicitly, so the distinction from prepare_mandate_owner_withdraw_collateral must be inferred.

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?

"Send idle tokens" plus "Collateral in a position is not idle" gives an explicit when and a when-not condition. It does not name the alternative tool an agent should call for collateral, so routing is implied rather than spelled out.

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 nothing is signed or sent, that the call simulates first, and that the return type branches — unsigned transaction data for the session key normally, EIP-712 typed data for the owner above the approval threshold. The refusal condition for contract owners is a non-obvious failure mode that would otherwise surprise the agent. All of this is consistent with readOnlyHint=true and destructiveHint=false.

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 tight sentences: purpose and destination first, then the "max" semantic, then the flow, then the approval exception, then the no-signing guarantee. No filler, and the most safety-relevant constraint is stated last for emphasis without burying the main action.

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, and the description compensates by describing both possible return shapes and when each occurs. With 100% schema coverage on six parameters including a nested approval object, nothing an agent needs to invoke the tool or interpret its result is missing.

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

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

Schema coverage is 100%, so a 3 baseline applies, but the description meaningfully upgrades it by defining "max" as stopping at the account's minimum ratio and by explaining the approval branch that produces the nonce/deadline/signature object. The market and account params are left 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: moving collateral from a position back to the account, with the destination constraint made explicit. It does not name the closest siblings (prepare_mandate_withdraw, prepare_mandate_owner_withdraw_collateral), so an agent must infer the distinction, but the scope statement is precise enough to separate it from deposit/repay/close tools.

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

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

Gives clear operating conditions: "max" caps at the account's minimum ratio, limits are checked first, and the approval path only applies above the threshold. It also raises the exclusion that the approval route fails for contract owners (Safe), which steers the agent correctly. It stops short of explicitly contrasting with the sibling withdraw variants.

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 the result is an UNSIGNED transaction (to, data, value, gas), that it is simulated against the latest block and refused if it would revert, and that it never signs or sends. That last clause crucially reconciles readOnlyHint=true with a transaction-producing 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 tight sentences, no filler, with the core action and the return contract front-loaded and the safety semantics immediately after. 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?

For a prep tool with no output schema, the description covers the return shape, simulation/revert behavior, and non-custodial guarantee. What it omits is whether prior synth approval or balance preconditions matter and which sibling to choose for delegated repayment.

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 what the 'all' token value means behaviorally and by tying the tokens argument to the repay(tokens) call. Owner/market semantics are left 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 concrete verb and resource: burn synth from the wallet to reduce debt, exposing the underlying call repay(tokens). The phrase 'for the user's own wallet' implicitly separates it from the prepare_mandate_*_repay siblings, though it never names them 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?

The 'all' special value is explained behaviorally ('repays the whole debt'), which is useful usage guidance. However, there is no explicit when-to-use vs. when-not guidance and no routing to the closest alternatives (prepare_mandate_repay, prepare_mandate_owner_repay) — a real gap given 29 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?

Goes well beyond the readOnly/destructive annotations by disclosing that output is UNSIGNED tx data (to, data, value, gas), that it is simulated against the latest block and refused if it would revert, and that it never signs or sends. The path-selection windows (maxSettleLag, +7 days) are behavior an agent cannot infer from any structured field.

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 'After expiry' precondition and then packs rules efficiently with no filler sentences. It is a single dense paragraph, which is slightly harder to scan than bulleted branches would be, but every clause carries real 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?

With no output schema, the description supplies the return shape, the simulation/refusal semantics, and the self-custody boundary (never signs or sends). Combined with the schema, an agent has everything needed to call it and interpret the result.

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 `market` and `from` are already documented. The description adds the derived roundId concept used to build the proof, which is useful, but does not clarify the market symbol/address handling or the guardian-safe override beyond what the schema already states.

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

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

States a specific verb+resource (build the settle transaction) and describes the mechanics precisely: first Chainlink round at/after expiry, proof encoded as abi.encode(uint80 roundId), and the three possible call targets. It never distinguishes itself from the sibling prepare_mandate_settle, so an agent can't tell which of the two settle-preparation tools fits a mandate 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?

Explicit timing gates ('After expiry', 'Refused before expiry, once settled, and until the round has printed') and a clear fallback ordering between settle, guardianSettle, and settleBackstop tell the agent exactly when this applies. It stops short of naming the alternative sibling to use when these conditions fail.

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/idempotent annotations, it discloses the return payload shape (to, data, value, gas), that the transaction is unsigned, that it is simulated against the latest block, and that it is refused pre-emptively if it would revert. "Never signs or sends" directly resolves the main anxiety for a transaction-preparing tool marked readOnlyHint=true.

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 with the action first, then the amount special case, then the safety/return contract. No filler and no repetition of schema field names.

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 3-required-parameter preparation tool with no output schema, it covers the essential unknowns: what comes back, whether anything is signed or broadcast, the fresh-price dependency, and the reverting precondition. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning for the amount parameter by defining what "max" computes (minimum ratio plus 10 USDG floor) — information absent from the schema's terse '"max"' note. Owner and market semantics are 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 states a specific verb and resource ("Withdraw collateral") plus the underlying call signature withdraw(amount), and the phrase "for the user's own wallet" implicitly separates it from the many prepare_mandate_* withdraw siblings. It stops short of naming those alternatives explicitly, so the differentiation is inferable 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?

"Needs a fresh price when the position has debt" gives a concrete precondition, and the "max" note explains how to request a full withdrawal subject to the minimum ratio and 10 USDG floor. There is no explicit when-not-use or named alternative among the mandate-based withdraw tools, but the deployment context 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 cover read-only, idempotent and non-destructive, so the description earns credit for adding real behavior: it warns when the oracle price is stale or the market is closed, and it promises exact on-chain math rather than an approximation. It stops short of saying how those warnings surface in the response (flag 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?

Two tight sentences: the first front-loads what you get back, the second delivers the caveat. Nothing is wasted or repeated from 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?

With no output schema, the description usefully enumerates the returned fields and the staleness/closed-market caveat, which is enough for an agent to call it. The remaining gap is the relationship between the optional mint parameters, which is left entirely to the schema.

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

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

Schema description coverage is 100%, so all five parameters are documented in structured data and the baseline applies. The description hints at the collateral-deposit and minting paths but adds no disambiguation between mintTokens and mintValueUsdg or what happens when neither is 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?

Names the resource (a position quote) and enumerates the exact outputs: fee, collateral ratio, liquidation price, headroom, computed with the contracts' math at the current oracle price. Combined with 'Read-only' it implicitly separates itself from the many prepare_* mutation siblings, 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?

Usage is implied (a dry-run preview before depositing/minting), but the description never states when to call this versus get_position or the prepare_create_position/prepare_deposit siblings. No exclusions or prerequisites are given.

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