LoomDesk

Plan a position from ETH or USDG, in one transaction

plan_build

Read-onlyIdempotent

Plans one transaction (two when paying in USDG: its approval first) from ETH or USDG to a ladder in a v4 pool of the token against the quote, and returns it unsigned. The sides the wallet's asset is not are bought in the chain's own pools inside the transaction, the ladder is built for the owner, and when the pair has no pool on LoomDesk's hook one is opened on the way. Use whenever the caller pays in ETH or USDG; it replaces plan_swap, plan_open_pool and plan_ladder together. Not for assets the wallet already holds (plan_ladder) or for an order at one price (plan_limit_order). Returns: transactions[] (to, data, value in wei, gas), check (simulated, ok, failedStep, reason, ethNeeded, ethHeld), sendWithin, ifItReverts, slippagePct, pool (which, or that it opens), priceNow, band, rungs, bought[] (each side, expected, atLeast, via), paid, fees, recentMovePct. 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 when the amount does not cover the opening fee, the token has no pool against ETH or USDG to buy a side in, or the quote has no exit.

Input Schema

TableJSON Schema

Name	Required	Description
`pool`	No	A v4 pool id from ladder_pools to build in, on the hook or not; the quote is then that pool's. Left out: the token's pool against the quote, opened if none.
`owner`	Yes	The wallet that signs, sends, and owns the ladder.
`payIn`	Yes	What the wallet pays with.
`quote`	Yes	What the token trades against: ETH, USDG, or the quote token's address.
`rungs`	No	How many rungs across the band, 1 to 40; default 20.
`shape`	No	Where the band puts the most: spot, curve, bidask, hybrid, or custom with weights. Default bidask.
`token`	Yes	The token's address.
`amount`	Yes	How much is paid, as a decimal string (for example "0.05").
`copyOf`	No	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.
`feePct`	No	The swap fee for a pool that has to be opened: 0.1, 0.5, or 1 to 5 (percent). Ignored when the pair already has a pool on the hook.
`lowPct`	No	The band's bottom, percent from the price (negative). Needed unless fullRange.
`highPct`	No	The band's top, percent from the price. Needed unless fullRange.
`weights`	No	shape custom only: a relative height per rung, low price to high, any scale; stretched over the rungs built.
`referrer`	No	The wallet that referred the owner: paid 0.1% of what goes in, out of the opening fee.
`fullRange`	No	One position across every price instead of a band; lowPct and highPct are ignored.
`slippagePct`	No	Room for the price to move, in percent. Left out: 1.5% on a calm token, more on one that has been moving, at most 10%.

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedOct 7, 2026

addedInput schema / properties / amount / description

Added value: +"How much is paid, as a decimal string (for example \"0.05\")."

addedInput schema / properties / copyOf / description

Added 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."

addedInput schema / properties / feePct / description

Added value: +"The swap fee for a pool that has to be opened: 0.1, 0.5, or 1 to 5 (percent). Ignored when the pair already has a pool on the hook."

addedInput schema / properties / fullRange / description

Added value: +"One position across every price instead of a band; lowPct and highPct are ignored."

addedInput schema / properties / highPct / description

Added value: +"The band's top, percent from the price. Needed unless fullRange."

changedInput schema / properties / lowPct / description

Previous value: -"needed unless fullRange"New value: +"The band's bottom, percent from the price (negative). Needed unless fullRange."

addedInput schema / properties / owner / description

Added value: +"The wallet that signs, sends, and owns the ladder."

addedInput schema / properties / payIn / description
```
Added value: +"What the wallet pays with."
```

changedInput schema / properties / pool / description

Previous value: -"A v4 pool of the token to build in, by id from ladder_pools: any pool, on the hook or not; the quote is then that pool's"New value: +"A v4 pool id from ladder_pools to build in, on the hook or not; the quote is then that pool's. Left out: the token's pool against the quote, opened if none."

changedInput schema / properties / quote / description

Previous value: -"ETH, USDG, or the quote token's address"New value: +"What the token trades against: ETH, USDG, or the quote token's address."

