Tools and access

Every action you publish has an access level. It decides whether assistants can see it and how changes are approved.

In the console, Confirm is called Ask first.

When Gephyr imports your API, actions that delete, involve money, cancel, or send or publish start on Ask first, and its AI can make levels stricter but never looser. You can still choose Write for one. If one of these is on Write when you publish, including actions you add by hand, Publish & share points it out. It never stops you publishing.

Changing levels in the console

On your app’s Actions tab, each action has a level (Read, Write or Ask first) and an on/off switch. Switching an action off hides it from assistants; switching it back on brings it back at the same level. What do Read, Write and Ask first mean? at the top of the tab opens a short guide to each level, with an example. Click Save actions, then publish: changes reach your users when you publish.

How Confirm works

1. The assistant calls the action. Gephyr doesn’t run it. Instead it checks the inputs (if they couldn’t run, the assistant is told what’s wrong and nothing is asked) and returns a preview of exactly what will happen, plus an approval token.
2. The assistant shows the preview to the user.
3. If the user agrees, the assistant calls again with the token, and Gephyr runs the action.

Approve in the AI app. Some AI apps can show their own approval screen (MCP 2026-07-28 with elicitation). In those apps Gephyr skips the preview in the chat: the app shows the user the action and every input it will run with, including any defaults, with Approve and Decline, and the action runs only if they approve. If the inputs are too long to show in full, Gephyr doesn’t ask and nothing runs. Characters that would be invisible on the screen (zero-width, direction-changing and tag characters, and variation selectors other than the one an emoji uses) are shown written out, like \u{e0070}, so nothing in an input can be hidden from the person approving it. The approval goes from the app straight back to Gephyr, so the assistant never handles it and can’t approve anything by itself. Other AI apps keep the steps above. It’s on by default; switch it off on the Actions tab, under How agents use your app, if you’d rather every app use the preview in the chat. As more AI apps add approval screens, your users get them without you changing anything.

Input names. Approval screens show each input by a name people can read: membership_id shows as “Membership ID”. To choose your own, open the action on the Actions tab and fill in Names people see when they approve. Leave a box blank to use the automatic name. If your API docs give an input a title, importing them fills it in for you. Agents still see and use the real names. If two inputs would end up with the same name, both also show their real names so they can’t be confused.

Approvals are strict:

• Exact: an approval only works for exactly the same action and inputs. Change anything and a new approval is needed.
• Short-lived: approvals expire after 5 minutes.
• Single use: each approval runs once. If the assistant retries after success, it gets the original result back, and the action doesn’t run twice.
• Per user: an approval only works for the signed-in user it was created for. One user can never use, or replay, another user’s approval.
• Uncertain outcomes stay used: if your API times out or errors, the approval stays used rather than risk doing it twice. The user is told to check before trying again.
• Every approved action gets a receipt: a signed record of what was approved, how and where, and how it went, to answer a dispute. Your API gets its id in the Gephyr-Receipt header. See Receipts.

Account security

Actions that change how someone signs in, or who can get into an account, get extra care. Gephyr applies this when it drafts actions from your API docs, and its AI can make these levels stricter but never looser:

You can change any level before you publish. The one rule Gephyr enforces is that an action taking a password is never Read or Write.

What agents get back

AI agents read every answer your API gives them, and long answers cost them: they slow down, cost the user more and miss things. Open an action on the Actions tab and go to What the agent gets back to choose what it returns. The row on the Actions tab shows what’s set, such as Pages: cursor or Up to 50 items.

