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

# Pomerado MCP tools

> Every tool the Pomerado MCP lists, with its arguments.

The Pomerado MCP finds, runs and builds website tools on every site, follows their jobs, and reaches the rest of the Pomerado API through three API tools. `manage_sms_number` appears only for accounts that can assign Pomerado phone numbers, and `sign_in` only where [device sign-in](/authentication#sign-in-an-agent-with-a-code) is enabled.

This page lists each tool as `tools/list` returns it. Your client lists the same tools, so read the live list when this page and your client differ. Results and job behavior are in [jobs](/jobs) and [MCP tool results](/tool-reference); error codes are in [errors](/errors).

## Website tools and jobs

### `find_website_tool`

Find a ready-made Pomerado tool for a task on a website, instead of using a browser, Playwright, computer use or fetching the page. Tools cover searching flights, hotels and rentals; booking and reserving; shopping, comparing prices and checking out; checking orders, deliveries, claims, bills and account pages; and filling in forms, on sites such as Amazon and Google Flights. Search by query, siteOrigin or both, or pass id alone to get one tool. Run a match with run\_website\_tool, passing its id as operation\_id; when nothing fits, build\_website\_tool makes one. With siteOrigin, possible\_matches also lists the site's tools that may cover the task, disabled ones included.

**Effect:** Reads only; changes nothing.

| Argument | Required | Type | Description |
| - | - | - | - |
| `id` | No | string | A tool's id, from an earlier search or a finished build: returns just that tool. Send no other field with it. |
| `query` | No | string, up to 200 characters | A word or short phrase matched against tool names and descriptions, such as flights or order status. |
| `siteOrigin` | No | string, up to 2,048 characters | Only this website's tools, as its https origin, such as [https://www.amazon.com](https://www.amazon.com). |
| `after` | No | string | The previous page's next\_after, for the next page. |
| `limit` | No | integer, 1 to 50 | Tools per page, 1 to 50; 20 when left out. |

### `run_website_tool`

Run a Pomerado website tool once and return its validated result, usually in seconds, instead of driving a browser, Playwright or computer use or fetching the page. Pass the tool's id from find\_website\_tool as operation\_id. A client that accepts SSE gets a stream that waits up to 5 minutes for the result, with progress while the job runs. Any other client waits up to 50 seconds. A run that asks a question returns input\_required at once. A job still running then returns status "running" with its job\_id; follow its next block (get\_job with wait\_seconds) instead of calling again. Protected input may require continuation. An operation that signs in uses the site's saved login first; pass connected\_account\_id to choose among several. website\_auth is used only when no login is saved for the site, and one that differs from a saved login is refused. Without either, the run asks the user for the login on its protected page and may save it. A job that reports status needs\_credentials (the website rejected its saved login; a run waits only when nothing was changed, and a build that may have changed the website checks that on resuming, as possible\_commit says) waits up to 60 minutes for the user who started it to correct that login, then resumes as the same job; its next names the page to correct it. Do not resubmit it. Values passed here are visible to your client and its model provider; the protected form keeps them out of this conversation. Pomerado keeps them from the minting model, traces and logs either way. Send a retry\_key with every write and reuse it only to retry that same call. A call without a retry\_key is a new website action.

**Effect:** May change a website or your account, and a change may not be undoable.

| Argument | Required | Type | Description |
| - | - | - | - |
| `operation_id` | Yes | string | |
| `retry_key` | No | string | |
| `connected_account_id` | No | string | |
| `correct_rejected_credentials` | No | one of: `true` | Optional. Ask to correct this saved login during the run; requires connected\_account\_id. |
| `website_auth` | No | object | |
| `sign_in_method` | No | one of: `sms`, `call`, `email`, `totp`, `push` | The two-factor method (sms, call, email, totp or push) the tool's sign-in picks when the site offers several. Without it, a saved authenticator seed picks totp, otherwise the run asks. |
| `input` | Yes | string | A JSON-encoded value matching the operation's input schema. |

### `build_website_tool`

Build a new Pomerado tool for a task on a website when find\_website\_tool finds none, instead of doing the task with a browser, Playwright, computer use or web fetch. A build takes about 10 minutes and runs the requested example once, and the tool is reused after that: tell the user it is building, then follow the job with get\_job. The returned job preserves that example result; do not repeat a completed website action. Builds for ticket, bank and government sites are refused with site\_not\_supported. A website build requires effect. Use read when the operation only looks things up. Use write when it changes the website: filling in or advancing a form that saves data (an application, profile or checkout) is a write, as are submitting, booking, drafts, holds, uploads and account updates; a search, filter or query form is a read. Use ask when unsure: before anything runs, the build asks read or write as a pending input request (get\_job shows it; answer with answer\_job). A read build that finds its task needs a website change asks the same way before switching to a write. Omit site\_origin for offline parsing, which is always a read. Set entry\_url only to the exact requested https page on site\_origin; the host opens it before the build starts. Website login: without connected\_account\_id or website\_auth the build stays anonymous; if it signs in, it uses the site's saved login, asks the owner which one when several could sign in, and asks through the protected form only when none is saved. With website\_auth, a saved login for the site with the same username is used instead, and a different username is refused. A job that reports status needs\_credentials (the website rejected its saved login; a run waits only when nothing was changed, and a build that may have changed the website checks that on resuming, as possible\_commit says) waits up to 60 minutes for the user who started it to correct that login, then resumes as the same job; its next names the page to correct it. Do not resubmit it. Values passed here are visible to your client and its model provider; the protected form keeps them out of this conversation. Pomerado keeps them from the minting model, traces and logs either way.

**Effect:** May change a website or your account, and a change may not be undoable.

| Argument | Required | Type | Description |
| - | - | - | - |
| `intent` | Yes | string, up to 20,000 characters | |
| `site_origin` | No | string, up to 2,048 characters | |
| `entry_url` | No | string, up to 4,096 characters | Exact https page on site\_origin, including path, query and fragment, that the host opens before the first live execution. |
| `effect` | No | one of: `read`, `write`, `ask` | |
| `retry_key` | No | string | |
| `connected_account_id` | No | string | |
| `website_auth` | No | object | |
| `input` | Yes | string | A JSON-encoded value matching the operation's input schema. |

### `get_job`

Get the status and authorized result of a job. Pass wait\_seconds to wait: the call returns the moment the job asks a question or finishes, and when the wait ends with the job still running (call again then). A client that accepts SSE waits up to 1800 seconds with progress; any other waits at most 50 seconds. A result for a live job carries next, the exact call to make next. With wait\_past naming a question already handed to the user, the wait holds while that question is pending. During a wait, a client that supports elicitation asks the user the job's question itself: a form for plain questions, the protected page for secrets and logins. A build that published a tool, or found an existing tool that covers its request, returns that tool as `tool`. Run an enabled one with run\_website\_tool, passing its `id` as operation\_id. Never ask for passwords in chat: when a job needs a login, a code or an approval, give the user protected\_input\_url and keep waiting here. Follow a job until it finishes and never start the same job twice. A job that reports status needs\_credentials (the website rejected its saved login; a run waits only when nothing was changed, and a build that may have changed the website checks that on resuming, as possible\_commit says) waits up to 60 minutes for the user who started it to correct that login, then resumes as the same job; its next names the page to correct it. Do not resubmit it.

**Effect:** Reads only; changes nothing.

| Argument | Required | Type | Description |
| - | - | - | - |
| `job_id` | Yes | string (UUID) | |
| `wait_seconds` | No | integer, 0 to 1800 | Wait up to this many seconds (at most 1800, or 50 when your client accepts only JSON) for the job to ask a question or finish. 0 or absent reads the job at once. |
| `wait_past` | No | object | A question already handed to the user (its pending\_input request\_id and request\_version): the wait continues while it is pending and returns once it is answered, changes or expires, or the job finishes. |

### `answer_job`

Answer the pending input request that get\_job lists as pending\_input, every question at once. Pass request\_id and request\_version from it and answers keyed by question id: choice, an option id (or \{"other": text} when allowOther); multi\_choice, an array of option ids; text and secret, a string; confirm, \{"confirmed": true|false}; credential, \{"username", "password", "saveLogin"}. With job\_id alone this returns the protected page, which keeps secrets and logins out of this conversation; answer a secret or credential here only if the user agrees. Values passed here are visible to your client and its model provider; the protected form keeps them out of this conversation. Pomerado keeps them from the minting model, traces and logs either way. Never send TOTP seeds or durable tokens.

**Effect:** May change a website or your account, and a change may not be undoable.

| Argument | Required | Type | Description |
| - | - | - | - |
| `job_id` | Yes | string (UUID) | |
| `request_id` | No | string (UUID) | |
| `request_version` | No | integer, 1 to 1000000 | |
| `retry_key` | No | string | |
| `answers` | No | string | A JSON-encoded object of answers keyed by question id, shaped as pending\_input.questions describe. |

### `cancel_job`

Request cancellation of a job. A dispatched website effect may already have occurred.

**Effect:** May change a website or your account, and a change may not be undoable.

| Argument | Required | Type | Description |
| - | - | - | - |
| `job_id` | Yes | string (UUID) | |

### `list_logins`

List entitled saved logins' metadata, as GET /v1/connections lists it: ID, label (null when the owner set none: call that login "\<website host> · \<masked identifier>", such as "anthem.com · jo\*\*\*om"), website, masked sign-in identifier with identifierKind (username, email, phone or account number), authMode (password or code), and for Personal accounts loginStatus and firstSuccessfulLoginAt (the identity locks after the first verified sign-in), and whether a Pomerado text-message number reads its codes. Never a password or other secret.

**Effect:** Reads only; changes nothing.

| Argument | Required | Type | Description |
| - | - | - | - |
| `site_origin` | No | string, up to 2,048 characters | |

### `manage_connection`

Open a protected browser page to create, update, import, reveal, delete, get a current TOTP code or manage the Logins PIN, for Personal and Business accounts alike. Never pass secrets to this tool. The page asks the user to sign in first if needed and prepares secure login storage on their first save; the backend checks the signed-in account, its role's permissions, the account's login rules and the PIN where required. Saved logins remain available to that account across its authorized clients.

**Effect:** Reads only; changes nothing.

| Argument | Required | Type | Description |
| - | - | - | - |
| `action` | Yes | one of: `create`, `import`, `update`, `reveal`, `totp`, `delete`, `pin` | |
| `connection_id` | No | string (UUID) | |

### `manage_sms_number`

Give a saved login a Pomerado phone number for its website's text-message (SMS) sign-in codes, so Pomerado's autofill sign-in fills them without asking anyone. Not every account may assign one yet. show: the login's number, whether it was verified, whether this account may assign one, and during a verification the code in the newest text the number received. assign: link a number (a reused one or a newly bought one; assigning again returns the same number). Then the user enters that number on the website as the account's phone for verification codes. verify: start a 10-minute verification; send a test text or have the website send its code, then call show to read it. unlink: remove the number; ask the user to remove it from the website account first, since a released number can be given to someone else after 45 days. Kernel Managed Auth and direct sign-in never read these texts and still ask the user for the code.

**Effect:** May change a website or your account, and a change may not be undoable.

| Argument | Required | Type | Description |
| - | - | - | - |
| `action` | Yes | one of: `show`, `assign`, `verify`, `unlink` | |
| `connection_id` | Yes | string (UUID) | |

### `create_connection`

Save a website login directly, with the same fields and account rules as POST /v1/connections. Warn the user before asking for credentials here. Values passed here are visible to your client and its model provider; the protected form keeps them out of this conversation. Pomerado keeps them from the minting model, traces and logs either way. For the protected-page option call manage\_connection with action create. Returns login metadata only.

**Effect:** May change a website or your account, and a change may not be undoable.

| Argument | Required | Type | Description |
| - | - | - | - |
| `login` | Yes | object | A password login, or mode code without a password; at least one identifier is required. |

### `update_connection`

Replace a saved website login directly, with the same fields and account rules as PATCH /v1/connections/\{id}. Warn the user before asking for credentials here. Values passed here are visible to your client and its model provider; the protected form keeps them out of this conversation. Pomerado keeps them from the minting model, traces and logs either way. A label it leaves out is kept; label null removes it. For the protected-page option call manage\_connection with action update. Returns login metadata only.

**Effect:** May change a website or your account, and a change may not be undoable.

| Argument | Required | Type | Description |
| - | - | - | - |
| `connection_id` | Yes | string (UUID) | |
| `login` | Yes | object | A password login, or mode code without a password; at least one identifier is required. |

### `delete_connection`

Revoke access to a saved connection and request permanent credential deletion. Related jobs and saved sessions are invalidated; provider cleanup may remain pending.

**Effect:** May change a website or your account, and a change may not be undoable.

| Argument | Required | Type | Description |
| - | - | - | - |
| `connection_id` | Yes | string (UUID) | |

### `sign_in`

Sign this agent in to Pomerado without a browser on this machine. Without device\_code it returns verification\_url and user\_code: give both to the person, who opens the link on any device, signs in (Google, GitHub or email; a new account is created) and approves. Then call sign\_in with the returned device\_code every interval seconds: it returns status pending until they approve, then once an API key (secret) for their account, valid 90 days. Configure it as this MCP's Authorization: Bearer header; it works on every Pomerado MCP and the REST API. Never ask the person for a password.

**Effect:** May change a website or your account.

| Argument | Required | Type | Description |
| - | - | - | - |
| `device_code` | No | string | The device\_code an earlier sign\_in returned; omit it to start a sign-in. Polling returns the API key once, after the person approves. |

## Pomerado API tools

These three tools reach every operation in the [API reference](/api-reference/introduction), by its `operationId`, with the same input, answers and errors as REST. Search lists only the operations your account can use.

### `search_pomerado_api`

Search the Pomerado API for everything beyond running and building website tools: API keys, saved logins, connected apps, usage, webhooks and more. Lists only operations your account can use, each with its group, summary and effect (read, write or destructive). Omit query to list them all.

**Effect:** Reads only; changes nothing.

| Argument | Required | Type | Description |
| - | - | - | - |
| `query` | No | string, up to 200 characters | Words to look for in operation names and descriptions; omit to list all |
| `group` | No | string, up to 60 characters | Only this group, such as api\_keys |

### `describe_pomerado_api`

Describe one Pomerado API operation from search\_pomerado\_api: what it does, its input schema, its answers and errors, and its REST route. Read it before call\_pomerado\_api.

**Effect:** Reads only; changes nothing.

| Argument | Required | Type | Description |
| - | - | - | - |
| `operation` | Yes | string, up to 100 characters | An operation from search\_pomerado\_api, such as api\_keys.create |

### `call_pomerado_api`

Call one Pomerado API operation with the input describe\_pomerado\_api gives, and return its JSON answer. A destructive operation cannot be undone, so confirm it with the user first. An answer that carries a secret, such as a new API key, reaches this conversation; pass deliver "dashboard" where the operation offers it to keep the secret out.

**Effect:** May change a website or your account, and a change may not be undoable.

| Argument | Required | Type | Description |
| - | - | - | - |
| `operation` | Yes | string, up to 100 characters | An operation from search\_pomerado\_api, such as api\_keys.create |
| `input` | No | string | A JSON-encoded object holding the operation's input, every field describe\_pomerado\_api lists by name. Omit it for an operation that takes none. |


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