Skip to main content
Glama

Plan a position from assets the wallet holds

plan_ladder
Read-onlyIdempotent

Plans a ladder, a deposit spread over up to 40 narrow one-sided ranges (rungs) of one pool, from assets the wallet already holds, and returns the unsigned transactions. Use when the wallet holds the token, the quote asset, or both; with only ETH or USDG, prefer plan_build, which buys the missing side and builds in one transaction. Not for an order at one price (plan_limit_order). Rungs under the price hold the quote and buy as it falls; rungs over it hold the token and sell as it rises; each earns the pool's swap fee when traded through. Returns: transactions[] (to, data, value in wei, gas), check (simulated, ok, failedStep, reason, ethNeeded, ethHeld), sendWithin, ifItReverts, slippagePct, rungs (the band as laid), fees (0.25% of what goes in; then 5% of the fees earned, 3.5% with 100,000 LOOM staked for a week; every cut paid as USDG). Behavior: read-only on our side; nothing is signed or sent. The plan is laid out from the chain at this block and simulated from the owner; send it within check.sendWithin, and plan again rather than resend one that reverted. Costs quota units (agent_quota). Errors: refused with a reason when the band holds no rung, the pool has no money side, the amounts are zero, or the token is flagged.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "token": "<token>",
      "owner": "<owner>",
      "lowPct": "<lowPct>",
      "highPct": "<highPct>"
    },
    "name": "plan_ladder"
  }
}

Input Schema

