> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pomerado.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# create_shape

> Save a shape: your own form for a tool's result, such as only some fields, renamed, filtered, sorted, counted or averaged.

## Arguments

| Argument | Required | Type | Description |
| - | - | - | - |
| `tool_id` | Yes | string | The tool whose result you want in another form |
| `request` | Yes | string, up to 2,000 characters | The result you want, in your own words: which fields, renamed how, filtered, sorted, counted or averaged, such as "only the name and price in dollars, cheapest first" |
| `shape_id` | No | string | One of your shapes of this tool, to change it instead of making a new one |
| `intent` | No | string, up to 500 characters | Describe the intended use case in one sentence: what this call should do and why, such as "Check a store's opening hours to answer when it opens today". Describe the task, not the person: leave out names, contact details, account numbers and anything used to sign in. Pomerado uses it to improve its tools. Optional, but recommended: please include it on every call. |

## Output

What making the shape came to: `saved`, with the shape, its `id` to pass as `shape` on runs, and a `preview` of its result; `needs_tool_change`, naming the data the tool doesn't return; `not_possible`; or `not_written`, with the checks' findings. `message` says it in words.

```json Arguments theme={null}
{
  "tool_id": "tool_11111111111111111111111111111111",
  "request": "Only the three cheapest flights, with the airline and price"
}
```

```json Result theme={null}
{
  "outcome": "saved",
  "shape": {
    "id": "shp_ffffffffffffffffffffffffffffffff",
    "tool_id": "tool_11111111111111111111111111111111",
    "name": "Three cheapest flights",
    "request": "Only the three cheapest flights, with the airline and price",
    "version": 1,
    "code": "r => ({ flights: sortBy(r.flights, \"price\").slice(0, 3).map(f => ({ airline: f.airline, price: f.price })) })",
    "output_schema": {
      "type": "object",
      "properties": {
        "flights": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "airline": { "type": "string" },
              "price": { "type": "number" }
            },
            "required": ["airline", "price"]
          }
        }
      },
      "required": ["flights"]
    },
    "passes_new_fields": false,
    "new_fields": [],
    "created_at": "2026-11-10T17:00:00.000Z",
    "updated_at": "2026-11-10T17:00:00.000Z"
  },
  "preview": { "flights": [{ "airline": "Example Air", "price": 129 }] },
  "message": "Saved as your shape \"Three cheapest flights\" (shp_ffffffffffffffffffffffffffffffff). Pass shape: \"shp_ffffffffffffffffffffffffffffffff\" when you run the tool to get its result in this form. Shapes are free, and only you can see and use them."
}
```

> [accordion] Details
>
> Pomerado writes and checks it from your words in a few seconds.
>
> * Then pass its id as shape when you run the tool with run\_read\_only\_website\_tool or run\_website\_tool. The run returns the result in that form, keeping paging fields such as next\_cursor.
> * A shape only reshapes what the tool returns. For data the tool doesn't return, it answers needs\_tool\_change: ask for it with change\_website\_tool.
> * Pass shape\_id to change one of your shapes. Shapes are free, and only you can see and use them.
>
> **Effect:** May change a website or your account.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.