addedInput schema / properties / referrer / description

Added value: +"The wallet that referred the owner: paid 0.1% of what goes in, out of the opening fee."

addedInput schema / properties / rungs / description

Added value: +"How many rungs across the band, 1 to 40; default 20."

addedInput schema / properties / shape / description

Added value: +"Where the band puts the most: spot, curve, bidask, hybrid, or custom with weights. Default bidask."

changedInput schema / properties / slippagePct / description

Previous value: -"Left out: 1.5% on a calm token, 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, in percent. Left out: 1.5% on a calm token, more on one that has been moving, at most 10%."

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."

Changed2 schema fields changedOct 6, 2026

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
```

Changed2 schema fields changedOct 6, 2026

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"
+}

Changed1 schema field changedOct 5, 2026

addedInput schema / properties / slippagePct / description

Added value: +"Left out: 1.5% on a calm token, more on one whose price has been moving (set from its last fifteen minutes, at most 10%)"

Changed2 schema fields changedSep 30, 2026
- changedInput schema / properties / feePct / minimum
```
Previous value: -1New value: +0.1
```
- changedInput schema / properties / feePct / type
```
Previous value: -"integer"New value: +"number"
```

Changed1 schema field changedSep 24, 2026

changedInput schema / properties / shape / enum

Previous value: -[
-  "spot",
-  "curve",
-  "bidask"
-]New value: +[
+  "spot",
+  "curve",
+  "bidask",
+  "hybrid"
+]

Changed1 schema field changedSep 23, 2026
- changedInput schema / properties / feePct / maximum
```
Previous value: -5New value: +10
```

Changed1 schema field changedSep 22, 2026

addedInput schema / properties / pool

Added value: +{
+  "description": "A v4 pool of the token to build in, by id from ladder_pools: any pool, on the hook or not; the quote is then that pool's",
+  "type": "string"
+}

Changed2 schema fields changedSep 22, 2026

addedInput schema / properties / lowPct / description
```
Added value: +"needed unless fullRange"
```

changedInput schema / required

Previous value: -[
-  "token",
-  "quote",
-  "payIn",
-  "amount",
-  "owner",
-  "lowPct",
-  "highPct"
-]New value: +[
+  "token",
+  "quote",
+  "payIn",
+  "amount",
+  "owner"
+]

AddedSep 22, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations cover read-only/idempotent/destructive, and the description adds context they cannot: the plan is simulated from the owner and unsigned, must be sent within check.sendWithin, should be re-planned rather than resent after a revert, and consumes agent_quota units. It also enumerates the three refusal conditions (opening fee not covered, no pool to buy a side, quote has no exit), which is exactly the kind of failure disclosure that aids invocation.

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?

Purpose and the sibling routing are front-loaded, and every clause carries information. The long, comma-spliced return-field enumeration is dense and slightly hard to scan, but with no output schema it is earning its place rather than padding.

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 a 16-parameter tool with no output schema, the description covers the missing pieces: the returned transaction/check/pool/price structure, the time window, the simulation semantics, quota cost, and the error cases. Nothing an agent needs in order to plan correctly appears to be absent.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already carries full parameter meaning and the baseline is 3. The description only echoes a few fields (pool, fee, slippage) via the return summary rather than adding syntax or constraints the schema lacks, so it neither helps nor hurts.

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?

The description gives a precise verb and resource: it plans one (or two) unsigned transactions that buy the missing side, build a ladder in a v4 pool, and open a pool on the hook if none exists. It explicitly names the siblings it supersedes (plan_swap, plan_open_pool, plan_ladder) and the ones it is not for, so an agent can route without opening schemas.

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

Usage Guidelines5/5

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

It states the selecting condition directly ('Use whenever the caller pays in ETH or USDG') and gives both exclusions with the correct alternative for each: plan_ladder for assets already held, plan_limit_order for a single-price order. It also notes the USDG two-transaction case (approval first), which is a usage-relevant nuance.

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

All LoomDesk tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?