MCP tools

Felspar's remote MCP server - connection, the four agent tools and the seven authoring tools, with inputs, results and errors.

Connection

The credential is checked on every message, including initialize. A missing, unknown or revoked key answers 401, so a client fails to connect rather than failing each tool.

Agents and people see different tools, never each other’s. An agent key gets the four agent tools. A person’s sign-in gets the seven authoring tools. Each tool calls the same REST route as an HTTP client would, with the caller’s own credential, so access, release choice and receipts are identical.

Errors

A refused or failed call is a tool result with isError: true, never a decision. Refusals carry the same error, path, issues[] and fix as the REST API, so the model can read and correct them. Arguments that don’t match a tool’s schema return invalid_arguments with each issue’s path and problem.

Tool hints

Every tool declares destructiveHint: false and openWorldHint: false: nothing deletes, overwrites or reaches outside your workspace. Tools that record something new (add_current_version, propose_pack, get_job_decision, check_output) declare readOnlyHint: false; the rest are read-only.

Agent tools

list_jobs

List the jobs this agent key may run, so an agent that wasn’t told which job to run can pick one. No inputs. Each job comes from its released pack:

A job is listed only when get_job_requirements would serve it to this key: it is registered for the job, followed on Latest or pinned, with a live release. An agent picks the job whose purpose and use-when fit the task and whose not-for doesn’t; when none fits, it says so instead of forcing one. Over REST, GET /v0/jobs returns the job IDs.

get_job_requirements

Read what a company job needs before deciding: its purpose and subject, its questions, what each means (quoted from the policy), what evidence counts, the possible answers and outcomes, and request limits. Call it once per job; it changes only when a new version is released.

Returns the job’s brief from the release this agent uses:

• purpose, useWhen, notFor and owner: what the job is for, quoted, first;
• subject: what each case is about (type, quoted definition, identifier, example, match), its related records (related[], each with relationship, cardinality, required and quoted definitions), and send: in plain words, exactly which ID to send and how to send related ones;
• identity: how each case gets its ID (mode: provided, fields, content or issued), send in plain words, and the fields or question it uses;
• questions[]: key, type (enum, boolean, number, date), meaning (quoted, with its locator), answer (what to send and how it’s read: send, valueFormat, interpretation, threshold, applies, dependsOn, appliesWhen), answers[] (each with meaning, inclusions, exclusions, examples, edgeCases) and whereToLook[]; a question about a related record carries about (relationship, subject);
• outcomes[]: id, meaning, nextStep (quoted), the outputs that outcome asks the agent to write, and escalate when it hands off;
• escalations: the hand-offs the policy names (routes[], each id with its quote), which one the unresolved path and the attempt limit use, and the rule in words;
• whenUnresolved: what to do when nothing is decided (quoted);
• attempts: max, withProgress and the rule in words;
• guidance.gather: how to gather evidence so one request is enough;
• input: for this tool, { tool: "get_job_decision", jsonSchema, note }, the exact arguments to send;
• limits: the facts limits;
• release: the release ID and digests;
• rules (with detail: "full"), each with its quoted text.

get_job_decision

Get the company’s decision for one case. Send, for each question, the exact words your sources say and where they came from. Use only the outcome Felspar returns.

Felspar works out the case ID by the job’s identity mode, normalizes it and each related ID by its subject’s match rule, picks the release (Latest or the agent’s pin) and assigns each call its own execution ID. The result is the same as the REST decision result: status, reason, and result with outcome, explanation, retry, attempts, nextStep, outputs, interpretation, case, subject, escalation, missing, receipt and executionObjectId.

• case: { id, mode } for a job released with identity modes, where mode is provided, fields, content or issued. Send case.id as entity_id for every later decision on the same case.

• subject: { type, id, related[] }, with the normalized IDs and, for each related record, the questions it supplied evidence for.

• escalation: { id, trigger, why } when the release names a hand-off for this result. trigger is outcome, unresolved or attempt_limit. Report the id exactly and hand the case off; don’t ask again. See Subjects and escalations.

• missing: with status gap, the required related records the request lacked, such as ["missing: counterparty"].

A wrong or missing case ID is refused with one of the identity refusals, such as entity_id_required or unknown_case_id.

check_output

Check text the agent wrote for one of its own decisions (a ticket reply, an email) before it is sent or saved.

Returns pass, revise (each finding with the policy sentence it quotes and what to fix), review_required or unavailable, and on pass a receipt bound to exactly this text. Any edit needs a new check. A pass means the text follows the released rules; it is not approval to send. Refusals include output_not_required (the outcome asks for no such output; it lists the ones it does), decision_not_decided and no_output_checks. Each check counts as one decision toward rate limits. Over REST: POST /v0/jobs/{job}/output-checks.

Receipt verification is deliberately not an MCP tool. The code that acts calls POST /v0/executions/{id}/verify with the same key.

Authoring tools

Available to a signed-in member, approver or owner. None of them can approve or release.

get_pack_guide

How to write a pack draft: the format, the rules Felspar enforces and a small example. No inputs. Read it before the first check_pack. Same content as Pack draft format.

list_sources

The workspace’s connected policy documents. No inputs. Each entry:

read_source

The exact text of one added source: the version that was added, which may be older than the document now.

Quote meanings from this text word for word; Felspar refuses any quote it can’t find.

add_current_version

When a document is changed, capture its current text as a new source, read with your own connection. Returns the new sourceObjectId; read, draft and propose from that one. Live decisions don’t change until a new proposal is released.

This is the only way an MCP sign-in can add a source. Text the assistant writes is never accepted as a source (source_text_not_allowed).

check_pack

Check a pack draft against its source without saving anything.

Returns status:

• invalid, with problems[] (each a path and message) and warnings;
• tests_failed, with tests and warnings;
• needs_definitions, with blocking (count), tests and warnings;
• ready, with tests, warnings and artifactDigest.

When the draft revises a released job and removes an escalation ID, subject type or relationship name, or changes the job’s subject, the result also carries breaking: { changes[], agents }. Report each change to the person: code that acts on results may depend on it.

propose_pack

Submit a checked draft as a proposal for review. Same inputs as check_pack. Returns status: "proposed" with the proposal, tests, warnings, breaking when it applies, a review link to the web app and authority: "unapproved". Refuses with status: "needs_definitions" while any blocking finding remains. Agents keep using the current release until an approver approves and releases on the web app.

backtest

Re-decide the job’s saved cases (the last 30 days) under a proposal and under the current release, before anyone approves it.

Returns each case as unchanged, changed (current outcome to proposal outcome, with each side’s escalation), unresolved (with the questions still open and why), needs_reinterpretation (with an estimate) or unavailable; counts of each; escalationChanged, the number of cases whose escalation differs; breaking when the proposal removes something callers may depend on; a total estimate; and agents: those that ran the cases and those following the job on Latest or pinned. Calls no model unless reinterpret is true. Writes nothing. Counts as 10 decisions toward rate limits. See Review and backtest.