# What agents can do

URL: /docs/ai/tools

Ask in plain language: your agent picks the tools. Name the project, give a time range, and ask for drafts before changes. Anything marked **Write** needs **Write** access for that resource when you [approve access](/docs/ai#approve-access).

## Example prompts [#example-prompts]

**Weekly summary**

> Summarize the opinions for Summer Menu Lab from the last 7 days. Group them into themes, say how many opinions are in each, and quote one per theme.

**What to fix first**

> Read all opinions and answers for my Storefront project from the last 30 days. List the three problems customers mention most, how often each comes up, and one practical fix for each.

**Draft replies**

> List every unresponded opinion in Summer Menu Lab and draft a short, warm reply to each that mentions something specific the customer said. Don't post anything.

**Post approved replies (Write)**

> Post these replies to the opinions we just discussed: [paste your edited replies].

**Suggest and create questions (Write)**

> Our goal for Autumn Brunch Pilot is "Decide whether to keep brunch on weekdays." Suggest five short questions with an answer mode and tags for each, then create the ones I approve.

**Tidy the question library (Write)**

> List the active questions in Summer Menu Lab with their priority and number of answers. Recommend which to archive, then archive the ones I confirm.

**Send personal links (Write)**

> Send a personal review link for Summer Menu Lab to each of these customers, with their order number as the reference: [paste names, emails, order numbers].

**Set up a project (Write)**

> Create a project called "Autumn Brunch Pilot", add the goal "Decide which three brunch dishes to keep", then suggest five questions and create them after I approve.

Replies are public: they're posted as your business with an **Owner** badge.

## Tools [#tools]

Each tool is one Business API operation, with the same input and errors as the [REST API](/docs/api-reference). Most take a `projectId`, so ask your agent to start with `projects_list`.

### Billing [#billing]

| Tool | Access | What it does |
| --- | --- | --- |
| `billing_entitlements` | Read | Get the organization's current plan, feature entitlements, and usage limits. |

### Projects [#projects]

| Tool | Access | What it does |
| --- | --- | --- |
| `projects_list` | Read | List the projects in the organization that the caller can access. |
| `projects_create` | Write | Create a project with its own team. The creator is added to the project team. |
| `project_get` | Read | Get one project by ID. |
| `project_update` | Write | Update a project's name, slug, description, status, visibility, or settings. Archived projects can be restored. |
| `project_upload` | Write | Upload an image for a project and return its public URL. |
| `project_delete` | Write | Delete a project and its team. The root storefront project cannot be deleted. |

### Goals [#goals]

| Tool | Access | What it does |
| --- | --- | --- |
| `project_goals_list` | Read | List a project's goals. |
| `project_goals_create` | Write | Add a goal to a project. |
| `project_goals_update` | Write | Update a project goal. |
| `project_goals_delete` | Write | Remove a goal from a project. |

### Questions [#questions]

| Tool | Access | What it does |
| --- | --- | --- |
| `project_questions_list` | Read | List a project's guided questions. |
| `project_questions_create` | Write | Add a guided question to a project. |
| `project_questions_update` | Write | Edit, activate, or archive a project question. |
| `project_questions_delete` | Write | Remove a question from a project. |

### Tags [#tags]

| Tool | Access | What it does |
| --- | --- | --- |
| `project_tags_get` | Read | Get the tags a project measures, including their display metadata and sentiment metrics. |
| `project_tags_update` | Write | Choose which tags a project measures. |

Project tag IDs use the lowercase keys `trust`, `reliability`, `experience`, `safety`,
`personalization`, `fairness`, `identity`, and `outcome`. The update input is an array
of `{ id }` objects, such as `[{ id: 'trust' }, { id: 'experience' }]`; it has no
`position` field. Tag selection is unordered and does not affect question selection or
Auto priority. The read response includes each tag's stored `name` and `description`,
plus `metric`, `metricName`, `metricRationale`, `selected`, and `sentiment` metadata.

### Delivery [#delivery]

| Tool | Access | What it does |
| --- | --- | --- |
| `project_link_create` | Write | Create a pre-verified opinion link for one customer and optionally email it. Each project can email the same customer once every 48 hours. |
| `project_link_list` | Read | List a project's delivery links and their status. |
| `project_link_resend` | Write | Email an existing, unexpired delivery link to its customer again. The 48-hour email cooldown applies. |
| `project_embed_get` | Read | Get the project's embedded opinion form settings, including allowed origins. |
| `project_embed_update` | Write | Update the project's embedded opinion form settings. An empty origin list allows every website. |

### QR codes [#qr-codes]

| Tool | Access | What it does |
| --- | --- | --- |
| `project_qr_display` | Read | Get the current link for the project's rotating QR code. Fetch it again when `validUntil` passes. |

### Opinions [#opinions]

| Tool | Access | What it does |
| --- | --- | --- |
| `project_opinions_list` | Read | List a project's opinions with search, reply-status, and date filters. |
| `project_opinions_reply` | Write | Post a public team response to an opinion. |

### Answers [#answers]

| Tool | Access | What it does |
| --- | --- | --- |
| `project_answers_list` | Read | List customers' answers to a project's questions. |

### Subscribers [#subscribers]

| Tool | Access | What it does |
| --- | --- | --- |
| `project_subscribers_list` | Read | List a project's subscribers. |
| `project_subscribers_count` | Read | Count a project's subscribers. |
| `project_subscribers_invite` | Write | Email invitations to subscribe to a project. |

### Knowledge base [#knowledge-base]

| Tool | Access | What it does |
| --- | --- | --- |
| `kb_get` | Read | Get the organization's knowledge base items. |
| `kb_create` | Write | Add an item to the organization knowledge base. |
| `kb_update` | Write | Update an organization knowledge base item. |
| `kb_delete` | Write | Delete an organization knowledge base item. |

### Webhooks [#webhooks]

| Tool | Access | What it does |
| --- | --- | --- |
| `webhooks_portal` | Write | Get a short-lived link to the hosted webhook portal, where you can manage destinations and retry deliveries. |
| `webhooks_upsert` | Write | Create or update a webhook destination URL and the event topics it receives. |

File uploads, such as `project_upload`, take the file as an object with `name`, `mimeType`, and base64-encoded `base64` content.

## Security [#security]

Every request is checked on Orvelt's servers against three things, and the agent can only do what all three allow:

1. What you approved for that agent: **None**, **Read**, or **Write** on each resource.
2. Your current role and product access in the organization.
3. Your project team access.

If an owner removes your access, the agent loses it on its next request. Changing billing and managing MCP connections are never available through MCP.

Tool results, such as opinions or subscriber emails, go to the agent and the AI provider behind it. Give **None** to anything the agent doesn't need, such as subscribers, and connect only agents you trust with customer data. Each person connects their own agent: a connection always acts as the person who approved it.

**Disconnect an agent:** open **Integrations**, select **Manage** on the **Business MCP** card, and select **Disconnect** next to the agent. Its access stops immediately.

MCP doesn't use API keys: an MCP connection can't call the Business API, and an [API key](/docs/developers/api-keys) can't be used with MCP.

### OAuth scopes [#oauth-scopes]

Read tools need the `business:read` scope and write tools need `business:write`; there are no MCP-specific scopes. Connections approved with the older `mcp:read` / `mcp:write` scopes must reconnect. MCP and the Business API use separate token audiences and reject each other's tokens.

## Troubleshooting [#troubleshooting]

**The browser doesn't open to sign in**

Use your client's authenticate command from [Connect using MCP](/docs/ai/connect-coding-agents), such as `/mcp` → **Authenticate** in Claude Code. In Claude, select **Connect** next to Orvelt under **Settings → Connectors**.

**The approval page says the request can't be approved**

The request expired or was changed. Start connecting again from the agent.

**The agent keeps asking me to sign in**

**Stay connected between sessions** was off. Disconnect and connect again with it on.

**I chose the wrong organization**

Disconnect the agent under **Integrations → Business MCP**, then connect again and choose the right one.

**The agent can't find any Orvelt tools**

Check the server URL is exactly `https://mcp.orvelt.com/mcp` and restart the client.

**Write tools are missing**

The connection is read-only for that resource. Disconnect, connect again, and choose **Write** for it.

**Access denied (FORBIDDEN) or Not found (NOT_FOUND)**

The agent acts as you, so check your organization, project, and product access. [Fix access problems](/docs/organization/troubleshooting). For **NOT_FOUND**, ask the agent to start with `projects_list` and use the IDs it returns.

**Rate limited**

Wait a minute before trying again.