NameRequiredDescriptionDefault
poolNoA pool id from ladder_pools. Left out: the token's default pool.
ownerYesThe wallet that signs, sends, and owns the ladder.
rungsNoHow many rungs across the band, 1 to 40; default 40.
shapeNoWhere the band puts the most: spot (even), curve (near the price), bidask (at the edges), hybrid (half spot, half bidask), custom (weights). Default bidask.
splitNoWith one asset only: swap part of it for the other in the same pool and build the whole band, in one transaction.
tokenYesThe token's address.
copyOfNoThe id of a ladder on the current contract this one copies: its owner is paid 0.1% while it stays open in the same pair.
lowPctYesThe band's bottom, in percent from the current price: negative for under it (for example -30).
highPctYesThe band's top, in percent from the current price (for example 40).
newPoolNoFrom plan_open_pool's `then`: a pool being opened in the same plan, so the ladder is laid against its key and opening price. No split in it; both amounts, or one for a one-sided ladder.
weightsNoshape custom only: a relative height per rung, low price to high, any scale; stretched over the rungs built.
referrerNoThe wallet that referred the owner: paid 0.1% of what goes in, out of the opening fee; kept by the contract from the owner's first ladder on.
fullRangeNoOne position across every price instead of a band. Never out of range, earns the least per dollar. Needs both amounts, or one with split: true; lowPct and highPct are ignored.
payWithEthNoFor a pool quoted in WETH: pay in plain ETH, wrapped inside the same transaction, nothing to approve. Default: whenever the wallet holds less WETH than amountQuote.
amountQuoteNoHow much of the quote asset to put in, as a decimal string. Builds the rungs under the price.
amountTokenNoHow much of the token to put in, as a decimal string. Builds the rungs over the price.
slippagePctNoRoom for the price to move before the transaction is mined, in percent. Left out: 2% on a calm pool, more on one that has been moving, at most 10%.
startMarketCapUsdNoFor a token that has never traded, built in the pool plan_open_pool is opening (newPool): the market cap it opens at, the same as given there.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / startMarketCapUsd
      Added value: +{
      +  "description": "For a token that has never traded, built in the pool plan_open_pool is opening (newPool): the market cap it opens at, the same as given there.",
      +  "exclusiveMinimum": 0,
      +  "type": "number"
      +}
  2. Changed18 schema fields changed
    • addedInput schema / properties / amountQuote / description
      Added value: +"How much of the quote asset to put in, as a decimal string. Builds the rungs under the price."
    • addedInput schema / properties / amountToken / description
      Added value: +"How much of the token to put in, as a decimal string. Builds the rungs over the price."
    • changedInput schema / properties / copyOf / description
      Previous value: -"The id of a ladder on the current contract this one copies: its owner is paid 0.1% while it is open in the same pair."New value: +"The id of a ladder on the current contract this one copies: its owner is paid 0.1% while it stays open in the same pair."
    • changedInput schema / properties / fullRange / description
      Previous value: -"One position across every price instead of a band of rungs. Never out of range and needs no watching; very little of the money sits at the price, so it earns the least per dollar. Needs both amounts, or one amount with split: true. lowPct and highPct are ignored."New value: +"One position across every price instead of a band. Never out of range, earns the least per dollar. Needs both amounts, or one with split: true; lowPct and highPct are ignored."
    • addedInput schema / properties / highPct / description
      Added value: +"The band's top, in percent from the current price (for example 40)."
    • addedInput schema / properties / lowPct / description
      Added value: +"The band's bottom, in percent from the current price: negative for under it (for example -30)."
    • changedInput schema / properties / newPool / description
      Previous value: -"From plan_open_pool's `then`, for a pool being opened in the same plan: the ladder is laid out against its key and opening price. No split in it (it is empty): both amounts, or one for a one-sided ladder."New value: +"From plan_open_pool's `then`: a pool being opened in the same plan, so the ladder is laid against its key and opening price. No split in it; both amounts, or one for a one-sided ladder."
    • addedInput schema / properties / owner / description
      Added value: +"The wallet that signs, sends, and owns the ladder."
    • changedInput schema / properties / payWithEth / description
      Previous value: -"For a pool quoted in WETH: pay in plain ETH, wrapped inside the same transaction, with nothing to approve. Default: whenever the wallet holds less WETH than amountQuote."New value: +"For a pool quoted in WETH: pay in plain ETH, wrapped inside the same transaction, nothing to approve. Default: whenever the wallet holds less WETH than amountQuote."
    • changedInput schema / properties / pool / description
      Previous value: -"A pool from ladder_pools; the default pool when left out"New value: +"A pool id from ladder_pools. Left out: the token's default pool."
    • changedInput schema / properties / referrer / description
      Previous value: -"The wallet that referred the owner: paid 0.1% of what goes in, out of the opening fee, and kept by the contract from the owner's first ladder on."New value: +"The wallet that referred the owner: paid 0.1% of what goes in, out of the opening fee; kept by the contract from the owner's first ladder on."
    • addedInput schema / properties / rungs / description
      Added value: +"How many rungs across the band, 1 to 40; default 40."
    • addedInput schema / properties / shape / description
      Added value: +"Where the band puts the most: spot (even), curve (near the price), bidask (at the edges), hybrid (half spot, half bidask), custom (weights). Default bidask."
    • changedInput schema / properties / slippagePct / description
      Previous value: -"Left out: 2% on a calm pool, more on one whose price has been moving (set from its last fifteen minutes, at most 10%)"New value: +"Room for the price to move before the transaction is mined, in percent. Left out: 2% on a calm pool, more on one that has been moving, at most 10%."
    • changedInput schema / properties / slippagePct / minimum
      Previous value: -0.1New value: +0.01
    • addedInput schema / properties / split / description
      Added value: +"With one asset only: swap part of it for the other in the same pool and build the whole band, in one transaction."
    • addedInput schema / properties / token / description
      Added value: +"The token's address."
    • changedInput schema / properties / weights / description
      Previous value: -"shape custom only: the height of each rung, low price to high, relative (any scale), stretched over the rungs built"New value: +"shape custom only: a relative height per rung, low price to high, any scale; stretched over the rungs built."
  3. Changed2 schema fields changed
    • changedInput schema / properties / weights / description
      Previous value: -"shape custom only: the height of each rung, low price to high, 0 to 1, stretched over the rungs built"New value: +"shape custom only: the height of each rung, low price to high, relative (any scale), stretched over the rungs built"
    • changedInput schema / properties / weights / items / maximum
      Previous value: -1New value: +1000000
  4. Changed2 schema fields changed
    • changedInput schema / properties / shape / enum
      Previous value: -[
      -  "spot",
      -  "curve",
      -  "bidask",
      -  "hybrid"
      -]New value: +[
      +  "spot",
      +  "curve",
      +  "bidask",
      +  "hybrid",
      +  "custom"
      +]
    • addedInput schema / properties / weights
      Added value: +{
      +  "description": "shape custom only: the height of each rung, low price to high, 0 to 1, stretched over the rungs built",
      +  "items": {
      +    "maximum": 1,
      +    "minimum": 0,
      +    "type": "number"
      +  },
      +  "maxItems": 40,
      +  "minItems": 1,
      +  "type": "array"
      +}
  5. Changed1 schema field changed
    • addedInput schema / properties / slippagePct / description
      Added value: +"Left out: 2% on a calm pool, more on one whose price has been moving (set from its last fifteen minutes, at most 10%)"
  6. Changed1 schema field changed
    • changedInput schema / properties / shape / enum
      Previous value: -[
      -  "spot",
      -  "curve",
      -  "bidask"
      -]New value: +[
      +  "spot",
      +  "curve",
      +  "bidask",
      +  "hybrid"
      +]
  7. Changed1 schema field changed
    • addedInput schema / properties / newPool
      Added value: +{
      +  "description": "From plan_open_pool's `then`, for a pool being opened in the same plan: the ladder is laid out against its key and opening price. No split in it (it is empty): both amounts, or one for a one-sided ladder.",
      +  "properties": {
      +    "key": {
      +      "properties": {
      +        "currency0": {
      +          "pattern": "^0x[0-9a-fA-F]{40}$",
      +          "type": "string"
      +        },
      +        "currency1": {
      +          "pattern": "^0x[0-9a-fA-F]{40}$",
      +          "type": "string"
      +        },
      +        "fee": {
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        "hooks": {
      +          "pattern": "^0x[0-9a-fA-F]{40}$",
      +          "type": "string"
      +        },
      +        "tickSpacing": {
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "currency0",
      +        "currency1",
      +        "fee",
      +        "tickSpacing",
      +        "hooks"
      +      ],
      +      "type": "object"
      +    },
      +    "sqrtPriceX96": {
      +      "pattern": "^\\d+$",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "key",
      +    "sqrtPriceX96"
      +  ],
      +  "type": "object"
      +}
  8. Changed2 schema fields changed
    • addedInput schema / properties / copyOf
      Added value: +{
      +  "description": "The id of a ladder on the current contract this one copies: its owner is paid 0.1% while it is open in the same pair.",
      +  "pattern": "^\\d+$",
      +  "type": "string"
      +}
    • addedInput schema / properties / referrer
      Added value: +{
      +  "description": "The wallet that referred the owner: paid 0.1% of what goes in, out of the opening fee, and kept by the contract from the owner's first ladder on.",
      +  "pattern": "^0x[0-9a-fA-F]{40}$",
      +  "type": "string"
      +}
  9. Changed1 schema field changed
    • addedInput schema / properties / fullRange
      Added value: +{
      +  "description": "One position across every price instead of a band of rungs. Never out of range and needs no watching; very little of the money sits at the price, so it earns the least per dollar. Needs both amounts, or one amount with split: true. lowPct and highPct are ignored.",
      +  "type": "boolean"
      +}
  10. Changed1 schema field changed
    • addedInput schema / properties / payWithEth
      Added value: +{
      +  "description": "For a pool quoted in WETH: pay in plain ETH, wrapped inside the same transaction, with nothing to approve. Default: whenever the wallet holds less WETH than amountQuote.",
      +  "type": "boolean"
      +}
  11. Added

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces and extends this: 'read-only on our side; nothing is signed or sent', simulated from the owner, time-limited by check.sendWithin, quota cost, and explicit error conditions (no rung, no money side, zero amounts, flagged token). It could go further on what happens when the simulated check fails mid-way, but the behavioral disclosure is well above the annotated baseline.

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

Conciseness4/5

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

Front-loaded with purpose and sibling routing, and uses inline labels ('Returns:', 'Behavior:', 'Errors:') to segment a dense block. It is long but nearly every clause carries decision-relevant information; the fee-schedule detail is the one portion that pads rather than guides tool selection.

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

Completeness5/5

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

For an 18-parameter tool with nested objects and no output schema, the description carries the full return-value burden: transactions[] fields, check subfields, sendWithin, ifItReverts, slippagePct, rungs, fees. Combined with enumerated failure modes, an agent has everything needed to call and interpret it.

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

Parameters4/5

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 earns extra by explaining economic semantics the schema omits — rungs under the price hold the quote and buy as it falls, rungs over hold the token and sell as it rises, and each earns the pool's swap fee. It also clarifies fee structure (0.25% in, then 5% of fees earned) and slippage defaults that supplement the schema's single-line slippage note.

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

Purpose5/5

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

States a specific verb and resource ('Plans a ladder, a deposit spread over up to 40 narrow one-sided ranges of one pool, from assets the wallet already holds') and immediately names the shape of the output (unsigned transactions). It is clearly distinguished from plan_build and plan_limit_order within the same paragraph.

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

Usage Guidelines5/5

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

Gives explicit use conditions ('Use when the wallet holds the token, the quote asset, or both'), an exclusion routing rule ('with only ETH or USDG, prefer plan_build, which buys the missing side'), and a negative case ('Not for an order at one price (plan_limit_order)'). All alternatives are named rather than implied.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources