Skip to content

Reference

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.

Calling deployed Decisions

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

search_decisions

Search DecisionsCall permissionReads

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

  • judgementRequiredstring1 to 300 characters
    The kind of judgement you need, in plain words.
  • domainOptionalstringat most 60 characters
    Optional: the area, such as payments or support.
  • item_typeOptionalstringat most 60 characters
    Optional: what is being judged, such as card_transaction.
  • limitOptionalinteger1 to 20
  • correlation_idOptionalstring
    Optional: your own id for this piece of work.

Answer

  • notestring
  • searchIdstring
    Pass it as discovery_id when you describe or call a match.
  • outcomestring
    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).One of matched, no_match, nothing_offered, filtered
  • matchesarray of { "decision": string, "call": { "tool": "call_decision", "decision": string, "environment": string } }
  • messagestring
Example call
{
  "name": "search_decisions",
  "arguments": {
    "judgement": "whether a returned order can be refunded"
  }
}

describe_decision

Describe a DecisionCall permissionReads

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

  • decisionRequiredstring1 to 200 characters
    The Decision's identifier from a search match, such as acme/refund-eligibility.
  • environmentOptionalstring1 to 60 characters
    Optional: the environment to use, from the match's deployments. Without it, the match's call.environment is used.
  • discovery_idOptionalstringat most 80 characters
    The searchId of the search that found this Decision.

Answer

  • notestring
  • decisionstring
  • namestring
  • purposestring or null
  • whenToUsestring or null
  • whenNotToUsestring or null
  • exampleRequestsarray of string
  • environmentstring
  • releasestring
  • versioninteger
  • deploymentsarray of { "environment": string, "release": string, "version": integer }
  • inputSchemaany JSON value
    The input a call takes: the release's state_schema.
  • answersSchemaobject
    What each answer means, by question id.
  • callobject
  • call.tool"call_decision"
  • call.decisionstring
  • call.environmentstring
Example call
{
  "name": "describe_decision",
  "arguments": {
    "decision": "acme/refunds"
  }
}

call_decision

Call a DecisionCall permissionWrites

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

  • decisionRequiredstring1 to 200 characters
    The Decision's identifier from a search match, such as acme/refund-eligibility.
  • inputRequiredobject or array or string
    The item's details, matching the Decision's inputSchema.
  • environmentOptionalstring1 to 60 characters
    Optional: the environment to use, from the match's deployments. Without it, the match's call.environment is used.
  • referenceOptionalobject
    Optional: what this call is about in your terms, such as { type: "order", id: "8812" }.
  • reference.typeRequiredstring1 to 40 characters
  • reference.idRequiredstring1 to 200 characters
  • correlation_idOptionalstring
    Optional: ties several calls together.
  • discovery_idOptionalstringat most 80 characters
    The searchId of the search that found this Decision.
  • idempotency_keyOptionalstring1 to 200 characters
    Optional: the same key answers once; a retry gets the first answer.

Answer

  • decisionstring
  • environmentstring
  • releasestring
    The semantic release that answered.
  • versioninteger
    The exact published version, for replay.
  • runIdstring
    The audit reference for this call.
  • answersobject
    Native answers by question id; a per-item question answers a list, one per element in order.
  • readingstring
    Each answer and its confidence in words (per-item lists show the first 10). It states the answers; it never says what to do.