• Fields. Set each field to Return, Hide or Return, written by other people. With Return every field your API sends, except hidden ones ticked, the agent gets everything but the fields set to Hide. Untick it to send only the fields set to Return, so a field your API adds later never reaches agents until you add it here. Hide keeps a field out even inside one that’s returned, and in every item of a list. A plain name like email is hidden wherever it appears in the answer, at any depth. A dot path like owner.email hides only that field, starting from where the answer (or List starts at) begins, and in every item where a step is a list: members.email hides each member’s email. When you import your API docs, Gephyr already hides secrets and owner IDs (see what each action contains).
• List starts at. Where the list is in your API’s answer, such as data.items. Leave it empty if the answer is the list.
• Paging. For an action that lists things, tell Gephyr how your API pages: Cursor, Page number, Offset or Link header, and which of your API’s inputs it uses. Agents then get the same two inputs on every list, limit and cursor, whatever your API does underneath. Each answer is one page, with has_more and a next_cursor for the next one. Gephyr signs every cursor, so an agent can only ask for pages your API pointed to, and a next page outside your API’s address is never offered or called. A cursor works only for the person it was made for and lasts a day; after that the agent starts the list again. If your API says whether there’s more (a field like has_more), Gephyr goes by that. For page numbers and Link headers, a cursor keeps the page size it was made with, so the agent never skips or repeats items. Paging works on Read actions that use GET. When you import your API docs, Gephyr sets it up for the list endpoints it recognises.
• Let agents ask for fewer fields. Adds a fields input to a Read action, so an agent can ask for just the fields it needs, such as names and dates. It can only choose from the fields set to Return.
• Most items per answer. For a list that doesn’t page: the most items the agent gets. The agent is told when there were more.
• Size limit. The most an answer can be, in characters (about 4 to a word). The default is 40,000, about 10,000 words. A longer list is cut at the last item that fits, and the agent is told how much it saw and how to see the rest: a smaller page, fewer fields or a filter. An answer that isn’t a list is never cut.

Each page an agent asks for is one call. Advanced: edit as JSON shows the same settings as code.

When your API refuses a call. For a 4xx answer (other than 401), the agent gets your API’s own reason, so it can fix what it sent and try again: “Upstream returned 400. The API said: “Latitude must be in range of -90 to 90”“. Gephyr takes the reason from the usual places (message, error, detail, reason, errors[0] and the like, or a short plain-text answer), puts it on one line, cuts it at 300 characters and removes hidden characters. Sign-in failures (401), server errors (5xx) and HTML error pages are never passed on: the agent gets the status only. When your server errors or doesn’t answer in time, the agent is also told what to do next: after a look-up, try once more and then tell the user your app isn’t answering; after a change, that it may have happened, so check before doing it again rather than repeating it. So write your 4xx messages for the person fixing the request, and leave internal details out of them. When your API answers 404 without a reason the agent can be shown, the agent is told nothing was found for what it sent and to check ids and names against an action that lists them. An answer over 1 MB is never passed on: after a look-up the agent is told to ask for less (one item, a filter or a smaller page); after a change it’s told the change may already have been made, to check before doing it again. A change your API accepts (any 2xx) counts as done even if your API answers in plain text, like “Deleted”, rather than JSON: the agent gets the text, and an approved action is never reported as uncertain because of it. An HTML page isn’t taken as proof (a sign-in or error page can come back as 200), so answer changes with JSON, plain text or an empty 204. A look-up still needs a JSON answer. Calls your API refuses are never billed.

On your dashboard, Actions in use shows how big each action’s answers usually are and how many were cut to fit, and Activity marks each cut call. If one action’s answers are cut often, Overview says so in What to fix next, with Turn on paging when your API docs show how the list pages. In each action’s What the agent gets back, Gephyr suggests fields to hide that look private and a paging setup from your API docs.

Text written by other people

Some of what an action returns is typed by other people: a message’s body, a comment, a review, someone’s bio. An AI agent reads it like everything else, so a stranger could write instructions into a message and hope the agent follows them.

To guard against that, open the action on the Actions tab and, under What the agent gets back, set those fields to Return, written by other people: body and subject, say, or review and author.bio. A name matches that field anywhere in the result; a dot path like sender.name picks a nested one. Gephyr then marks their text in what the agent reads and tells it to show the text to the user, never follow it. When you import your API docs, Gephyr fills in likely fields on actions about messages, comments or reviews; check them before you publish. Listing a field your API doesn’t return does nothing.

