---
name: mindset-function
description: Use when building a function in Mindset (mindset.ai) through the mindset-admin MCP server, the fixed pipeline an agent calls as one tool. Covers choosing a function, an agent or a single operation, writing the steps (operation calls, model calls through an AI model connection, computed values, choices), test runs on real input, getting a version activated and the function enabled, and giving it to an agent.
metadata:
  title: Build a function
  blurb: Builds a function, a fixed set of steps an agent calls as one tool.
  group: Mindset MCP
  order: 2
  docs: build-a-function, versions-and-going-live
  checked: 70d2d364d
  updated: 2026-11-11
---

# Build a Mindset function

When you finish, an enabled function with an active version does one job that has one right answer, its test parameters have run on real input and read as verified, and an agent holds it. If the work has to wait for a person or happen in a fixed order, use the `mindset-script` skill instead.

## Mindset in brief

Mindset is a hosted platform for building, running and governing AI agents. An **agent** is configuration, not code: a prompt, a model, and the resources it may use. Those resources are **scripts** (steps that must wait or happen in order), **functions** (fixed steps with one right answer), **widgets** and **connections** (the only way data enters or leaves). People manage all of it in the Studio, a web app, or through Mindset's MCP servers.

## Where you are building: host, org, environment

Every Mindset call names three things. Get all three from the person before you write code or call a tool. Never guess or invent them.

| Value | What it is | Where the person finds it |
|---|---|---|
| **Host** | The Mindset deployment their org lives on, for example `https://eu.mindset.ai` | The address bar when they're signed in to the Studio, or an agent's **Embed** tab |
| **Org slug** | Their company's account. The org is the isolation boundary: members, model keys, settings and audit sit here, and one org can never see into another | An agent's **Embed** tab, or the users' server address under **Settings → Systems → Connect an AI client → For users** |
| **Environment slug** | A named partition inside the org, such as Sandbox, Test or Production | An agent's **Embed** tab, or the same address. The **Environment** switcher in the Studio shows which one is current |

How environments behave:

- **Agents, scripts, functions, connections, triggers, schedules, conversations, runs and API keys each belong to exactly one environment** and can't see anything in another.
- **Every org starts with one environment, Sandbox, whose slug is `sandbox`.** A slug never changes, even when the environment is renamed. Use the slug, never the display name.
- **Nothing copies between environments.** To promote a change from Test to Production, make the same change again in Production.
- **Don't create an environment to hold your work.** Environments are for stages such as Test and Production, not for projects, and only a person can delete one, with everything in it. Work in the environment the person names. Create one only if the person asks you to.
- **Members, model keys and org settings are shared by every environment.** Changing an org setting changes it everywhere.

## Credentials for building in Mindset: sign in, never a key

You build inside Mindset through the **`mindset-admin` MCP server**. The person signs in with their own Mindset account in a browser, and they must be an org admin. There is no key or token, so never ask the person for one.

- **The server address names one environment**: `<host>/api/v1/orgs/<org-slug>/envs/<environment-slug>/mcp`. Every call goes to that environment unless the tool call passes `envSlug` to point that one call at another environment. Org-level tools refuse an `envSlug`.
- **No tool takes a secret value.** When a connection needs a credential, call `request_capture`. It returns a reference and a capture URL. Give the person the URL to open and paste the value into themselves, then use the reference. Capture links expire after 15 minutes. For a system that signs in with OAuth, `authorize_connection` returns a sign-in link the person opens the same way, and it expires after 10 minutes. If a link has expired, request a new one. Never ask the person to paste a credential into the conversation, even if they offer.
- **Errors come back structured.** Read `code` and `context` and act on them. Don't retry blind.

## Before you start

This skill works through the `mindset-admin` MCP server. Check that its tools (for example `get_information`) are available to you. If they aren't, set the server up first, following the `mindset-mcp` skill or https://docs.mindset.ai/docs/work-from-claude-code.md, then come back here.

Call `get_information` with no arguments for the platform's own topic index. Its guidance is current for the platform you're connected to. Where it and this skill disagree, follow `get_information`.

## Decide first: function, agent or single operation

Ask what happens if it runs twice on the same input.

