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

# Build a tool

> Build a new tool when no existing tool covers your task.

Describe a task and a site, and Pomerado builds a tool for it on the real site in about 10 minutes, then reuses it. Building needs you to be signed in.

## From an MCP client

Ask your agent, for example: "Build a tool that searches Instacart for a product near a ZIP code." It calls `build_website_tool`:

```json theme={null}
{
  "task": "Search Instacart for a product and return the matches at each store with name, size and price",
  "site_url": "https://www.instacart.com",
  "effect": "read",
  "example_input": "{\"query\": \"oat milk\", \"zip\": \"94103\"}"
}
```

The agent tells you it's building, then follows the job with `get_job`.

## From the REST API

```bash theme={null}
curl https://api.pomerado.ai/v1/builds \
  -H "Authorization: Bearer $POMERADO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: build-instacart-search-1" \
  -d '{"task": "Search Instacart for a product and return the matches at each store with name, size and price",
       "site_url": "https://www.instacart.com",
       "effect": "read",
       "example_input": {"query": "oat milk", "zip": "94103"}}'
```

The answer is the build's job. Read it with `GET /v1/jobs/{id}`; `build.stage` shows progress.

## Use the new tool

When the job succeeds, its `tool_id` names the new tool, and `build.example_result` holds the result of the example it ran. [Run it](/quickstart/run-a-tool) like any other tool.

<Accordion title="Details">
  * Set `effect` to `read` when the tool only looks things up, `write` when it changes the site, or `ask` to have the build ask you first.
  * A write build makes the change once, with your example input. Don't repeat it.
  * If the build needs your website login, the job asks for it on a protected page. Never paste a password into chat.
  * If a tool already covers the task, the job names it as `tool_id` instead.
  * Ticket, bank and government sites are refused with `site_not_supported`.
  * More in the [build overview](/guides/build/overview).
</Accordion>

## Next

See it in use: a [personal assistant](/examples/personal-assistant), a [backend application](/examples/backend-application) or a [product agent](/examples/product-agent).


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