This lowers the risk but doesn’t remove it, so keep actions that send things out on Confirm. More in the security overview.

The agent guide

Every connector comes with a guide for assistants, generated from your actions: what each one does, how Confirm works, and your own notes (Notes for AI agents, under How agents use your app on the Actions tab). Assistants receive the short version when they connect and can read the full one with the built-in get_help tool. For apps with many actions, the full guide lists every action in one line each. Keep descriptions accurate; the guide updates when you publish.

Your input limits (a maximum, a length, a list of choices) are checked by Gephyr on every call, and anything outside them is refused before it reaches your API. AI apps also see the limits, and some quietly change a user’s value to fit (a 700-minute workout sent as 600). So whenever an app has Write or Confirm actions, the guide tells agents never to change a value to fit a limit, and to tell the user and ask instead. Most models follow it, but it’s an instruction, not a guarantee: for actions where an exact value matters (amounts, dates, quantities), use Confirm, whose approval shows the user every value before anything happens. Suggest notes drafts the notes for you with Gephyr AI, for you to edit before saving.

Apps with many actions

AI apps work best with a short list of tools: past a few dozen, they slow down, cost more and pick the wrong one more often. So when your app has more than 40 actions on, Gephyr lists four tools instead of one per action:

• search_actions finds actions for what the user wants, by name and description.
• describe_action gives one action in full: what it does and its inputs.
• call_read_action runs a Read action. It’s marked read-only, so AI apps don’t ask the user first.
• call_action runs any action, including Write and Confirm ones. It’s marked as making changes, so AI apps may ask the user first.

Nothing else changes. Every call is the action’s own call: its inputs are checked, its level applies (Confirm still needs the user’s approval), paying-customers-only rules and limits apply, it’s billed only when it succeeds, and it shows on your dashboard under the action’s name. Searching and describing never reach your API and are never billed. Actions that are off can’t be found or run. Confirm actions use the AI app’s own approval screen, or the preview and confirmation.

To choose, open How agents use your app at the top of the Actions tab and pick How agents find your actions: Automatic (the default: every action listed up to 40, then the four tools), Always list every action, or Always let agents search. Then publish. A link with 40 actions or fewer on lists them all, even when your app’s own address uses the four tools. Test with AI always tests your actions as a full list, because it checks each description on its own.

Limits

Each user’s agent can use each action a limited number of times a minute and a day, and a Write action repeated with the same inputs within 10 seconds is only sent once. The defaults suit most apps; change them on the Protection tab. See Protection.

What your users asked for

When a user asks their AI agent for something your app can’t do yet, the agent sends Gephyr a short note instead of giving up, for example “wanted to pause a membership”. It’s how you learn what to build next, in your users’ own words.

• How: every connector has a built-in request_capability action, and its guide tells agents when to use it. The agent sends a note of up to 280 characters, plus an optional theme such as “bookings”.
• Where you read them: your app’s Activity tab, in What users asked for, covering the last 7 days and grouped by theme, on Growth and Scale. Starter and Launch see how many requests came in.
• On by default. To switch it off, untick Let AI agents record feature requests under How agents use your app on the Actions tab, then publish.
• Never billed, and each user’s agent can send up to 10 a minute (see Protection).
• Turn them into actions: Match to your API on Activity has Gephyr AI match requests to endpoints in your API docs that no action uses yet, each with a ready action to add.
• Private: notes aren’t linked to who sent them. Users can type anything, though, so treat them as user content. See Security.

Good practice

Check your descriptions with Test with AI, at the bottom of the Actions tab: it runs realistic requests on real AI models and shows which actions they mix up. See Test your actions.

• Start with Read actions plus a few Write actions your users ask for most.
• Use Confirm for anything involving money, cancellation or deletion, and for account security (above).
• Write descriptions for an assistant that has never seen your app: what it does, when to use it, what the inputs mean.
• Hide response fields assistants don’t need.

Something missing or wrong? Email hello@gephyr.ai.