Example call
{
  "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 organisationsRead accessReads

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

  • skill_versionOptionalstringat most 40 characters
    The installed TypeFuse skill's version, as its SKILL.md names it
Example call
{ "name": "list_organisations", "arguments": {} }

notifications

Show what is waitingRead accessReads

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.

Inputs

It takes no inputs.

Example call
{ "name": "notifications", "arguments": {} }

export_audit

Export the audit trailRead accessWrites

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

  • orgRequiredstring
    Organisation slug
  • kindRequiredstring
    One of calls, changes, evidence
  • formatRequiredstring
    csv or json for calls and changes; zip for an evidence packOne of csv, json, zip
  • fromOptionalstring
    Start of the period, ISO 8601 (inclusive)
  • toOptionalstring
    End of the period, ISO 8601 (exclusive)
  • decisionOptionalstring
    A Decision's slug; required for an evidence pack
  • environmentsOptionalarray of string
    Environment slugs; "sandbox" for Sandbox runs
  • includePayloadsOptionalboolean
Example call
{
  "name": "export_audit",
  "arguments": {
    "org": "acme",
    "kind": "calls",
    "format": "csv"
  }
}

get_export

Get an exportRead accessReads

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

  • orgRequiredstring
    Organisation slug
  • idOptionalstring
  • decisionOptionalstring
Example call
{ "name": "get_export", "arguments": { "org": "acme" } }

list_decisions

List DecisionsRead accessReads

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

Inputs

  • orgRequiredstring
    Organisation slug
Example call
{ "name": "list_decisions", "arguments": { "org": "acme" } }

get_decision

Get a DecisionRead accessReads

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

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
Example call
{
  "name": "get_decision",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

list_runs

List runsRead accessReads

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

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • environmentOptionalstring
    Only this environment, e.g. production
  • referenceOptionalstring
    Only calls with this reference id or correlation id; a caller's subject is recorded as its reference
  • limitOptionalinteger1 to 200default 50
Example call
{
  "name": "list_runs",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

get_run

Get a runRead accessReads

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • runIdRequiredstring
Example call
{
  "name": "get_run",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "runId": "<runId>"
  }
}

performance

Show performanceRead accessReads

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • environmentOptionalstringdefault "production"
  • hoursOptionalnumber1 to 2,160default 168
    Window ending now
Example call
{
  "name": "performance",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

list_test_runs

List test runsRead accessReads

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

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
Example call
{
  "name": "list_test_runs",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

list_evaluations

List EvaluationsRead accessReads

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

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
Example call
{
  "name": "list_evaluations",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

get_evaluation

Get an EvaluationRead accessReads

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • evaluationIdRequiredstring
Example call
{
  "name": "get_evaluation",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "evaluationId": "<evaluationId>"
  }
}

list_cases

List test casesRead accessReads

Confirmed and proposed Test set cases with expected answers.

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
Example call
{
  "name": "list_cases",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

list_test_sets

List Test setsRead accessReads

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

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
Example call
{
  "name": "list_test_sets",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

list_datasets

List DatasetsRead accessReads

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

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
Example call
{
  "name": "list_datasets",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

get_comparison

Get a ComparisonRead accessReads

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • comparisonIdRequiredstring
  • filterOptionalstring
    One of differs, all, errors, not_accepted
  • questionOptionalstring
  • cursorOptionalinteger
  • limitOptionalinteger1 to 50
Example call
{
  "name": "get_comparison",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "comparisonId": "<comparisonId>"
  }
}

estimate_comparison

Estimate a ComparisonRead accessReads

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • datasetIdRequiredstring
  • aRequired{ "version": integer } or { "draft": true } or { "environment": string } or { "recorded": true }
    One side: {"version": N}, {"draft": true}, {"environment": "production"} (the release live there) or {"recorded": true} (production's recorded answers; replay Datasets only)
  • bRequired{ "version": integer } or { "draft": true } or { "environment": string } or { "recorded": true }
    One side: {"version": N}, {"draft": true}, {"environment": "production"} (the release live there) or {"recorded": true} (production's recorded answers; replay Datasets only)
  • sampleOptionalintegerat least 1
  • maxCallsOptionalintegerat least 1
  • freshOptionalboolean
Example call
{
  "name": "estimate_comparison",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "datasetId": "<datasetId>",
    "a": {
      "version": 3
    },
    "b": {
      "draft": true
    }
  }
}

review_draft

Review the draftRead accessReads

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • triageOptionalboolean
    Also run the assistant review (one TypeSafe call; unchanged questions are not re-asked)
Example call
{
  "name": "review_draft",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

model_status

Show model statusRead accessReads

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • trialIdOptionalstring
    A trial's id, to read that trial in full
Example call
{
  "name": "model_status",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

Run

With Run or Full access.

compile_draft

Compile the draftRun accessReads

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
Example call
{
  "name": "compile_draft",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

run_draft

Run the draftRun accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • inputRequiredstring or array or object
Example call
{
  "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 setRun accessWrites

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

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • versionNumberOptionalintegerat least 1
    The version's number, as publish_version returned it (also accepted as version)
  • versionOptionalintegerat least 1
    Another name for versionNumber; give one of them
  • includeOptionalstringdefault "confirmed"
    One of confirmed, all
  • batchSizeOptionalinteger1 to 10default 1
  • testSetIdsOptionalarray of string
  • expansionOptionalstring
    Draft runs only: how each questions are sent. shared sends the wording once; evaluate it against repeat before relying on it.One of repeat, shared
Example call
{
  "name": "run_tests",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

evaluate

Evaluate a versionRun accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • testRunIdRequiredstring
Example call
{
  "name": "evaluate",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "testRunId": "<testRunId>"
  }
}

compare

Compare two versionsRun accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • aRequired{ "version": integer } or { "draft": true } or { "environment": string } or { "recorded": true }
    One side: {"version": N}, {"draft": true}, {"environment": "production"} (the release live there) or {"recorded": true} (production's recorded answers; replay Datasets only)
  • bRequired{ "version": integer } or { "draft": true } or { "environment": string } or { "recorded": true }
    One side: {"version": N}, {"draft": true}, {"environment": "production"} (the release live there) or {"recorded": true} (production's recorded answers; replay Datasets only)
  • datasetIdOptionalstring
  • replayOptionalobject
    Snapshot recorded production calls as the Dataset instead of datasetId
  • replay.environmentOptionalstring
  • replay.daysOptionalinteger1 to 365
  • replay.limitOptionalintegerat least 1
  • sampleOptionalintegerat least 1
  • maxCallsOptionalintegerat least 1
  • freshOptionalboolean
Example call
{
  "name": "compare",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "a": {
      "version": 3
    },
    "b": {
      "draft": true
    }
  }
}

Full

With Full access.

create_decision

Create a DecisionFull accessWrites

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

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • nameRequiredstring
  • descriptionOptionalstring
  • definitionRequiredobject
    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.
Example call
{
  "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 draftFull accessReplaces

Replaces the draft definition. Compile afterwards.

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • definitionRequiredobject
    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.
Example call
{
  "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 fixFull accessReplaces

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • fixIdRequiredstring
  • draftHashOptionalstring
Example call
{
  "name": "apply_fix",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "fixId": "<fixId>"
  }
}

suggest_fix

Suggest a fixFull accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • findingIdRequiredstring
  • draftHashOptionalstring
  • retryOfOptionalstring
    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.
Example call
{
  "name": "suggest_fix",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "findingId": "<findingId>"
  }
}

dismiss_finding

Dismiss a findingFull accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • findingIdRequiredstringat most 500 characters
  • reasonRequiredstring
    One of not_a_problem, not_now
  • probabilityOptionalnumber0 to 1
    The probability shown for an assistant review finding, when it was one
Example call
{
  "name": "dismiss_finding",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "findingId": "two_things:questions.reason",
    "reason": "not_a_problem"
  }
}

accept_suggestion

Accept a suggestionFull accessReplaces

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • suggestionIdRequiredstring
  • draftHashOptionalstring
Example call
{
  "name": "accept_suggestion",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "suggestionId": "<suggestionId>"
  }
}

assist_draft

Ask the assistantFull accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • goalRequiredstring3 to 1,000 characters
  • draftHashOptionalstring
  • retryOfOptionalstring
    Try another: the id of the earlier answer to the same goal
Example call
{
  "name": "assist_draft",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "goal": "also flag chargebacks"
  }
}

accept_proposal

Accept a proposalFull accessReplaces

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • proposalIdRequiredstring
Example call
{
  "name": "accept_proposal",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "proposalId": "<proposalId>"
  }
}

add_case

Add a test caseFull accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • nameOptionalstring
  • inputRequiredstring or array or object
  • expectedAnswersOptionalobject
    The expected answers by question name (also accepted as expected)
  • expectedOptionalobject
    Another name for expectedAnswers; give one of them
  • noteOptionalstring
  • testSetIdsOptionalarray of string
Example call
{
  "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 setFull accessWrites

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

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • nameRequiredstring
  • descriptionOptionalstring
Example call
{
  "name": "create_test_set",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "name": "Damaged on arrival"
  }
}

list_examples

List ExamplesFull accessReads

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

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
Example call
{
  "name": "list_examples",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

add_example

Add an ExampleFull accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • nameRequiredstring
  • inputRequiredstring or array or object
  • expectedAnswersOptionalobject
    The expected answers by question name (also accepted as expected)
  • expectedOptionalobject
    Another name for expectedAnswers; give one of them
  • noteOptionalstring
Example call
{
  "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 caseFull accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • exampleIdRequiredstring
  • testSetIdsOptionalarray of string
Example call
{
  "name": "promote_example",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "exampleId": "<exampleId>"
  }
}

propose_case_updates

Propose test case updatesFull accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • kindRequiredstring
    Test set cases (partial expected answers allowed) or Examples (one answer per question)One of cases, examples
Example call
{
  "name": "propose_case_updates",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "kind": "cases"
  }
}

accept_case_update

Accept a test case updateFull accessReplaces

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • kindRequiredstring
    Test set cases (partial expected answers allowed) or Examples (one answer per question)One of cases, examples
  • targetIdRequiredstring
    The case or Example id (the proposal's targetId)
  • proposalIdRequiredstring
Example call
{
  "name": "accept_case_update",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "kind": "cases",
    "targetId": "<targetId>",
    "proposalId": "<proposalId>"
  }
}

publish_version

Publish a versionFull accessReplaces

Publishes the draft as the next immutable version.

Inputs

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • labelOptionalstring
Example call
{
  "name": "publish_version",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

start_model_trial

Start a model trialFull accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • modelOptionalstringat most 64 characters
    An exact model version such as jev-1.14.0; the newer model by default
Example call
{
  "name": "start_model_trial",
  "arguments": {
    "org": "acme",
    "slug": "refunds"
  }
}

decide_trial_case

Decide a trial caseFull accessReplaces

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • trialIdRequiredstring
  • caseIdRequiredstring
  • rightRequiredstring
    One of baseline, candidate
Example call
{
  "name": "decide_trial_case",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "trialId": "<trialId>",
    "caseId": "<caseId>",
    "right": "baseline"
  }
}

release_model_trial

Release the trial's modelFull accessReplaces

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • trialIdRequiredstring
Example call
{
  "name": "release_model_trial",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "trialId": "<trialId>"
  }
}

stay_on_model

Stay on the current modelFull accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • trialIdRequiredstring
Example call
{
  "name": "stay_on_model",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "trialId": "<trialId>"
  }
}

deploy_version

Deploy a versionFull accessReplaces

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • environmentRequiredstring
  • versionNumberOptionalintegerat least 1
    The version's number, as publish_version returned it (also accepted as version)
  • versionOptionalintegerat least 1
    Another name for versionNumber; give one of them
  • noteOptionalstring
  • scheduledForOptionalstringa date and time (ISO 8601)
Example call
{
  "name": "deploy_version",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "environment": "production"
  }
}

check_deploy

Check a deploymentFull accessReads

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • environmentRequiredstring
  • versionNumberOptionalintegerat least 1
    The version's number, as publish_version returned it (also accepted as version)
  • versionOptionalintegerat least 1
    Another name for versionNumber; give one of them
Example call
{
  "name": "check_deploy",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "environment": "production"
  }
}

upload_dataset

Upload a DatasetFull accessWrites

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

  • orgRequiredstring
    Organisation slug
  • slugRequiredstring
    Decision slug
  • nameRequiredstringat least 1 character
  • rowsRequiredarrayat least 1 item
Example call
{
  "name": "upload_dataset",
  "arguments": {
    "org": "acme",
    "slug": "refunds",
    "name": "October returns",
    "rows": [
      {
        "request": "The kettle arrived with a cracked lid.",
        "days_since_delivery": 3
      }
    ]
  }
}