design_tree

Turns a short wish (for example 'a silver birch with lanterns') into a premium tree design. An AI paints the tree after the call (about 30 s); the first painting becomes the tree. Returns design_id and the tree genome. Max 3 design attempts per caller per day (including rejected or interrupted generation). Show the result to the user before you order.

Argument	Type	Description
wish*	string	What the tree should look like, 1-200 characters. No brands, logos or text.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "wish"
  ],
  "properties": {
    "wish": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "What the tree should look like, 1-200 characters. No brands, logos or text."
    }
  },
  "additionalProperties": false
}

explain_shared_forest

Read-only. Returns the full agent guide as Markdown: growth rules, API, tools and limits.

read-only

Argument	Type	Description
section	string	Return only the section whose heading contains this text, for example 'Limits' or 'MCP tools'. Omit for the whole guide.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "section": {
      "type": "string",
      "description": "Return only the section whose heading contains this text, for example 'Limits' or 'MCP tools'. Omit for the whole guide."
    }
  },
  "additionalProperties": false
}

find_spots

Read-only. Suggests free positions for N sponsored trees, optionally near a point. Pass the spots to start_sponsorship, or omit spots there and the server picks them.

read-only

Argument	Type	Description
near_x	number	Optional x coordinate (0-8192) to search near. Needs near_y.
near_y	number	Optional y coordinate (0-8192) to search near. Needs near_x.
quantity*	integer	Number of trees, 1-100. Larger orders get a lower unit price.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "quantity"
  ],
  "properties": {
    "near_x": {
      "type": "number",
      "maximum": 8192,
      "minimum": 0,
      "description": "Optional x coordinate (0-8192) to search near. Needs near_y."
    },
    "near_y": {
      "type": "number",
      "maximum": 8192,
      "minimum": 0,
      "description": "Optional y coordinate (0-8192) to search near. Needs near_x."
    },
    "quantity": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Number of trees, 1-100. Larger orders get a lower unit price."
    }
  },
  "additionalProperties": false
}

get_design

Read-only. Returns one design by design_id: genome, genomeHash and expiresAt.

read-only

Argument	Type	Description
design_id*	string	Design id from design_tree, for example dsn_abc123.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "design_id"
  ],
  "properties": {
    "design_id": {
      "type": "string",
      "pattern": "^dsn_[A-Za-z0-9_-]{4,64}$",
      "description": "Design id from design_tree, for example dsn_abc123."
    }
  },
  "additionalProperties": false
}

get_forest

Read-only. Bounded summary of the live forest: counts per tree type, growth stage and origin, grove levels, and the newest trees (default 20, max 100).

read-only

Argument	Type	Description
bbox	array	Bounding box [minX, minY, maxX, maxY] in world coordinates. Only trees inside it are returned.
limit	integer	Number of newest trees to return.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "bbox": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "maxItems": 4,
      "minItems": 4,
      "description": "Bounding box [minX, minY, maxX, maxY] in world coordinates. Only trees inside it are returned."
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "description": "Number of newest trees to return."
    }
  },
  "additionalProperties": false
}

get_forest_stats

Read-only. Counts of trees, groves, total and unique visitors, and traffic by class (humans, agents, bots, trees planted today).

read-only

Argument	Type	Description
fields	array	Return only these counters. Omit for all counters.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "fields": {
      "type": "array",
      "items": {
        "enum": [
          "trees",
          "groves",
          "visitors",
          "uniqueVisitors",
          "humans",
          "agents",
          "bots",
          "plantedToday"
        ],
        "type": "string"
      },
      "description": "Return only these counters. Omit for all counters.",
      "uniqueItems": true
    }
  },
  "additionalProperties": false
}

get_order

Read-only. Needs OAuth scope account:read or sponsor:write. Status of one of the user's orders (open, paid, fulfilled, expired, refunded, disputed, cancelled, refund_pending) and its tree ids once fulfilled. Poll every 10 seconds or more after the user pays.

