Skip to main content
Glama

LoomDesk

by trade.loomdesk
OverviewDiscussionsAdmin

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

NameRequiredDescriptionDefault
hookNoWhich hook the pool goes on and with what, when it has to be opened. Left out: the plain ranges pool at feePct; the answer then lists the presets under options. A full-range pool, a launch fee or the volatility fee are opened by the hook's own call in a transaction before the build (plan_build returns both, in order).
poolNoA 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.
sideNoquote: the buy side only. Every rung sits under the price and holds the quote, nothing is swapped into the token, the band's top is the price (highPct capped at 0). Default both: the token side is bought on the way in.
ownerYesThe wallet that signs, sends, and owns the ladder.
payInYesWhat the wallet pays with.
quoteYesWhat the token trades against: ETH, USDG, or the quote token's address.
rungsNoHow many rungs across the band, 1 to 40; default 20.
shapeNoWhere the band puts the most: spot, curve, bidask, hybrid, or custom with weights. Default bidask.
tokenYesThe token's address.
amountYesHow much is paid, as a decimal string (for example "0.05").
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.
feePctNoThe 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.
lowPctNoThe band's bottom, percent from the price (negative). Needed unless fullRange.
highPctNoThe band's top, percent from the price. Needed unless fullRange.
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.
fullRangeNoOne position across every price instead of a band; lowPct and highPct are ignored.
slippagePctNoRoom 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.

  1. Changed1 schema field changed
    • addedInput schema / properties / side
      Added value: +{
+  "description": "quote: the buy side only. Every rung sits under the price and holds the quote, nothing is swapped into the token, the band's top is the price (highPct capped at 0). Default both: the token side is bought on the way in.",
+  "enum": [
+    "both",
+    "quote"
+  ],
+  "type": "string"
+}
  2. Changed1 schema field changed
    • removedInput schema / properties / hook / properties / blocks / properties / sellLockMinutes
      Removed value: -{
-  "description": "Sell lock: no sells for the first so many minutes. Liquidity can always be removed.",
-  "maximum": 1440,
-  "minimum": 1,
-  "type": "integer"
-}
  3. Changed1 schema field changed
    • addedInput schema / properties / hook / properties / blocks
      Added value: +{
+  "description": "ranges only: the creator's blocks, each enforced by the hook in every swap and fixed at opening. A trader always pays the pool's fee and no more: the royalty and the burn come out of it.",
+  "properties": {
+    "antiSnipeMaxQuote": {
+      "description": "Anti-snipe: the most a single buy may spend of the quote (ETH or USDG, in whole units) during the first antiSnipeMinutes.",
+      "exclusiveMinimum": 0,
+      "type": "number"
+    },
+    "antiSnipeMinutes": {
+      "maximum": 1440,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "burnPct": {
+      "description": "Auto burn: this percent of the base fee is burned in the token on every sell. At most 20.",
+      "exclusiveMinimum": 0,
+      "maximum": 20,
+      "type": "number"
+    },
+    "managedFee": {
+      "description": "Managed fee: the creator may later move the base fee between these tiers (same spacing as the fee: 1 to 5 together), an hour apart, with the hook's setFee.",
+      "properties": {
+        "ceilPct": {
+          "type": "number"
+        },
+        "floorPct": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "floorPct",
+        "ceilPct"
+      ],
+      "type": "object"
+    },
+    "offHoursFeePct": {
+      "description": "Market hours: outside NYSE hours (weekdays 13:30 to 20:00 UTC) the base fee is this tier instead.",
+      "type": "number"
+    },
+    "royaltyPct": {
+      "description": "Royalty: this percent of the base fee goes to the pool's creator in the quote, every swap. At most 30.",
+      "exclusiveMinimum": 0,
+      "maximum": 30,
+      "type": "number"
+    },
+    "sellLockMinutes": {
+      "description": "Sell lock: no sells for the first so many minutes. Liquidity can always be removed.",
+      "maximum": 1440,
+      "minimum": 1,
+      "type": "integer"
+    }
+  },
+  "type": "object"
+}
  4. Changed1 schema field changed
    • addedInput schema / properties / hook
      Added value: +{
+  "description": "Which hook the pool goes on and with what, when it has to be opened. Left out: the plain ranges pool at feePct; the answer then lists the presets under options. A full-range pool, a launch fee or the volatility fee are opened by the hook's own call in a transaction before the build (plan_build returns both, in order).",
+  "properties": {
+    "kind": {
+      "description": "ranges: LoomOpenHookV2, any band, the fee in the asset paid in (default). full: LoomFullHook, one full-range position only, every fee in the quote (ETH or USDG), and a swap that closes a gap of 3%+ to the token's Uniswap v3 market pays for the gap instead.",
+      "enum": [
+        "ranges",
+        "full"
+      ],
+      "type": "string"
+    },
+    "launchFeePct": {
+      "description": "The fee the pool opens at, percent, above the swap fee and at most 50; it falls in a straight line to the swap fee over launchMinutes. Needs launchMinutes.",
+      "maximum": 50,
+      "minimum": 0,
+      "type": "number"
+    },
+    "launchMinutes": {
+      "description": "How long the launch fee takes to fall to the swap fee: 1 to 1440 minutes.",
+      "maximum": 1440,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "preset": {
+      "description": "A named set: steady (1%, plain), volatile (3%, volatility fee on), launch (5%, opens at 50% and falls to 5% over an hour, volatility fee on), full (full range, 1% in the quote, opens at 10% for ten minutes). A field given beside it wins.",
+      "enum": [
+        "steady",
+        "volatile",
+        "launch",
+        "full"
+      ],
+      "type": "string"
+    },
+    "volatility": {
+      "description": "ranges only: a fee that rises for a while after the price moves (a move under 3% adds nothing; the add fades within minutes).",
+      "type": "boolean"
+    }
+  },
+  "type": "object"
+}
  5. Changed16 schema fields changed
    • 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."
  6. 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
  7. 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"
+}
  8. Changed1 schema field changed
    • 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%)"
  9. Changed2 schema fields changed
    • changedInput schema / properties / feePct / minimum
      Previous value: -1New value: +0.1
    • changedInput schema / properties / feePct / type
      Previous value: -"integer"New value: +"number"
  10. Changed1 schema field changed
    • changedInput schema / properties / shape / enum
      Previous value: -[
-  "spot",
-  "curve",
-  "bidask"
-]New value: +[
+  "spot",
+  "curve",
+  "bidask",
+  "hybrid"
+]
  11. Changed1 schema field changed
    • changedInput schema / properties / feePct / maximum
      Previous value: -5New value: +10
  12. Changed1 schema field changed
    • 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"
