# Tool reference

Every tool the MCP server offers an agent: what it does, the access it needs, its inputs and an example call.

Each tool is described here as the MCP server describes it to an agent, so this page says exactly what your agent is told.

An agent has the tools its access allows, chosen when it signs in: **Read**, **Run** (Read's tools, and those that compile and run drafts, run Test sets and evaluate them) or **Full** (every tool). The three tools that find and call your deployed Decisions come with their own permission, ticked at sign-in. A personal access token has the same three levels without them, and an agent token has those three alone.

- [How to connect an agent](https://typefuse.dev/guides/agents)

## Calling deployed Decisions

With the permission to call your deployed Decisions, whatever the agent's other access.

### search_decisions

**Search Decisions.** Call permission. Reads.

Find a deployed Decision for a kind of judgement, such as "fraud check on a card payment". Name the judgement, not the item: pass the item's details when you call the Decision, never here. Find once, then call it for each item; search again only when the judgement changes. Each match carries the exact call to make. When nothing fits, say so rather than calling something unrelated.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `judgement` | `string`, 1 to 300 characters | Required | The kind of judgement you need, in plain words. |
| `domain` | `string`, at most 60 characters | Optional | Optional: the area, such as payments or support. |
| `item_type` | `string`, at most 60 characters | Optional | Optional: what is being judged, such as card_transaction. |
| `limit` | `integer`, 1 to 20 | Optional |  |
| `correlation_id` | `string` | Optional | Optional: your own id for this piece of work. |

**Answer**

| Name | Type | Description |
| --- | --- | --- |
| `note` | `string` |  |
| `searchId` | `string` | Pass it as discovery_id when you describe or call a match. |
| `outcome` | `string`, one of `matched`, `no_match`, `nothing_offered`, `filtered` | matched; no_match (nothing offered fits); nothing_offered (no Decision is offered to this agent); filtered (a match exists where this agent can't call). |
| `matches` | `array of { "decision": string, "call": { "tool": "call_decision", "decision": string, "environment": string } }` |  |
| `message` | `string` |  |

```json
{
  "name": "search_decisions",
  "arguments": {
    "judgement": "whether a returned order can be refunded"
  }
}
```

### describe_decision

**Describe a Decision.** Call permission. Reads.

Read a Decision's contract before calling it: what it decides, when to use it and when not, the input it takes (inputSchema, with its required fields) and what each answer means (answersSchema).

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `decision` | `string`, 1 to 200 characters | Required | The Decision's identifier from a search match, such as acme/refund-eligibility. |
| `environment` | `string`, 1 to 60 characters | Optional | Optional: the environment to use, from the match's deployments. Without it, the match's call.environment is used. |
| `discovery_id` | `string`, at most 80 characters | Optional | The searchId of the search that found this Decision. |

**Answer**

| Name | Type | Description |
| --- | --- | --- |
| `note` | `string` |  |
| `decision` | `string` |  |
| `name` | `string` |  |
| `purpose` | `string or null` |  |
| `whenToUse` | `string or null` |  |
| `whenNotToUse` | `string or null` |  |
| `exampleRequests` | `array of string` |  |
| `environment` | `string` |  |
| `release` | `string` |  |
| `version` | `integer` |  |
| `deployments` | `array of { "environment": string, "release": string, "version": integer }` |  |
| `inputSchema` | `any JSON value` | The input a call takes: the release's state_schema. |
| `answersSchema` | `object` | What each answer means, by question id. |
| `call` | `object` |  |
| `call.tool` | `"call_decision"` |  |
| `call.decision` | `string` |  |
| `call.environment` | `string` |  |

```json
{
  "name": "describe_decision",
  "arguments": {
    "decision": "acme/refunds"
  }
}
```

### call_decision

**Call a Decision.** Call permission. Writes.

Asks an authorised, deployed Decision for its answers, with input that fits its published contract. Returns the native answers and the run's audit reference. It doesn't run code, change any Decision or take any action in your business. Call it once for each item.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `decision` | `string`, 1 to 200 characters | Required | The Decision's identifier from a search match, such as acme/refund-eligibility. |
| `input` | `object or array or string` | Required | The item's details, matching the Decision's inputSchema. |
| `environment` | `string`, 1 to 60 characters | Optional | Optional: the environment to use, from the match's deployments. Without it, the match's call.environment is used. |
| `reference` | `object` | Optional | Optional: what this call is about in your terms, such as { type: "order", id: "8812" }. |
| `reference.type` | `string`, 1 to 40 characters | Required |  |
| `reference.id` | `string`, 1 to 200 characters | Required |  |
| `correlation_id` | `string` | Optional | Optional: ties several calls together. |
| `discovery_id` | `string`, at most 80 characters | Optional | The searchId of the search that found this Decision. |
| `idempotency_key` | `string`, 1 to 200 characters | Optional | Optional: the same key answers once; a retry gets the first answer. |

**Answer**

| Name | Type | Description |
| --- | --- | --- |
| `decision` | `string` |  |
| `environment` | `string` |  |
| `release` | `string` | The semantic release that answered. |
| `version` | `integer` | The exact published version, for replay. |
| `runId` | `string` | The audit reference for this call. |
| `answers` | `object` | Native answers by question id; a per-item question answers a list, one per element in order. |
| `reading` | `string` | Each answer and its confidence in words (per-item lists show the first 10). It states the answers; it never says what to do. |

```json
{
  "name": "call_decision",
  "arguments": {
    "decision": "acme/refunds",
    "input": {
      "request": "The kettle arrived with a cracked lid.",
      "days_since_delivery": 3
    }
  }
}
```

## Read

With Read, Run or Full access.

### list_organisations

**List organisations.** Read access. Reads.

Organisations the caller belongs to, with their role. Send skill_version (the installed TypeFuse skill's version) and the answer ends with a note when a newer skill exists.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `skill_version` | `string`, at most 40 characters | Optional | The installed TypeFuse skill's version, as its SKILL.md names it |

```json
{ "name": "list_organisations", "arguments": {} }
```

### notifications

**Show what is waiting.** Read access. Reads.

What is waiting for the person across their organisations: deployment requests they can approve (with the Decision, release, environment, note and who asked), notices as the organisation's use nears what its plan includes (for owners and admins), and notices that a model a Decision's live or latest release uses will retire soon (for owners and admins; model_status and start_model_trial deal with it). Approving happens in the app, never through MCP: each item's url is the page to give the person.

It takes no inputs.

```json
{ "name": "notifications", "arguments": {} }
```

### export_audit

**Export the audit trail.** Read access. Writes.

Exports an organisation's audit trail (owners, admins and viewers): kind calls (the Decision log: each call's release, environment, Application and key, reference, answers, confidence, tokens, latency, seal and serving deployment), changes (the Change history: versions, deployments, approvals with approver and requester, settings and access) or evidence (one Decision's evidence pack: a zip with a PDF summary, the period's calls and changes, Evaluations, seals and Definition sources). Filter by period (from inclusive, to exclusive; ISO dates), Decision and environments. includePayloads adds each call's input and the state sent to the model where still stored ("no longer stored" past retention). A small export is ready at once with a downloadUrl (a signed link valid for an hour: fetch it or give it to the person); a larger one is queued, the person is notified when it is ready, and get_export returns its link. Every export is recorded in the audit trail.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `kind` | `string`, one of `calls`, `changes`, `evidence` | Required |  |
| `format` | `string`, one of `csv`, `json`, `zip` | Required | csv or json for calls and changes; zip for an evidence pack |
| `from` | `string` | Optional | Start of the period, ISO 8601 (inclusive) |
| `to` | `string` | Optional | End of the period, ISO 8601 (exclusive) |
| `decision` | `string` | Optional | A Decision's slug; required for an evidence pack |
| `environments` | `array of string` | Optional | Environment slugs; "sandbox" for Sandbox runs |
| `includePayloads` | `boolean` | Optional |  |

```json
{
  "name": "export_audit",
  "arguments": {
    "org": "acme",
    "kind": "calls",
    "format": "csv"
  }
}
```

### get_export

**Get an export.** Read access. Reads.

An export by id (owners, admins and viewers): its status (queued, running, ready, failed, expired) and, once ready, a fresh downloadUrl valid for an hour. Without an id, the organisation's latest exports, or with decision (a slug) the latest narrowed to that Decision.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `id` | `string` | Optional |  |
| `decision` | `string` | Optional |  |

```json
{ "name": "get_export", "arguments": { "org": "acme" } }
```

### list_decisions

**List Decisions.** Read access. Reads.

Decisions in an organisation: slug, name, description and identifier (org/slug).

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |

```json
{ "name": "list_decisions", "arguments": { "org": "acme" } }
```

### get_decision

**Get a Decision.** Read access. Reads.

One Decision: its YAML-first v3 draft (state_schema, optional context and native TypeSafe questions), its versions and deployments.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |

```json
{
  "name": "get_decision",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### list_runs

**List runs.** Read access. Reads.

Recent runs of a decision, newest first. Served runs carry an environment and a role (primary, variant, shadow); sandbox runs say 'sandbox'.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `environment` | `string` | Optional | Only this environment, e.g. production |
| `reference` | `string` | Optional | Only calls with this reference id or correlation id; a caller's subject is recorded as its reference |
| `limit` | `integer`, 1 to 200, default 50 | Optional |  |

```json
{
  "name": "list_runs",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### get_run

**Get a run.** Read access. Reads.

One run in full: its release (version) and environment, the deployment that served it (servedBy: who asked for it and who approved it), the input, the state sent to TypeSafe and its native answers. When the input isn't kept (the Decision doesn't keep inputs) or the plan's retention has expired it, notStored is the sentence to relay; the answers stay.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `runId` | `string` | Required |  |

```json
{
  "name": "get_run",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "runId": "<runId>"
  }
}
```

### performance

**Show performance.** Read access. Reads.

How a decision is doing in an environment over a window: run counts, errors, latency p50/p95, cost, answers per question, split by version and role. The analyst's view.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `environment` | `string`, default "production" | Optional |  |
| `hours` | `number`, 1 to 2,160, default 168 | Optional | Window ending now |

```json
{
  "name": "performance",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### list_test_runs

**List test runs.** Read access. Reads.

Immutable Test runs for a decision, newest first, including whether each has been evaluated.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |

```json
{
  "name": "list_test_runs",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### list_evaluations

**List Evaluations.** Read access. Reads.

Deterministic analyses of a decision's immutable Test runs, newest first, including agreement per question and the source Test run.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |

```json
{
  "name": "list_evaluations",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### get_evaluation

**Get an Evaluation.** Read access. Reads.

One Evaluation with every case: expected against actual, agreement per question, coverage (the questions no case checks) and calibration: over the yes/no and choice answers the cases expect, the Brier score, the expected calibration error and a reliability table (for each band of stated probability, how often the answers were right). Calibration is rough below 50 answers, and not_available when the model gave no probability for each possible answer.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `evaluationId` | `string` | Required |  |

```json
{
  "name": "get_evaluation",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "evaluationId": "<evaluationId>"
  }
}
```

### list_cases

**List test cases.** Read access. Reads.

Confirmed and proposed Test set cases with expected answers.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |

```json
{
  "name": "list_cases",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### list_test_sets

**List Test sets.** Read access. Reads.

Lists the named Test sets available for evaluation, including Core and their case counts.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |

```json
{
  "name": "list_test_sets",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### list_datasets

**List Datasets.** Read access. Reads.

Datasets of a Decision (inputs with no expected answers: uploaded, or replayed from production) and its Comparisons with their headline numbers.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |

```json
{
  "name": "list_datasets",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### get_comparison

**Get a Comparison.** Read access. Reads.

One Comparison: status and progress of both sides; cost: the cost difference in words and numbers (cost per call A vs B, total cost, tokens in/out and p50/p95 latency, over the rows both sides answered) with a projection at the Decision's last 30 days of production traffic when it has any; the summary as numbers (per-question distributions, transitions from A to B; questionsCompared is 'different' when the sides share no question, and then the answers are not compared); for a replay of production calls, replay: how many recorded calls could not be replayed and why (message is the sentence to relay); and a page of rows. filter: differs (default), all, errors, not_accepted; question narrows differs to one question; cursor continues.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `comparisonId` | `string` | Required |  |
| `filter` | `string`, one of `differs`, `all`, `errors`, `not_accepted` | Optional |  |
| `question` | `string` | Optional |  |
| `cursor` | `integer` | Optional |  |
| `limit` | `integer`, 1 to 50 | Optional |  |

```json
{
  "name": "get_comparison",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "comparisonId": "<comparisonId>"
  }
}
```

### estimate_comparison

**Estimate a Comparison.** Read access. Reads.

What comparing A and B over a Dataset would involve, without running anything: its rows and unique inputs, the calls each side would make after reusing answers, the tokens and how long it would take. It also says whether the Comparison would be refused, and why.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `datasetId` | `string` | Required |  |
| `a` | `{ "version": integer } or { "draft": true } or { "environment": string } or { "recorded": true }` | Required | One side: {"version": N}, {"draft": true}, {"environment": "production"} (the release live there) or {"recorded": true} (production's recorded answers; replay Datasets only) |
| `b` | `{ "version": integer } or { "draft": true } or { "environment": string } or { "recorded": true }` | Required | One side: {"version": N}, {"draft": true}, {"environment": "production"} (the release live there) or {"recorded": true} (production's recorded answers; replay Datasets only) |
| `sample` | `integer`, at least 1 | Optional |  |
| `maxCalls` | `integer`, at least 1 | Optional |  |
| `fresh` | `boolean` | Optional |  |

```json
{
  "name": "estimate_comparison",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "datasetId": "<datasetId>",
    "a": {
      "version": 3
    },
    "b": {
      "draft": true
    }
  }
}
```

### review_draft

**Review the draft.** Read access. Reads.

Reviews the saved draft with TypeFuse's rule checks, which write nothing: copies of a question that should be one question asked for each item, unknown backticked paths, required input nothing refers to, lists without maxItems, identical questions and fixed policy text sent as input, plus the compiler's advice. Each finding has a path and a message; a mechanical one also has a fix with its id, a unified diff and its effect (whether it compiles, the semantic release of the change and of the next release, and the cost per call before and after). Fix findings yourself, or apply a fix by its id with apply_fix (Full access). Returns draftHash: pass it to apply_fix.

With triage: true it also runs the assistant review (Assistant review in the app); reviewing again asks only about the questions that changed. Its findings (triage.findings, at or above each check's threshold, and triage.worthALook) each have a probability, a path and howToFix. Fix them yourself from howToFix, and ask suggest_fix only when you are stuck. The assistant review is for members who edit: for a viewer, or a read-only token or connection, triage.status is not_permitted and only the rule checks run.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `triage` | `boolean` | Optional | Also run the assistant review (one TypeSafe call; unchanged questions are not re-asked) |

```json
{
  "name": "review_draft",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### model_status

**Show model status.** Read access. Reads.

Where a Decision's model stands: the model of the release live in production (else the latest release), a newer model to try (newer), when its model retires once a date is announced (retirement), and the latest trial of the newer model (latestTrial: an outcome of stayed means the person chose to stay). With trialId, also that trial in full: agreement on each model (baseline is the published model, candidate the one tried) and the cases that answered differently, each with both models' answers, what it expects and which model the person said was right. Start a trial with start_model_trial (a full-scope token).

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `trialId` | `string` | Optional | A trial's id, to read that trial in full |

```json
{
  "name": "model_status",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

## Run

With Run or Full access.

### compile_draft

**Compile the draft.** Run access. Reads.

Checks the draft compiles; returns errors to fix in the definition, plus an estimate (tokens and cost per call and per item at maxItems) and advice on the Decision's shape (use_each, static_text_in_input, large_state, …) to act on before publishing.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |

```json
{
  "name": "compile_draft",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### run_draft

**Run the draft.** Run access. Writes.

Runs the draft once on dynamic state matching state_schema. Returns native TypeSafe answers (a list in element order for an each question), tokens, cost and itemCount.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `input` | `string or array or object` | Required |  |

```json
{
  "name": "run_draft",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "input": {
      "request": "The kettle arrived with a cracked lid.",
      "days_since_delivery": 3
    }
  }
}
```

### run_tests

**Run the Test set.** Run access. Writes.

Executes selected Test-set evidence against the draft or an immutable version, records a raw Test run and its basic Evaluation (exact agreement).

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `versionNumber` | `integer`, at least 1 | Optional | The version's number, as publish_version returned it (also accepted as version) |
| `version` | `integer`, at least 1 | Optional | Another name for versionNumber; give one of them |
| `include` | `string`, default "confirmed", one of `confirmed`, `all` | Optional |  |
| `batchSize` | `integer`, 1 to 10, default 1 | Optional |  |
| `testSetIds` | `array of string` | Optional |  |
| `expansion` | `string`, one of `repeat`, `shared` | Optional | Draft runs only: how each questions are sent. shared sends the wording once; evaluate it against repeat before relying on it. |

```json
{
  "name": "run_tests",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### evaluate

**Evaluate a version.** Run access. Writes.

Deterministically analyses one immutable Test run; it never calls the provider again. Agreement compares only the answers a case expects; coverage lists the questions no case checks; calibration measures whether the stated probabilities match how often the yes/no and choice answers were right.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `testRunId` | `string` | Required |  |

```json
{
  "name": "evaluate",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "testRunId": "<testRunId>"
  }
}
```

### compare

**Compare two versions.** Run access. Writes.

Starts a Comparison of A and B over a Dataset or, with replay, over a fresh snapshot of recorded production calls. A replay needs Full access and an owner or admin; with Run access, compare over a Dataset that already exists. maxCalls is optional: the most model calls both sides together may make (rows beyond it are not run); without it, every chosen row runs. estimate_comparison shows what it would run. It runs in the background; read it with get_comparison.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `a` | `{ "version": integer } or { "draft": true } or { "environment": string } or { "recorded": true }` | Required | One side: {"version": N}, {"draft": true}, {"environment": "production"} (the release live there) or {"recorded": true} (production's recorded answers; replay Datasets only) |
| `b` | `{ "version": integer } or { "draft": true } or { "environment": string } or { "recorded": true }` | Required | One side: {"version": N}, {"draft": true}, {"environment": "production"} (the release live there) or {"recorded": true} (production's recorded answers; replay Datasets only) |
| `datasetId` | `string` | Optional |  |
| `replay` | `object` | Optional | Snapshot recorded production calls as the Dataset instead of datasetId |
| `replay.environment` | `string` | Optional |  |
| `replay.days` | `integer`, 1 to 365 | Optional |  |
| `replay.limit` | `integer`, at least 1 | Optional |  |
| `sample` | `integer`, at least 1 | Optional |  |
| `maxCalls` | `integer`, at least 1 | Optional |  |
| `fresh` | `boolean` | Optional |  |

```json
{
  "name": "compare",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "a": {
      "version": 3
    },
    "b": {
      "draft": true
    }
  }
}
```

## Full

With Full access.

### create_decision

**Create a Decision.** Full access. Writes.

Creates a decision with its first draft. Slug is lowercase with hyphens; the Decision's identifier is org/slug.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `name` | `string` | Required |  |
| `description` | `string` | Optional |  |
| `definition` | `object` | Required | A Definition v3 object: { format: 3, model, state_schema, context?, questions }. Questions use native TypeSafe noul, choice or score shapes. A question may add each: input.<list> (or context.<list>) to be asked once per element of a declared array with maxItems, referring to the element as `item`; its answer is a list in element order. Never number copies of a question. |

```json
{
  "name": "create_decision",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "name": "Refunds",
    "definition": {
      "format": 3,
      "model": "jev-1.13.0",
      "state_schema": {
        "type": "object",
        "properties": {
          "request": {
            "type": "string",
            "description": "What the customer wrote"
          },
          "days_since_delivery": {
            "type": "number"
          }
        },
        "required": [
          "request",
          "days_since_delivery"
        ],
        "additionalProperties": false
      },
      "context": {
        "policy": "Refund within 30 days for unused items or anything defective."
      },
      "questions": {
        "eligible": {
          "type": "noul",
          "instructions": "Is this request eligible for a refund under the policy?",
          "criteria": {
            "true": "Within 30 days and unused, or defective.",
            "false": "Outside 30 days with no defect, or used."
          }
        },
        "reason": {
          "type": "choice",
          "instructions": "Which policy rule decides this request?",
          "criteria": {
            "within_window": "Inside 30 days and unused.",
            "defective": "Faulty or damaged in transit.",
            "unclear": "The supplied facts do not settle it."
          }
        }
      }
    }
  }
}
```

### update_draft

**Update the draft.** Full access. Replaces.

Replaces the draft definition. Compile afterwards.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `definition` | `object` | Required | A Definition v3 object: { format: 3, model, state_schema, context?, questions }. Questions use native TypeSafe noul, choice or score shapes. A question may add each: input.<list> (or context.<list>) to be asked once per element of a declared array with maxItems, referring to the element as `item`; its answer is a list in element order. Never number copies of a question. |

```json
{
  "name": "update_draft",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "definition": {
      "format": 3,
      "model": "jev-1.13.0",
      "state_schema": {
        "type": "object",
        "properties": {
          "request": {
            "type": "string",
            "description": "What the customer wrote"
          },
          "days_since_delivery": {
            "type": "number"
          }
        },
        "required": [
          "request",
          "days_since_delivery"
        ],
        "additionalProperties": false
      },
      "context": {
        "policy": "Refund within 30 days for unused items or anything defective."
      },
      "questions": {
        "eligible": {
          "type": "noul",
          "instructions": "Is this request eligible for a refund under the policy?",
          "criteria": {
            "true": "Within 30 days and unused, or defective.",
            "false": "Outside 30 days with no defect, or used."
          }
        },
        "reason": {
          "type": "choice",
          "instructions": "Which policy rule decides this request?",
          "criteria": {
            "within_window": "Inside 30 days and unused.",
            "defective": "Faulty or damaged in transit.",
            "unclear": "The supplied facts do not settle it."
          }
        }
      }
    }
  }
}
```

### apply_fix

**Apply a fix.** Full access. Replaces.

Applies one fix from review_draft to the saved draft as a single draft edit (the audit log records which fix). It never publishes or deploys; publish_version is a separate step. Pass the draftHash review_draft returned: if the draft changed since, it is refused (DRAFT_MOVED) and you review again. Returns the new draftHash, what was applied (its release type) and the fresh review.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `fixId` | `string` | Required |  |
| `draftHash` | `string` | Optional |  |

```json
{
  "name": "apply_fix",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "fixId": "<fixId>"
  }
}
```

### suggest_fix

**Suggest a fix.** Full access. Writes.

Asks TypeFuse's Definition assistant for a rewrite that fixes one finding of the assistant review (from review_draft with triage: true; pass the finding's id, such as two_things:questions.clear). Fixing a finding yourself from its howToFix is usually quicker. The rewrite touches only the finding's paths, must compile, and is checked by asking the same review question of the rewritten question. Returns the unified diff, its effect (whether it compiles, the release, the cost per call before and after), the verification (before, after, threshold and status) and, once verified, a suggestion id for accept_suggestion. The draft changes only when the suggestion is accepted. Refused with FAIR_USE_REACHED when the organisation has used what its plan includes of the Definition assistant for now; `details.resetsAt` says when it can be asked again.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `findingId` | `string` | Required |  |
| `draftHash` | `string` | Optional |  |
| `retryOf` | `string` | Optional | Try again: the id of a Not verified suggestion for this finding; its verification is fed back. At most 2 rewrites per finding per draft. |

```json
{
  "name": "suggest_fix",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "findingId": "<findingId>"
  }
}
```

### dismiss_finding

**Dismiss a finding.** Full access. Writes.

Records that a Review finding (from the rule checks or the assistant review) is not a problem, or not for now, by its finding id. The draft is unchanged. not_a_problem tells TypeFuse the check was wrong (how the checks are improved) and hides the finding on this Decision in the web app until the question or input it is about changes.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `findingId` | `string`, at most 500 characters | Required |  |
| `reason` | `string`, one of `not_a_problem`, `not_now` | Required |  |
| `probability` | `number`, 0 to 1 | Optional | The probability shown for an assistant review finding, when it was one |

```json
{
  "name": "dismiss_finding",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "findingId": "two_things:questions.reason",
    "reason": "not_a_problem"
  }
}
```

### accept_suggestion

**Accept a suggestion.** Full access. Replaces.

Accepts a verified suggestion from suggest_fix into the saved draft as one draft edit (the audit log records the suggestion, the review version and the model). Never publishes. Refused with DRAFT_MOVED if the draft changed since the suggestion was made.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `suggestionId` | `string` | Required |  |
| `draftHash` | `string` | Optional |  |

```json
{
  "name": "accept_suggestion",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "suggestionId": "<suggestionId>"
  }
}
```

### assist_draft

**Ask the assistant.** Full access. Writes.

Ask the assistant, as the app calls it: puts a goal for the saved draft to TypeFuse's Definition assistant, such as "also flag chargebacks", "make this cheaper" or "why does it say escalate so often?". It reads the Decision through the same read tools you have (never the inputs of recorded runs), works out what kind of goal it is (add_judgment, change_behaviour, reduce_cost, explain_behaviour, restructure or not_a_definition_change) and answers with at most one proposal: a draft change, written, compiled and checked, to accept with accept_suggestion, or one action, which accept_proposal runs as you. An agent can often do the same itself with the read tools and update_draft. Each goal can be asked at most twice for each draft (retryOf asks for another answer). Refused with FAIR_USE_REACHED when the organisation has used what its plan includes of the Definition assistant for now; `details.resetsAt` says when it can be asked again.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `goal` | `string`, 3 to 1,000 characters | Required |  |
| `draftHash` | `string` | Optional |  |
| `retryOf` | `string` | Optional | Try another: the id of the earlier answer to the same goal |

```json
{
  "name": "assist_draft",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "goal": "also flag chargebacks"
  }
}
```

### accept_proposal

**Accept a proposal.** Full access. Replaces.

Runs an action that assist_draft proposed, by its id, as you: the same tool, with your permissions. A proposed draft change is accepted with accept_suggestion instead. It never publishes or deploys.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `proposalId` | `string` | Required |  |

```json
{
  "name": "accept_proposal",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "proposalId": "<proposalId>"
  }
}
```

### add_case

**Add a test case.** Full access. Writes.

Adds a confirmed test case: dynamic state with its expected answers. For an each question, expect a list with one answer per element of the case's list (null for no expectation).

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `name` | `string` | Optional |  |
| `input` | `string or array or object` | Required |  |
| `expectedAnswers` | `object` | Optional | The expected answers by question name (also accepted as expected) |
| `expected` | `object` | Optional | Another name for expectedAnswers; give one of them |
| `note` | `string` | Optional |  |
| `testSetIds` | `array of string` | Optional |  |

```json
{
  "name": "add_case",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "input": {
      "request": "The kettle arrived with a cracked lid.",
      "days_since_delivery": 3
    }
  }
}
```

### create_test_set

**Create a Test set.** Full access. Writes.

Creates a named collection of reusable cases for a particular evaluation purpose.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `name` | `string` | Required |  |
| `description` | `string` | Optional |  |

```json
{
  "name": "create_test_set",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "name": "Damaged on arrival"
  }
}
```

### list_examples

**List Examples.** Full access. Reads.

Lists the worked examples stored separately from the Definition and Test set.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |

```json
{
  "name": "list_examples",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### add_example

**Add an Example.** Full access. Writes.

Adds a worked example. It documents intent but is not evaluation evidence until promoted. Unlike a test case, an Example answers every question: expectedAnswers needs one per question (a refusal is EXAMPLE_INVALID with the path of each missing answer).

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `name` | `string` | Required |  |
| `input` | `string or array or object` | Required |  |
| `expectedAnswers` | `object` | Optional | The expected answers by question name (also accepted as expected) |
| `expected` | `object` | Optional | Another name for expectedAnswers; give one of them |
| `note` | `string` | Optional |  |

```json
{
  "name": "add_example",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "name": "Cracked lid",
    "input": {
      "request": "The kettle arrived with a cracked lid.",
      "days_since_delivery": 3
    }
  }
}
```

### promote_example

**Promote an Example to a test case.** Full access. Writes.

Promotes a reviewed worked example into one or more named Test sets. When a case with the same input already exists, that case is added to the sets instead and keeps its own expected answers: the result says created: false.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `exampleId` | `string` | Required |  |
| `testSetIds` | `array of string` | Optional |  |

```json
{
  "name": "promote_example",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "exampleId": "<exampleId>"
  }
}
```

### propose_case_updates

**Propose test case updates.** Full access. Writes.

Proposes an update for every Test case or Example that no longer fits the current draft Definition (Fix with the assistant, in the app). Fields that were removed, and answers to questions that were removed, are dropped; obvious values are filled in and plainly renamed choice options mapped, all without a model. Only what is left (a new required field, an answer to a new question, an option whose meaning changed) is asked of TypeFuse's Definition assistant, which is refused with FAIR_USE_REACHED when it can't be asked for now (`details.resetsAt` says when it can be asked again). Every proposal fits the Definition. Returns the proposals (id, targetId, input, expectedAnswers and changes) and any cases it couldn't update, with the reason. Nothing changes until accept_case_update, and proposals last a day, for this draft only.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `kind` | `string`, one of `cases`, `examples` | Required | Test set cases (partial expected answers allowed) or Examples (one answer per question) |

```json
{
  "name": "propose_case_updates",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "kind": "cases"
  }
}
```

### accept_case_update

**Accept a test case update.** Full access. Replaces.

Accepts one proposal from propose_case_updates: saves exactly the proposed input and expected answers to that Test case or Example. Accepting is the confirmation, so a confirmed case stays confirmed; the audit log records that the assistant proposed it and you accepted it. Refused with PROPOSAL_UNAVAILABLE when it is gone or the draft changed.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `kind` | `string`, one of `cases`, `examples` | Required | Test set cases (partial expected answers allowed) or Examples (one answer per question) |
| `targetId` | `string` | Required | The case or Example id (the proposal's targetId) |
| `proposalId` | `string` | Required |  |

```json
{
  "name": "accept_case_update",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "kind": "cases",
    "targetId": "<targetId>",
    "proposalId": "<proposalId>"
  }
}
```

### publish_version

**Publish a version.** Full access. Replaces.

Publishes the draft as the next immutable version.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `label` | `string` | Optional |  |

```json
{
  "name": "publish_version",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### start_model_trial

**Start a model trial.** Full access. Writes.

Tries another model on a Decision: asks the Test set of the release live in production (or else the latest release) twice, once as published (the baseline) and once with only its model changed (the candidate), and returns both sides' agreement and the cases that answered differently. The draft is untouched. model defaults to the newer model that model_status names. Then decide each changed case with decide_trial_case, and finish with release_model_trial or stay_on_model. Only a newer, released model can be tried. Refusals: NOT_NEWER, SAME_MODEL, UNKNOWN_MODEL, MODEL_RETIRED, INVALID_MODEL, NO_RELEASE, NO_CASES and INVALID_CASES.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `model` | `string`, at most 64 characters | Optional | An exact model version such as jev-1.14.0; the newer model by default |

```json
{
  "name": "start_model_trial",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}
```

### decide_trial_case

**Decide a trial case.** Full access. Replaces.

Says which model answered a changed case of a model trial rightly: baseline (the published model) or candidate (the model tried). candidate also makes the case expect the new model's answers from now on. Ask the person when it isn't clear from the case; never decide every case one way to get past this step. Returns the trial with what is still undecided. Refused with CASE_CHANGED when the case's input was edited after the trial asked it (start a new trial), CASE_NOT_FOUND when it was removed, ALREADY_DECIDED once the trial is released or stayed.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `trialId` | `string` | Required |  |
| `caseId` | `string` | Required |  |
| `right` | `string`, one of `baseline`, `candidate` | Required |  |

```json
{
  "name": "decide_trial_case",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "trialId": "<trialId>",
    "caseId": "<caseId>",
    "right": "baseline"
  }
}
```

### release_model_trial

**Release the trial's model.** Full access. Replaces.

Publishes the trial's model: the latest release with only its model changed, as the next version (a minor release). Every changed case must be decided first (CASES_UNDECIDED). Refused with TRIAL_OUTDATED when a release published since changed the Decision (try the model again on it) and ALREADY_ON_MODEL when the latest release already uses it. The draft follows when it matched the latest release (draftMoved); otherwise it is left as it was. Deploy the new version with deploy_version as usual.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `trialId` | `string` | Required |  |

```json
{
  "name": "release_model_trial",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "trialId": "<trialId>"
  }
}
```

### stay_on_model

**Stay on the current model.** Full access. Writes.

Keeps the Decision on its current model after a trial; the choice is kept, so the Decision's Summary stops offering the newer model until something changes.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `trialId` | `string` | Required |  |

```json
{
  "name": "stay_on_model",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "trialId": "<trialId>"
  }
}
```

### deploy_version

**Deploy a version.** Full access. Replaces.

Deploys a version to an environment and says what happened and why (outcome), with any warnings and appUrl (the Decision's Deployments page). A production environment holds a deploy an agent asks for (approval "agent", the default) until a person approves it with one click in the app: the result has status pending and approveUrl, the page to give the person you act for, who may approve it themselves. Where approval is "every", a person approves every deploy (an owner or admin other than the one who asked, or the one who asked when they are the only owner or admin); where the environment requires a second person, never the person you act for. You can't approve. A deploy the organisation's plan doesn't include is refused with PLAN_LIMIT. Asking again for a release that is already waiting returns that request. Where the organisation requires a passing Test set (production environments by default), a release whose latest Evaluation didn't agree on every case is refused with PASSING_TESTS_REQUIRED: evaluate it and fix what fails first. scheduledFor (optional, an ISO time) deploys it later: at least a minute and at most a year ahead.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `environment` | `string` | Required |  |
| `versionNumber` | `integer`, at least 1 | Optional | The version's number, as publish_version returned it (also accepted as version) |
| `version` | `integer`, at least 1 | Optional | Another name for versionNumber; give one of them |
| `note` | `string` | Optional |  |
| `scheduledFor` | `string`, a date and time (ISO 8601) | Optional |  |

```json
{
  "name": "deploy_version",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "environment": "production"
  }
}
```

### check_deploy

**Check a deployment.** Full access. Reads.

What deploying a version to an environment would do, without doing it: whether it waits for approval, a request for it already waiting, the release's evidence (its latest Evaluation) and the warnings (no Evaluation or a failing one, production before test). It refuses what the deploy would refuse, with the same error: a plan that does not deploy, or PASSING_TESTS_REQUIRED where the organisation requires a passing Test set (every case agreed in the release's latest Evaluation) and the release has none; details.evaluations links to its Evaluations.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `environment` | `string` | Required |  |
| `versionNumber` | `integer`, at least 1 | Optional | The version's number, as publish_version returned it (also accepted as version) |
| `version` | `integer`, at least 1 | Optional | Another name for versionNumber; give one of them |

```json
{
  "name": "check_deploy",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "environment": "production"
  }
}
```

### upload_dataset

**Upload a Dataset.** Full access. Writes.

Uploads a Dataset: inputs (JSON objects, one per row) with no expected answers, to compare two releases over. Rows that are not JSON objects are refused and listed by position.

**Inputs**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required | Organisation slug |
| `slug` | `string` | Required | Decision slug |
| `name` | `string`, at least 1 character | Required |  |
| `rows` | `array`, at least 1 item | Required |  |

```json
{
  "name": "upload_dataset",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "name": "October returns",
    "rows": [
      {
        "request": "The kettle arrived with a cracked lid.",
        "days_since_delivery": 3
      }
    ]
  }
}
```