read-only

Argument	Type	Description
order_id*	string	Order id from start_sponsorship, for example ord_abc123.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "order_id"
  ],
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^ord_[A-Za-z0-9_-]{4,64}$",
      "description": "Order id from start_sponsorship, for example ord_abc123."
    }
  },
  "additionalProperties": false
}

get_price_quote

Read-only. Final price for sponsoring N trees for 12 months: unit price, total in euro cents and discount. Call it before you tell the user a price.

read-only

Argument	Type	Description
quantity*	integer	Number of trees, 1-100. Larger orders get a lower unit price.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "quantity"
  ],
  "properties": {
    "quantity": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Number of trees, 1-100. Larger orders get a lower unit price."
    }
  },
  "additionalProperties": false
}

list_trees

Read-only. One page of trees with cursor pagination, the same data as GET /api/forest?limit=. Pass nextCursor as cursor until it is null.

read-only

Argument	Type	Description
bbox	array	Bounding box [minX, minY, maxX, maxY] in world coordinates. Only trees inside it are returned.
limit*	integer	Trees per page, for example 100.
cursor	string	Opaque cursor from nextCursor of the previous page.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "limit"
  ],
  "properties": {
    "bbox": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "maxItems": 4,
      "minItems": 4,
      "description": "Bounding box [minX, minY, maxX, maxY] in world coordinates. Only trees inside it are returned."
    },
    "limit": {
      "type": "integer",
      "maximum": 500,
      "minimum": 1,
      "description": "Trees per page, for example 100."
    },
    "cursor": {
      "type": "string",
      "description": "Opaque cursor from nextCursor of the previous page."
    }
  },
  "additionalProperties": false
}

my_orders

Read-only. Needs OAuth scope account:read. The signed-in user's sponsorship orders, newest first, with status, total and tree ids.

read-only

Argument	Type	Description
limit	integer	Number of orders, 1-50.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "description": "Number of orders, 1-50."
    }
  },
  "additionalProperties": false
}

my_trees

Read-only. Needs OAuth scope account:read. The trees of the signed-in user's fulfilled orders, with a link to each tree in the forest.

read-only

Argument	Type	Description
limit	integer	Number of trees, 1-500.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "description": "Number of trees, 1-500."
    }
  },
  "additionalProperties": false
}

plant_tree

Plant one tree in the Shared Forest for the caller. One tree per visitor per day; repeats only add growth energy. The visit counts as agent traffic. Ask the user before you call it.

Argument	Type	Description
idempotency_key	string	Optional retry key, for example a UUID. A retry with the same key within 24 hours returns the first visitId and plants nothing new.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "idempotency_key": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Optional retry key, for example a UUID. A retry with the same key within 24 hours returns the first visitId and plants nothing new."
    }
  },
  "additionalProperties": false
}

start_sponsorship

Needs OAuth scope sponsor:write (a Shared Forest account). Creates an unpaid order for the signed-in user and holds the spots. It charges nothing. The total must fit the spending limit the user set when connecting. The order expires after 30 minutes unless the user confirms. Returns confirm_url: give it to your user. The user logs in, accepts the terms and pays on that page. Ask the user before you call it and confirm name and total.

Argument	Type	Description
link	string	Optional https link. It goes live after manual review.
email	string	Optional email for the confirmation and the invoice. Default: the email of the signed-in account.
spots	array	Optional positions from find_spots, one per tree. Omit and the server picks free spots.
quantity*	integer	Number of trees, 1-100. Larger orders get a lower unit price.
link_text	string	Optional public label for the link. Requires link; approved with it.
design_ids*	array	One design_id for all trees, or one per tree.
display_name*	string	Name shown on the trees, 1-32 characters, labelled Sponsored.

Shared Forest

Try it

design_tree

Shared Forest

Try it

design_tree

Tools (13)