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

# Shape a tool's result

> Save your own form for a tool's result, and get it on every run.

A shape is your own form for one tool's result: only some fields, renamed, filtered, sorted, grouped, counted or averaged. Say what you want in words. Pomerado writes a small function for it and checks it against every form the tool's result can take before saving it. Then pass the shape's `id` as `shape` when you run the tool.

Shapes are free, a shaped run counts as one run, and only you can see and use your shapes.

## Make a shape

| MCP | REST |
| - | - |
| `create_shape` | `POST /v1/tools/{id}/shapes` |

```json theme={null}
{
  "name": "create_shape",
  "arguments": {
    "tool_id": "tool_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "request": "Only the three cheapest flights, with the airline and price"
  }
}
```

It answers in a few seconds and starts no job. `outcome` is one of:

* `saved`: the shape, with its `id`, and a `preview` of its result for a made-up result of the tool.
* `needs_tool_change`: the tool doesn't return the data you asked for (`missing`). Ask for it with `change_website_tool` (`POST /v1/tools/{id}/changes`), then make the shape.
* `not_possible`: no shape can do it, such as one needing the time or other pages of results.
* `not_written`: Pomerado's code didn't pass its checks; `findings` says why. Try saying it another way.

To change a shape, pass `shape_id` to `create_shape`, or send `PATCH /v1/shapes/{id}` with `request`, `name` or both. Each change is a new version; `GET /v1/shapes/{id}` lists the last 100, and `POST /v1/shapes/{id}/restore` makes an earlier one current again.

## Run with a shape

Add `shape` beside `tool_id` and `input` on `run_read_only_website_tool`, `run_website_tool` or the REST run routes. The run's `result` comes in the shape's form, and paging fields such as `next_cursor` are copied onto it, so you page as before. The job's `shape` says what happened:

* `status: "applied"`: the result is in the shape's form.
* `status: "skipped"`: the result is the tool's own, and `reason` says why. A shape that breaks never fails the run.
* `new_fields`: fields the tool returns now that your shape leaves out. `message` says how to add them.

A shape sees only the result, never the run's input. A website's refusal always comes as the tool gives it.

## New fields

Tools gain fields over time. A shape leaves them out unless you asked it to keep everything, so your form stays the same. A shape that keeps everything still replaces a new field with its own field of the same name, so that new field counts as left out too. The tool's `shapes`, each shape and each shaped run list the new fields, and the Dashboard's Shapes dialog offers to add them.

## Change requests that only reshape

A requested change that only asks for the same data in another form is answered with a shape instead of a tool change: the change's job succeeds at once, uncharged, with `build.change.shape` naming the shape saved for you. A change that also needs new data goes on as a tool change, and its reshaping part is saved as a shape beside it.


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