- **One right answer: a function.** Comparing an invoice to its purchase order, converting a currency, looking up a supplier's payment terms. Left to an agent, you pay a model to work out something that has a correct answer, and get a slightly different result each time.
- **It needs weighing up: leave it to the agent.** Whether a $340 overage is worth querying depends on the contract and the supplier. That belongs in the agent's prompt, not a function.
- **One call to one system: give the agent the operation.** A function is worth building when it's several calls plus the work between them, so the agent makes one call and gets one answer.
- **Most work is both.** The agent judges, and the function does the arithmetic it judges on. Have the function return the value the agent or its script decides on, such as whether there are any differences at all.
- **A rule a write must never break: a function that refuses.** When the agent may only write within rules (each action maps to fixed values, or the system's own records say no), wrap the write in a function that checks first and writes only when nothing refused, and give the agent that function instead of the raw write. A policy rule in the prompt is for judgment; it can't make a write impossible. `get_information` with `topic: "choosing-what-to-build"` has the worked comparison.

If the person's request is judgment, say so and don't build a function.

## Ask the person for

- The job in their own words, and one real input for each path through it, for example "an invoice that matches its purchase order, and one with a price difference". These become the test parameters.
- Which connection holds the data (a pure calculation needs none), and for a model step which **AI model** connection to use. The connection fixes the model, so never ask which model name to write.
- Which agent should hold it, and whether that agent already has an active version.
- If the function writes: where a test write can land safely, such as a test supplier record.

## Step 1: read the language and the parts

1. Call `get_information` with `topic: "dsl-reference"` and read it whole. It's the function language as the validator enforces it: every operator (dates and today's date among them), allowed input values, the result shapes and the refusal codes.
2. Read `get_information` with `topic: "authoring:function"`: the path from save to an agent holding it, and what catches people.
3. Call `find_examples` with `resource_type: "function"` and the intent in the person's words. Start from the closest example: there are worked ones for a date rule and for a write that refuses before it writes. A result whose `grain` is `counter-example` is a refusal to relay to the person, not a body to copy.
4. List the operations: `list_resources` with `type: "connection_operation"` and `filter: { connection: "<connection id>" }`, then `get_resource` on each one you'll call. Check its input, its `tested` status, and that its `exposures` includes `functions`. If it doesn't, add it with `edit_resource` (a `path_set` on `exposures`); the Studio has no control for it. An operation must also be enabled, and a write may be waiting for a person to enable it.
5. See what an operation really returns before you bind to it: `test_resource` with `type: "connection"` and `input: { operation, input }`. It reads by default and refuses a write.

## Step 2: write the document

A function document has `handle`, `kind: "declarative"`, `input`, `steps` (each an `id` and exactly one operation in `do`) and `return`, plus an optional `output` schema. Each step does one of four things:

| Step | How | Invoice example |
|---|---|---|
| Calls a connection operation | `$op` with `connection`, `operation`, `input` | Fetch the purchase order for the invoice number |
| Asks a model | `$llm` with `prompt`, `connection` (an AI model connection), `schema` | Pull the quantity received out of a free-text delivery note |
| Works out a value | A pure expression: `$filter`, `$map`, `$sum`, `$sub` and the rest | List every line where quantity or price differs |
| Chooses between values | `$cond` | Return "no action" when the list of differences is empty |

The rules agents get wrong most often:

