Tool reference
Every tool the Fareground MCP server exposes — 66 in all. The description under each one is the exact text your agent receives. Flags come from the server's own hints: read-only never changes anything; destructive replaces or removes something; retry-safe can be repeated with the same request ID without doing the work twice.
Every tool takes human-friendly handles: an environment by ID or exact name. Lists return
{items, total, truncated, next_cursor} — pass next_cursor back as cursor.
| Group | Tools |
|---|---|
| Orientation and account | 4 |
| Ready environments | 12 |
| Custom environments | 27 |
| Participate | 4 |
| Scenario-format environments | 11 |
| Scenario-format runs | 8 |
Orientation and account
Who the connection acts as, the built-in guide, balance, costs and long-running operations.
whoami
read-only
whoami()
The account this credential acts as, and what it may do.
scopes is the one to check before a write: a read-only token will
fail every mutating call, and failing them one at a time is a slow
way to discover that.
guide
read-only
guide(topic: str = 'overview')
How to use this platform — read this before building anything.
overview explains the environment → run → read-the-report loop.
Other topics cover a single area in depth. Call with no argument to
start; the returned topics list names the rest.
get_balance
read-only
get_balance()
Your wallet balance. Simulation runs cost money; check before a big one.
get_cost_estimates
read-only
get_cost_estimates()
Read historical platform cost estimates and their sample sizes. These are estimates, not price quotes or spending caps; check get_balance before paid work.
Ready environments
Market, Exchange, Council and Dispute — configure, review, start and read without authoring.
list_fareground_environments
read-only
list_fareground_environments()
The pre-built environments (council, market, exchange, dispute): what each simulates, the settings it takes with their types and defaults, and its catalog (presets, products, instruments). Read it before preparing a session; a setting not listed there is refused.
prepare_fareground_session
changes data
prepare_fareground_session(
environment: str,
config: dict,
conversation_id: Optional[str] = None,
)
Create an unstarted session of a pre-built environment from its settings. Free: nothing runs yet.
environment is council, market, exchange or dispute; config follows that environment's settings from list_fareground_environments. Returns session_id and the page where the person reviews and edits it. Show the person what it is set to; start it only when they say to, or asked you to run it.
save_fareground_setup
changes data
save_fareground_setup(environment: str, config: dict)
Save a setup of a pre-built environment to the person's environments, or update one. Free.
config: {name, description, and the environment's settings as prepare takes them — models, agents and
all}. Add saved_id to update a Council, Exchange or Dispute setup, saved_market_id for a Market. An
unfinished setup saves, and problem says what a run still needs. list_fareground_environments shows each
environment's under saved. Run one by preparing with its settings (changed for this run if asked); a
Market run also takes config.saved_market_id, so it plays that market's people.
upload_customer_file
changes data
upload_customer_file(filename: str, content: str)
Upload an organisation's customer export (CSV/TSV text: one row per order line) for a Market population. Free. Returns its columns, what each holds, the role each seems to play (customer, date, order, product, quantity, unit_price, amount, discount, segment, channel, status), which are personal (names, emails, phones: never read) and its first rows with personal cells masked. Confirm the mapping with the person, then build_customer_population. The file is kept for a day, so a population can be built from it again with other settings, then deleted.
preview_customer_file
changes data
preview_customer_file(upload_id: str, steps: Optional[list] = None)
Try a reshape plan on an uploaded customer file before building: the columns as the plan leaves them, read as the build would read them (shape, mapping, missing roles, notes, per-column stats, first rows). Steps, in order: {scale:{column, divide_by}} (cents), {join:{columns, into, with?}} (date + time), {unpivot:{keep, columns, name_into, value_into}} (a column per period), {drop_rows:{column, matching}} (totals inside the data), {map_values:{column, values:{from: to}}} (codes into words). Free.
build_customer_population
changes data
build_customer_population(
upload_id: str,
mapping: dict,
label: str = '',
holdout_days: Optional[int] = None,
steps: Optional[list] = None,
)
Build a population of the organisation's customers from an upload: {role: column} for at least customer and date. Each customer is kept as the patterns in their history under a pseudonymous id; nothing personal is stored. holdout_days (7-120) keeps the file's last days out of what is learned, to backtest a Market run against them. steps: the reshape plan preview_customer_file confirmed, applied to every row. A customer summary (one row per customer) maps customer, orders_count, last_purchase and optionally first_purchase, total_spent, segment. Builds in the background: follow get_customer_population until ready, then tell the person what it learned and what the file lacked. Free.
get_customer_population
read-only
get_customer_population(population_id: str)
A customer population: building, ready or failed (with why); once ready, learned says what was read
(customers, purchases, period, products, rows skipped) and each column the file lacked with what that
leaves unknown. Run a Market on it with population.population_id.
start_fareground_session
changes data
start_fareground_session(environment: str, session_id: str)
Start a prepared session, billed to the person's wallet. Start it when the person says to, or asked you to run it. Failed attempts count toward requested run limits; do not automatically replace them. Terminal sessions cannot restart here. Read status after an uncertain start instead of starting again. Returns at once; read it later with get_fareground_session rather than waiting.
get_fareground_session
read-only
get_fareground_session(environment: str, session_id: str)
A session's status: progress while it runs, the recorded outcome once it is completed. For Market purchases and reports, Exchange history and bars, or Dispute trial statements, use get_fareground_session_evidence.
get_fareground_session_evidence
read-only
get_fareground_session_evidence(
environment: str,
session_id: str,
after: int = 0,
run_index: Optional[int] = None,
)
Read stored evidence without starting a run: Market roster, purchases and reports; Exchange seed history and price/news bars; Dispute trial events, with counsel and judge statements (speakers' claims, not verified facts). Events carry run_index (Market, Exchange); run_started marks attempts. Visit days start at zero; market_day totals are cumulative. Follow next_after by passing it as after until null, optionally selecting run_index (Market, Exchange). Missing reasons and summary zero counters do not prove successful model calls.
write_dispute_case_file
changes data
write_dispute_case_file(session_id: str, case: dict)
As the person's attorney, write their side's case file while the case is being prepared. Each call is a full snapshot of: case_theory, objective, case_summary, key_facts, strongest_evidence, vulnerabilities, likely_counterarguments, rebuttals, next_steps. Their attorney argues from it at trial.
set_environment_metrics
changes data
set_environment_metrics(
environment_id: str,
metrics: list,
headline: Optional[str] = None,
)
Choose which results a custom environment's report shows: each a declared result key, or {key, measures:[...]}; headline is the one it leads with. Later runs report these.
Custom environments
Build a scenario as one contract, check and verify it, run it many times and read the results.
import_custom_dataset
changes data · destructive
import_custom_dataset(
environment_id: str,
input_id: str,
expected_revision: str,
filename: str,
content: str,
source_label: str = '',
source_url: Optional[str] = None,
origin: str = 'unknown',
)
Import UTF-8 CSV/JSON/JSONL text (up to 2 MB / 50,000 rows) into one table or list input.
origin is measured, synthetic or unknown. Replaces only this input and records a source receipt; refit and verify before running. After an uncertain response, read the environment before retrying with its revision.
simulate_custom_environment
changes data · retry-safe
simulate_custom_environment(
contract: dict,
request_id: str,
cases: list[StudyCase],
question: str = '',
input_values: Optional[dict] = None,
n_runs: int = 2,
max_rounds: int = 4,
agent_bindings: Optional[dict] = None,
wait_seconds: float = 20,
fit_patterns: bool = False,
datasets: Optional[dict[str, SourceDataset]] = None,
comparison: Optional[StudyComparison] = None,
)
One paid study: save the environment, verify known answers, run its agents, return outcomes.
cases need expected_outputs or expected_series; they default to max_rounds. fit_patterns=True fits declared patterns to the supplied data first. datasets maps table/list input IDs to {filename, content, origin?, source_label?, source_url?} (UTF-8 CSV/JSON/JSONL, up to 8 files and 2 MB); do not also set those inputs in input_values. comparison={label, variants:[{id,label,inputs}]} runs 2–8 conditions; n_runs is per condition, 50 runs in total. A case may name variant_id instead of input_values; cover every condition. agent_bindings follows start_custom_run. request_id (UUID) identifies the whole study: reuse it after an uncertain response, use a new one for changed arguments. Failed checks start no runs. Returns operation_id; waits up to wait_seconds (0–30) for outcomes. Follow get_custom_study, then get_custom_run with the returned environment_id/session_id.
get_custom_study
read-only
get_custom_study(operation_id: str)
Read a study's progress. When status=done, result holds environment_id and session_id (or status verification_failed); follow get_custom_run for the simulations.
stop_custom_study
changes data · destructive · retry-safe
stop_custom_study(operation_id: str)
Cancel a study before its simulations are admitted; after admission use stop_custom_run.
get_custom_verification_data
read-only
get_custom_verification_data(
environment_id: str,
expected_revision: str,
expected_evidence_sha256: str,
kind: Literal['verification', 'probe'] = 'verification',
path: str = '',
representation: Literal['items', 'json'] = 'items',
limit: int = 20,
cursor: Optional[str] = None,
)
Read pages of exact check evidence from a data_ref, at a JSON Pointer path.
Follow next_cursor; representation=json returns exact JSON text. A 409 means the checks were replaced; start again from the new data_ref.
sample_personas
read-only
sample_personas(
records: list[dict],
size: int,
seed: int = 0,
run: int = 0,
resample: bool = True,
constraints: Optional[dict] = None,
fixed: Optional[list[dict]] = None,
assignments: Optional[list[dict]] = None,
id_field: str = 'id',
group_by: Optional[str] = None,
weight_field: Optional[str] = None,
source: str = 'authored',
source_version: Optional[str] = None,
assignment_field: str = 'role',
)
Sample a reproducible participant cohort and return its full provenance.
list_environment_engines
read-only
list_environment_engines()
List reusable engines for a custom environment. Inspect one before writing its rules.
get_environment_engine
read-only
get_environment_engine(engine_id: str)
Get an engine and its complete, executable starter contract. Customize rules, inputs and outputs.
environment_authoring_guide
read-only
environment_authoring_guide(part: str = 'authoring')
Read the installed Environments SDK guide, the source of truth for the contract language. Start with authoring (a worked contract and the loop); core maps every other part.
environment_contract_schema
read-only
environment_contract_schema(path: str = '', offset: int = 0, limit: int = 10)
Inspect a focused JSON Pointer in the installed environment contract schema.
check_environment_contract
read-only
check_environment_contract(
contract: dict,
input_values: Optional[dict] = None,
max_rounds: int = 4,
)
Validate a complete custom environment contract and inputs without saving or spending.
create_custom_environment
changes data
create_custom_environment(
contract: dict,
question: str = '',
input_values: Optional[dict] = None,
max_rounds: int = 4,
)
Save a private custom environment from a complete checked contract. Probe it before running.
get_custom_environment
read-only
get_custom_environment(environment_id: str)
Read the complete saved contract, revision, inputs and last structural probe.
get_environment_page
read-only
get_environment_page(environment_id: str)
What people read about a saved custom environment: the diagram, participants (what each knows, can do and wants, and what its agent sees), the rules in run order, what the world tracks, the checks and every assumption with its basis. Nothing runs and nothing is saved.
preview_custom_environment
read-only
preview_custom_environment(
environment_id: str,
actor: Optional[str] = None,
stage: Optional[str] = None,
offset: int = 0,
limit: int = 50,
seed: int = 0,
agent_bindings: Optional[dict] = None,
input_values: Optional[dict] = None,
expected_revision: Optional[str] = None,
)
Resolve inputs, entity IDs and stages; with actor, show that agent's model or policy, initial prompts and legal actions. No model is called and nothing is saved.
agent_bindings and input_values preview proposed settings; expected_revision fences the contract.
update_custom_environment
changes data · destructive
update_custom_environment(
environment_id: str,
expected_revision: str,
contract: dict,
question: Optional[str] = None,
input_values: Optional[dict] = None,
max_rounds: Optional[int] = None,
)
Replace a complete contract with optimistic revision checking. Omitted settings are preserved; probe again after editing.
patch_custom_environment
changes data · destructive
patch_custom_environment(
environment_id: str,
expected_revision: str,
changes: dict,
question: Optional[str] = None,
input_values: Optional[dict] = None,
max_rounds: Optional[int] = None,
)
Replace selected top-level contract sections, preserving everything else. Use the revision from get_custom_environment; probe again after editing.
probe_custom_environment
changes data
probe_custom_environment(
environment_id: str,
rounds: int = 3,
seed: int = 0,
input_values: Optional[dict] = None,
decisions: Optional[list[ProbeDecision]] = None,
expected_outputs: Optional[dict] = None,
expected_series: Optional[dict] = None,
absolute_tolerance: float = 1e-09,
view: Literal['auto', 'summary', 'full'] = 'auto',
claim: Optional[str] = None,
)
Run a free random or scripted check with optional expected outputs. claim is the one sentence people read for it on the environment page (what it proves).
Large results return failures and a get_custom_verification_data reference; view=full returns everything.
verify_custom_environment
changes data
verify_custom_environment(
environment_id: str,
expected_revision: str,
cases: list[ProbeCase],
view: Literal['auto', 'summary', 'full'] = 'auto',
)
Run up to eight known-answer cases against one revision; all must pass before a paid run.
Large results return failures and a get_custom_verification_data reference; view=full returns everything.
fit_custom_environment
changes data · destructive
fit_custom_environment(
environment_id: str,
expected_revision: str,
input_values: Optional[dict] = None,
)
Fit declared patterns to the current data and save the estimates; verify the new revision before running.
grounding_status names the inputs the fit read; changing them or the rules makes the fit stale. A failed or concurrent fit saves nothing.
analyze_custom_environment
changes data
analyze_custom_environment(
environment_id: str,
rounds: int = 10,
input_values: Optional[dict] = None,
)
Sample legal input boundaries for rule failures in an isolated process. An ok result is a bounded structural check, not predictive validation.
start_custom_run
changes data · retry-safe
start_custom_run(
environment_id: str,
request_id: str,
n_runs: int = 2,
max_rounds: Optional[int] = None,
input_values: Optional[dict] = None,
agent_bindings: Optional[dict] = None,
)
Start a durable paid custom-environment batch. Reuse UUID request_id on uncertain retries.
agent_bindings maps entity IDs, agent types or '' to {kind:'llm', model?:
get_custom_run
read-only
get_custom_run(
environment_id: str,
session_id: str,
view: Literal['summary', 'full'] = 'summary',
)
Read a durable batch's outcomes, run health and report.
Large values are marked summary_only; read them with get_custom_run_data using each run's data_ref. view=full returns the complete batch and report.
get_custom_run_data
read-only
get_custom_run_data(
environment_id: str,
session_id: str,
run_id: str,
part: Literal['inputs', 'outputs', 'series', 'diagnostics', 'agent_bindings', 'contract', 'decisions'] = 'outputs',
path: str = '',
representation: Literal['items', 'json'] = 'items',
limit: int = 20,
cursor: Optional[str] = None,
expected_value_sha256: Optional[str] = None,
)
Read pages of one run's exact recorded inputs, outcomes, series, diagnostics or bindings.
decisions contains submitted tool actions and execution receipts, not raw provider wire data. Check its truncated/dropped counts before treating the records as complete. run_id is a job or simulation ID; path is a JSON Pointer (escape / as ~1, ~ as ~0). Large values return a summary and a path to drill into; representation=json returns exact JSON text pages. Pass expected_value_sha256 from a summary and reuse next_cursor unchanged; a 409 means the value changed, so restart. recorded=false means the value was not recorded.
list_custom_runs
read-only
list_custom_runs(
environment_id: str,
limit: int = 25,
cursor: Optional[str] = None,
)
List durable batches for one custom environment, newest first. Use a session_id with get_custom_run.
wait_for_custom_run
read-only
wait_for_custom_run(
environment_id: str,
session_id: str,
timeout_seconds: float = 20,
)
Wait for all jobs in a custom-environment batch, then return it with its report across seeds. Timeout leaves the batch running; use get_custom_run later.
stop_custom_run
changes data · destructive · retry-safe
stop_custom_run(environment_id: str, session_id: str)
Request cancellation of a custom batch. Finished work is retained; poll get_custom_run for its final state.
Participate
Play one seat in a simulation yourself while agents play the rest.
enter_simulation
changes data
enter_simulation(
environment_id: Optional[str] = None,
contract: Optional[dict] = None,
seat: Optional[str] = None,
inputs: Optional[dict] = None,
model: Optional[str] = None,
offline: bool = False,
)
Participate: put the person inside a simulation — they play seat (an agent entity id: the role they
take, played as themselves under their own name) and models play everyone else, reacting to what they do.
Name environment_id (one of their custom environments, when it is this same situation) or contract (an
Environments SDK contract you built for them from their situation; see guide("immersive") for how to write
one to be played: their seat under their own name, grounded in their real material, a persona for every
other character). Played worlds are always built for the person, never picked from ready-made ones. Billed per model reply;
offline=true is free (the others play by rule or at random, for checking mechanics only).
While they are inside, you are the narrator, not a character: show them the situation, their goal and every new line exactly as the characters said it, then pass what they do to speak_in_simulation. Never answer for a character or invent what happens.
speak_in_simulation
changes data
speak_in_simulation(
session_id: str,
text: Optional[str] = None,
move: Optional[str] = None,
details: Optional[dict] = None,
since: int = 0,
)
The person's move, then everyone else's answers. Pass what they say as text, unchanged. For a move with
details (make an offer, vote, investigate a system), name it as move (from moves) with its details
({"salary": 110000}) and any words they say with it as text; with text alone the move is read from their
words. Returns the lines since since (the last_seq you already showed): show them as they are. refused
means the world would not take it and the turn is still theirs; an error that says the move was taken back
means the others could not answer — make it again.
rewind_simulation
changes data
rewind_simulation(session_id: str, moment: int)
Go back: undo the person's move number moment (from moments) and everything after it, so they can take
it another way. The world is as it was just before that move; the moment's tool and args are the move as
they made it, to offer back to them to change. Works on a finished run too while it is open. The characters
may answer differently this time.
restart_simulation
changes data
restart_simulation(session_id: str)
Play it again from the beginning, same setup; nobody will answer the same way twice. To change the setup (inputs, who plays whom), enter_simulation again with new inputs; earlier runs stay as records.
Scenario-format environments
The older environment format. New simulations are built as custom environments.
list_environments
read-only
list_environments(
limit: Optional[int] = None,
cursor: Optional[str] = None,
mine_only: bool = False,
)
Environments you can run — yours first, then the shared library.
Rows are trimmed to identity and status. format says which tools
apply: environments-sdk-v1 is a custom environment (read it with
get_custom_environment, run it with start_custom_run); any other is
a scenario environment (get_environment, run_environment).
get_environment
read-only
get_environment(environment: str)
One environment's full definition, by id or exact name.
inputs is the part that matters before running: it lists every
value run_environment accepts, with types and defaults.
list_mechanisms
read-only
list_mechanisms()
The mechanisms an environment can be built on.
A mechanism is the underlying simulated system — a market, an auction, a social network. It decides which actions exist, so pick it before writing rules that depend on them.
list_outcome_options
read-only
list_outcome_options(mechanism: str)
Ready-made outcome definitions for a mechanism.
An outcome is what a run resolves to — the thing being forecast. Pick one of these rather than hand-writing the spec.
list_patterns
read-only
list_patterns()
Reusable scenario patterns to start a new environment from.
create_environment
changes data
create_environment(
name: str,
mechanism: Optional[str] = None,
question: Optional[str] = None,
description: Optional[str] = None,
category: Optional[str] = None,
definition: Optional[Mapping[str, Any]] = None,
)
Create an environment. Returns it with the id to run.
name and a question are the minimum worth creating: the question
is what a run answers, and an environment without one has nothing to
resolve.
Everything structural goes in definition, matching the shape
get_environment returns — participants, rules, properties, actions,
inputs, outcome, dynamics, max_rounds. Build it up incrementally with
update_environment, then call mark_environment_ready before running.
New environments start as drafts. Call mark_environment_ready when
the definition is complete.
update_environment
changes data · destructive
update_environment(
environment: str,
definition: Optional[Mapping[str, Any]] = None,
name: Optional[str] = None,
description: Optional[str] = None,
category: Optional[str] = None,
question: Optional[str] = None,
)
Edit an environment in place.
This REPLACES the fields you send rather than merging into them —
sending rules replaces the whole rule list, it does not append one.
Read the current definition with get_environment, change what you
mean to change, and send the result back.
rename_environment
changes data · destructive
rename_environment(environment: str, name: str)
Change an environment's display name, nothing else.
mark_environment_ready
changes data
mark_environment_ready(environment: str)
Promote a draft to ready — it becomes runnable from the catalog.
The server checks the definition is complete and refuses with the specific gap if it is not, so a rejection here names what to fix.
delete_environment
changes data · destructive
delete_environment(environment: str)
Delete one of your environments. Past runs of it are unaffected.
autofill_environment
changes data
autofill_environment(
environment: str,
fields: Optional[list] = None,
values: Optional[Mapping[str, Any]] = None,
document: Optional[str] = None,
)
Ground an environment's inputs in real data.
Fills groundable input fields from live sources and returns each
value WITH its provenance. Pass values for anything already known
so the lookups compose, fields to fill only some of them, and
document to ground from a pasted document instead of a source.
The provenance comes back as grounded_fields — hand it to
run_environment so the report records where the numbers came from.
Scenario-format runs
Run scenario-format environments as ensembles and read their reports and events.
run_environment
changes data · retry-safe
run_environment(
environment: str,
request_id: str,
values: Optional[Mapping[str, Any]] = None,
n_runs: int = 20,
base_seed: int = 0,
use_llm: bool = True,
grounded_fields: Optional[Mapping[str, Any]] = None,
sequential: bool = False,
)
Start an ensemble. Supply a UUID request_id and reuse it on uncertain retries. Returns immediately with ensemble_id.
values fills the environment's inputs — see inputs on
get_environment for the accepted keys. Anything you omit uses its
default.
n_runs is how many simulations to aggregate (1–50). More runs
narrow the estimate and cost proportionally more, since each one is
a full simulation with its own LLM calls. Twenty is a reasonable
default; drop to a handful while iterating on a definition.
use_llm=False replaces the reasoning cast with random valid
actions. That is a FREE structural smoke test — it proves the
environment runs without erroring, and its numbers mean nothing.
Pass grounded_fields straight from autofill_environment to record
in the report where each input value came from.
This does not wait. Follow with wait_for_run, or poll get_run.
get_run
read-only
get_run(ensemble_id: str, include_runs: bool = False)
An ensemble's current state, and its report once finished.
status is one of running, done, failed, cancelled. counts
breaks the individual simulations down by status, and report
carries the aggregate answer once status is done.
The per-simulation detail is omitted unless you ask for it with
include_runs — for a 60-run ensemble it is by far the largest part
of the payload and is rarely what you want.
wait_for_run
read-only
wait_for_run(
ensemble_id: str,
timeout_seconds: float = _DEFAULT_WAIT,
include_runs: bool = False,
)
Block until an ensemble finishes, then return its final state.
Polls with a backing-off interval. On timeout this RAISES rather than returning a half-finished snapshot — a caller that treats an unfinished report as a result publishes a forecast built on the subset of simulations that happened to be done.
The run is unaffected by the timeout and keeps going; call
get_run later, or cancel_run to stop it.
get_run_report
read-only
get_run_report(ensemble_id: str)
Just the aggregate report, once the ensemble is done.
Raises while the run is unfinished rather than returning a partial answer, and raises with the failure reason if it did not succeed.
extend_run
changes data
extend_run(ensemble_id: str, n_more: int = 20)
Add more simulations to a finished ensemble, same world.
The report re-aggregates over every simulation, old and new. This is how you tighten an estimate that came back too uncertain — cheaper and more correct than starting a second ensemble, whose results you would have no sound way to pool.
cancel_run
changes data · destructive · retry-safe
cancel_run(ensemble_id: str)
Stop an in-flight ensemble. Finished simulations are kept.
list_runs
read-only
list_runs(
environment: str,
limit: Optional[int] = None,
cursor: Optional[str] = None,
)
Your past runs of an environment, newest first.
Each row carries the input values it used, so this is what to read
before re-running: it shows which configurations have already been
tried and what they produced.
get_run_events
read-only
get_run_events(
run_id: str,
limit: Optional[int] = None,
cursor: Optional[str] = None,
)
The event log of ONE simulation — what actually happened, round by round.
Note this takes a run_id (from get_run with include_runs=True),
not an ensemble id. This is the tool for "why did it conclude that":
the report tells you the aggregate, the events tell you the story.
SDK pages scan a durable journal; total is unknown because private
envelopes are excluded. Keep next_cursor when done is false to poll
new events without replaying the previous page.
Generated from the agent kit at 6482b576.