+}
  13. Changed2 schema fields changed
    • 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"
+]
  14. Added

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial context beyond them: it returns unsigned transactions, is simulated from the owner at the current block, must be sent within check.sendWithin, should be replanned if reverted, and costs quota units (agent_quota). It also lists specific error refusal cases.

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

Conciseness5/5

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

The description is front-loaded with purpose, then usage, returns, behavior, and errors. Despite its length, every sentence earns its place by covering critical aspects of an 18-parameter, mutation-like planning tool.

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?

There is no output schema, but the description comprehensively lists return fields (transactions[], check, sendWithin, ifItReverts, slippagePct, pool, priceNow, band, rungs, bought[], paid, fees, recentMovePct) and explains simulation, send-within, and error behavior. Nothing an agent needs in order 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.

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 documents all 18 parameters in detail. The description adds some high-level semantics (e.g., 'two when paying in USDG: its approval first' and how sides are bought) but does not provide per-parameter syntax or constraints beyond what the schema already gives. Baseline 3 is appropriate.

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 states a specific verb+resource: 'Plans one transaction ... from ETH or USDG to a ladder in a v4 pool of the token against the quote.' It distinguishes itself from siblings by explicitly saying it replaces plan_swap, plan_open_pool, and plan_ladder together.

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 gives explicit when-to-use: 'Use whenever the caller pays in ETH or USDG' and when-not: 'Not for assets the wallet already holds (plan_ladder) or for an order at one price (plan_limit_order).' This leaves no ambiguity about alternatives.

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

All LoomDesk toolsInspect
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