- **An effect is a whole step.** `$op` and `$llm` can't sit inside `$map` or any other expression (`effect_in_expression`). To call once per item, put `over` (a list) and `as` (an item name) on the step. The result is an ordered list of `{ index, status, value, error }`, and a failed item doesn't stop the others. The limit is 1,000 items, run 8 at a time.
- **There are no local variables.** To reuse an intermediate value, make it its own step and bind `steps.<id>.result`.
- **A wrong binding fails silently.** The evaluator never throws: a missing path yields nothing. An `$op` result is the raw response body (no `.body` wrapper). Under `over`, an `$llm` item's `value` is the completion text itself. A run that succeeds and returns nothing usually means a bad path or an input the caller never sent.
- **Declare every input** with an example value or a JSON Schema node. Never put a `$bind` in `input` (`input_schema_required`). Example values become the function's test parameters; with `input` as a JSON Schema, keep them in `testParameters`. Arithmetic on a missing value can come out as a plausible 0, so list what callers must send in `required`, or check it in a step and return a problem. Give the function a `description` when you create it: the agent reads it, with each input's `description`, to decide when to call it.
- **Allowed values are checked for you.** List them as `enum` on a top-level input and a call sending anything else is refused before the first step (`input_not_allowed`). An `enum` nested in a list or a record is not checked: refuse that in a step.
- **Dates have operators.** `$daysBetween`, `$addDays` and `$today` (today in the Org's timezone). Never work a date out with arithmetic, and give a date rule an optional `asOf` input that falls back to `$today`, so a test can pin the day.
- **Declare `output`** when the return uses `$reduce`, `$parseJSON`, an `$llm` without `schema`, or a step's `error` (`output_schema_required`).
- **Every step runs.** You can't skip one on a condition: branch with `$cond`. A failed step stops the run unless it's marked `optional: true`, and then a later step can read `steps.<id>.error`.
- **Retries are off by default.** `retry` is an object, `{ "maxAttempts": 3, "retryOn": ["429", "5xx", "timeout", "network"] }`, and `maxAttempts` counts every attempt, up to 10.
- **No credentials, no raw HTTP.** Every outside call is an `$op` on a connection, even to a public host. A literal secret in a header is refused (`secret_literal`).
- **A function can't call another function** (`composition_unsupported`).
- **A write's destination comes from an input**, never a literal in the step, so the test inputs decide where a test write lands.

Before you save, call `render_function_doc` with the `doc`. It describes what each step does and what happens when it fails. Fix anything that surprises you.

## Step 3: create it and change it

- `create_resource` with `type: "function"` and `input: { name, doc, idempotencyKey }`. Always send `idempotencyKey` (any string of 8 or more characters for this one intent). If the call fails, retry with the **same** key, because the first may have committed. A key means one intent: re-sending it with different content returns the original function and drops your changes.
- Creating saves version 1. A new function starts disabled, and nothing can call it until a person activates a version and enables it.
- To change it, `get_resource` first for its `versionToken` and `acceptedEditOps`, then `edit_resource` with `ops` (`add_step`, `set_step`, `move_step`, `remove_step`, `set_return`, `set_input`, `path_set`, `path_remove`, `full_replace`). Each edit saves a new version, which isn't active. A `path_set` on an object patches it: delete a key with `path_remove`.
- A save that breaks a rule is refused with a code and a message naming the step or field. Fix that and save again.

## Step 4: test it on real input

1. Run it: `test_resource` with `type: "function"`, `ref` (its id or handle) and `input`. It runs the newest version, active or not, and returns a per-step trace and a `runId`. Its result is cut short; `get_run` with that `runId` returns it whole, with the full record. While you iterate on a function that writes, `dryRun: true` runs the reads for real and skips each write. A dry run never makes a write tested.
2. Keep a test parameter set (resource type `flow_test_parameters`) with one scenario per path. Read `get_information` with `topic: "authoring:flow_test_parameters"` for the shape. Include one awkward case. The first set, `contract example`, is made for you from the function's example input.
3. Run each set with `test_resource` and `parameterSet`. `verified` is true only when every step was exercised. `notExercised` names each step that wasn't, and why.
4. **A test that writes needs a go-ahead.** The first call is refused with `write_go_ahead_required`, a write list and its `listHash`. Tell the person what the run will read and what it will write, and where. When they say go, call again with `goAhead: { listHash, instruction }` beside `input`, quoting their words. Never invent a go-ahead. The writes are real.

## Step 5: a person activates and enables it

- You can't activate a version or enable a function. A person does both on the function's **Versions** tab in the Studio: **Activate version N**, then the **Enabled** switch. Activating never enables it. The reply to your save carries the link in its `next` block: give it to the person. `get_resource` reads `activeVersion` and `enabled`.
- **Activating needs tested operations.** Activating is refused with `operations_untested` while a step calls an operation with no successful call on record. Run the test parameters first, so the person can activate. For a function that writes only when its rules allow, that means a test parameter scenario where every rule holds, aimed at a safe target, run once for real under a go-ahead: `authoring:function` has the steps. **Activate untested** is the person's own choice in the Studio. A step that calls a write still waiting for a person to enable it is refused with `operation_awaiting_approval`: a person enables the operation, then a test run makes it tested.
- **Activating reaches every agent that holds the enabled function on its next call.** Nothing on the agents is activated. Before a person activates a new version of a function in use, find out which agents hold it (in the Studio: **Govern → Monitor → Topology**).
- Going back to an earlier version is the person's act too: **Activate version N** on that version. Disabling stops every agent calling the function and keeps its active version.

## Step 6: give it to an agent

The agent holds it as a tool named `function__<handle>`, and a behavior test that checks the call names that tool.

1. `agent_config_admin` with verb `set_assignments` and `assignments: { functions: [<every function the agent should hold>] }`. A type you name is replaced whole, so include the functions it already has. It saves an agent version that isn't active.
2. Tell the person the version number, and that they activate it on the agent's **Versions & Availability** tab. The reply's `next` carries the link.
3. Call `agent_config_admin` with verb `assignment_health`. `unusable` names a function the agent won't get (one disabled or with no active version, for example), and `resourceChangesNotActive` says the change is saved in a version that isn't active.
4. If the agent's script calls the function, the phase that calls it must also list it. See the `mindset-script` skill.

## Rules

- Never put a credential in a function. Credentials live on connections.
- Never pass a write go-ahead the person didn't give in their own words.
- You can't activate anything. Save, and tell the person what to activate and enable, with the link.
- Nothing deletes a function yet. To stop agents calling it, a person disables it.

## Check it works

- `render_function_doc` describes what the person asked for.
- Every test parameter set reads `verified: true`, including the awkward case.
- Once the person has activated and enabled it, `get_resource` shows that version active and `enabled: true`.
- `assignment_health` reports nothing `unusable` and no `resourceChangesNotActive` once the agent's version is active.
- The person asks the agent something that needs the function, on its **Chat** tab, and the run record shows the call.

## When it fails

| What you see | Cause and fix |
|---|---|
| A step returns nothing and everything after it is empty | A bound path doesn't match the real shape. Read the trace in `get_run`, or test the operation on its own, and fix the path |
| `status: "ok"` with an empty result | The caller didn't send an input the steps bind. Check every `input.<name>` arrived |
| `effect_in_expression` | An `$op` or `$llm` is nested in an expression. Make it its own step, with `over` for a list |
| `input_schema_required` or `output_schema_required` | An input or the output can't be typed. Declare it |
| `output_mismatch` | The return doesn't produce what `output` declares. `context.differences` names each path |
| `input_not_allowed` | The call sent a value outside an input's `enum`. `context.inputs` names it and the allowed values |
| A step calling an operation fails | The operation isn't enabled, isn't offered to functions, or a write is waiting for a person to enable it. Check it on the connection |
| `write_go_ahead_required` | Expected for a test that writes. Get the person's go-ahead, then call again with `goAhead` |
| `operations_untested` when the person activates | Run the test parameters until each named operation has a successful call |
| `operation_awaiting_approval` when the person activates | A step calls a write still waiting for a person to enable it. They enable it on the connection's **Operations** tab, then run the test parameters |
| It runs on its own but the agent never calls it | Disabled, no active version, not assigned, or the agent version holding it isn't active |
| It runs out of time on a big list | Use `over` on one step instead of the agent calling the function many times, or give each run fewer items |

## Read more

Fetch these as Markdown when you need more than this skill gives you. If one disagrees with this skill, the page is newer: follow it.

- https://docs.mindset.ai/docs/build-a-function.md: read for the running invoice example and what each Studio tab shows the person.
- https://docs.mindset.ai/docs/versions-and-going-live.md: read for test parameters, write go-aheads, tested status and what makes it lapse.
- https://docs.mindset.ai/docs/versions-and-going-live.md: read when you need to know when a change reaches people and how to go back to an earlier version.
- https://docs.mindset.ai/docs/runs.md: read to size a function against its time and call limits.
- https://docs.mindset.ai/docs/approve-what-an-agent-can-do.md: read when an operation the function writes through is waiting for a person to enable it.
