Tool reference¶

Server: atelier-mcp · Tools: 18 · Result form: JSON text content

Every tool follows one record: intent, a parameter table, and one example call with an example result. Parameters marked required must be supplied; the rest fall through to a server default. Results are illustrative — field values vary with live data.

Errors are data

A backend failure returns {"ok": false, "error": "..."} as a normal result, not a protocol error. A client reads it and adapts in the same loop.

Platform¶

platform_health¶

Liveness of the backing services — overseer, overdex-server, overwatch, and the pulsar ClickHouse. Call first, before you do real work.

Param	Type	Required	Default	Notes
none

{ "tool": "platform_health", "arguments": {} }

{ "overseer": "ok", "overdex_server": "ok", "overwatch": "ok", "pulsar_clickhouse": "ok" }

Collectors¶

list_collectors¶

List the caller's deployed market-data collectors with their services and status.

Param	Type	Required	Default	Notes
none

{ "tool": "list_collectors", "arguments": {} }

{
  "services": [
    { "service_id": "63060972", "status": "active", "exchange": "binance", "symbol": "BTCUSDT" }
  ]
}

deploy_collector¶

Register a remote (bring-your-own) market-data collector on an exchange. Returns service_id, binding_id, and the agent JWT for running your own agent container against the gateway with that token.

This tool is remote bring-your-own only. It registers the collector and hands back a JWT; the caller runs their own agent container against the gateway with that JWT. The overseer never spawns a platform-managed container from this tool. Consult list_cex_options for a venue's native symbol format, market types, and valid order-book depths before calling.

Param	Type	Required	Default	Notes
`exchange`	string	yes		Lowercase venue id, e.g. `binance`, `coinbase`, `kraken`
`symbols`	string[]	yes		Venue-native symbol form, one worker each — binance `BTCUSDT`, coinbase `BTC-USD`, kraken `BTC/USD`
`market_type`	string	no	`spot`	e.g. `spot`, `perpetual`
`region`	string	no		Advisory: the colocation region this choice is based on
`orderbook`	bool	no	`true`	Collect an order book
`orderbook_depth`	int	no	`50`	Order book depth
`trades`	bool	no	`true`	Collect trades
`kind`	string	no	`data`	`data` (synchronized + parquet) or `market` (raw)

Datatype defaults land order book (depth 50) and trades ON; liquidations, funding rates, and open interest OFF.

{
  "tool": "deploy_collector",
  "arguments": {
    "exchange": "binance",
    "symbols": ["BTCUSDT"],
    "market_type": "spot"
  }
}

{
  "service_id": "63060972",
  "binding_id": "cfb7688a",
  "token": "your-agent-jwt"
}

collector_status¶

Get a collector's status — service, binding, and recent commands — by service_id.

Param	Type	Required	Default	Notes
`service_id`	string	yes		The id returned by `deploy_collector`

{ "tool": "collector_status", "arguments": { "service_id": "63060972" } }

{
  "service": { "service_id": "63060972", "status": "active" },
  "binding": { "binding_id": "cfb7688a", "status": "active" },
  "commands": []
}

collector_command¶

Send a live command to a collector.

Param	Type	Required	Default	Notes
`service_id`	string	yes		Target collector
`kind`	string	yes		`task_pause`, `task_resume`, `binding_release`, or `agent_restart`

{
  "tool": "collector_command",
  "arguments": { "service_id": "63060972", "kind": "task_pause" }
}

{ "service_id": "63060972", "command": "task_pause", "accepted": true }

collector_health¶

Health of a deployed collector: a top-line verdict (healthy · starting · degraded · silent) plus liveness and data-landing detail. Answers "is the collector I deployed actually producing data?" — a fresh deploy reads as starting until data lands.

Param	Type	Required	Default	Notes
`service_id`	string	yes		Target collector

{ "tool": "collector_health", "arguments": { "service_id": "63060972" } }

{
  "service_id": "63060972",
  "binding_id": "cfb7688a",
  "verdict": "starting",
  "service_status": "active",
  "binding_status": "active",
  "liveness": { "connected": true, "heartbeat_age_s": 4, "ws_latency_ms": 22.1 },
  "landing": { "rows_last_5m": 0, "total_rows": 0, "last_row_age_s": null,
               "expected_first_data_by": "2026-07-03T18:05:00Z" }
}

stop_collector¶

Operator-stop a collector by service_id. Use it to clean up a collector you deployed.

Param	Type	Required	Default	Notes
`service_id`	string	yes		Target collector

{ "tool": "stop_collector", "arguments": { "service_id": "63060972" } }

{ "service_id": "63060972", "stop": "requested" }

Deploy-prep¶

list_cex_options¶

List every deployable CEX option: the 12 supported venues with their native symbol format (with example), market types, valid order-book depths, and datatype availability. Consult this before deploy_collector to pick a correct exchange, symbols, market_type, and orderbook_depth.

Param	Type	Required	Default	Notes
none

{ "tool": "list_cex_options", "arguments": {} }

{
  "venues": [
    {
      "exchange": "binance",
      "label": "Binance",
      "symbol_format": "concatenated uppercase",
      "symbol_example": "BTCUSDT",
      "market_types": ["spot"],
      "orderbook_depths": [5, 10, 20, 50, 100, 500, 1000],
      "default_orderbook_depth": 50,
      "datatypes": [
        { "name": "orderbook", "available": true },
        { "name": "trades", "available": true },
        { "name": "funding", "available": false, "pending_on": "perpetual endpoint routing" }
      ]
    },
    {
      "exchange": "coinbase",
      "label": "Coinbase",
      "symbol_format": "dash-separated",
      "symbol_example": "BTC-USD",
      "market_types": ["spot"],
      "orderbook_depths": [50],
      "default_orderbook_depth": 50,
      "datatypes": [
        { "name": "orderbook", "available": true },
        { "name": "trades", "available": true }
      ]
    }
  ]
}

Colocation¶

query_colocation¶

Query the colocation oracle for the best AWS region per exchange, ranked by latency score. Omit exchange for all venues.

Param	Type	Required	Default	Notes
`exchange`	string	no		Filter to one venue; omit for all, ranked by score

{ "tool": "query_colocation", "arguments": { "exchange": "binance" } }

{
  "count": 1,
  "exchanges": [
    { "exchange": "binance", "region": "ap-northeast-1", "score": 0.96 }
  ]
}

Governance¶

governance_catalog¶

The governance catalog: every declared stream reconciled with observed reality, labeled present, absent, or stale. All filters are optional.

Param	Type	Required	Notes
`exchange`	string	no	Filter by venue
`market_type`	string	no	Filter by market type
`symbol`	string	no	Filter by symbol
`datatype`	string	no	Filter by datatype
`presence`	string	no	`present`, `absent`, or `stale`

{
  "tool": "governance_catalog",
  "arguments": { "exchange": "coinbase", "presence": "present" }
}

{
  "streams": [
    { "exchange": "coinbase", "market_type": "spot", "symbol": "BTC/USDT",
      "datatype": "orderbook", "presence": "present" }
  ]
}

stream_scorecard¶

Completeness and quality scorecard for one stream. window_secs recomputes completeness live over a trailing window. Symbols may contain a slash (BTC/USDT).

Param	Type	Required	Notes
`exchange`	string	yes	Venue id
`market_type`	string	yes	e.g. `spot`
`symbol`	string	yes	As the platform records it, may contain a slash
`datatype`	string	yes	`orderbook`, `trades`, `funding`, `open_interest`, or `liquidations`
`window_secs`	int	no	Recompute completeness over this trailing window (seconds)

{
  "tool": "stream_scorecard",
  "arguments": {
    "exchange": "coinbase", "market_type": "spot",
    "symbol": "BTC/USDT", "datatype": "orderbook"
  }
}

{
  "exchange": "coinbase", "symbol": "BTC/USDT", "datatype": "orderbook",
  "completeness": { "grade": "critical", "ratio": 0.049 },
  "quality": { "max_severity": "none", "checks": [] }
}

governance_datasets¶

The governance file-level dataset catalog over the parquet lake, across all datatypes.

Param	Type	Required	Default	Notes
none

{ "tool": "governance_datasets", "arguments": {} }

{
  "datasets": [
    { "exchange": "kraken", "symbol": "ETH-USD", "datatype": "trades", "files": 12 }
  ]
}

Fit & serve¶

list_datasets¶

List fittable datasets (venue, symbol, datatype), each with an opaque dataset_id.

Param	Type	Required	Default	Notes
none

{ "tool": "list_datasets", "arguments": {} }

{
  "datasets": [
    { "dataset_id": "ds_9f3a…", "exchange": "kraken", "symbol": "ETH-USD",
      "datatype": "trades" }
  ]
}

fit_pricing¶

The fit price in compute tokens. A fit charges compute tokens against the caller's identity; this returns the current price so a client can report it before running a fit.

Param	Type	Required	Default	Notes
none

{ "tool": "fit_pricing", "arguments": {} }

{ "unit": "compute_token", "price": 10 }

fit_hawkes¶

Fit a univariate Hawkes process (MLE) to a dataset and persist it. Returns fitted params and diagnostics; the chart series are omitted — fetch them with get_fit. A non-converged fit returns an error you can adapt to by loosening tolerance. Prefer a trades dataset.

Param	Type	Required	Default	Notes
`dataset_id`	string	yes		From `list_datasets`
`tolerance`	float	no	`1e3`	Gradient infinity-norm; tight for real data — loosen (e.g. `1e4`, `5e4`) if not converged
`max_iter`	int	no	`50000`	Optimizer iteration cap
`train_ratio`	float	no	`0.8`	Train split fraction
`learning_rate`	float	no	`1e-2`	Gradient-ascent step
`seed`	int	no		Reproducibility seed

{
  "tool": "fit_hawkes",
  "arguments": { "dataset_id": "ds_9f3a…", "tolerance": 10000 }
}

{
  "fit_id": "fit_7c21…",
  "converged": true,
  "branching_ratio": 0.182,
  "n_train": 561,
  "tolerance_used": 10000
}

list_fits¶

List the caller's fit runs, newest first.

Param	Type	Required	Default	Notes
none

{ "tool": "list_fits", "arguments": {} }

{
  "fits": [
    { "fit_id": "fit_7c21…", "dataset_id": "ds_9f3a…", "converged": true,
      "created_at": "2026-07-03T17:50:00Z" }
  ]
}

get_fit¶

Fetch a persisted fit artifact by fit_id, including the full chart series.

Param	Type	Required	Default	Notes
`fit_id`	string	yes		From `fit_hawkes` or `list_fits`

{ "tool": "get_fit", "arguments": { "fit_id": "fit_7c21…" } }

{
  "fit_id": "fit_7c21…",
  "converged": true,
  "branching_ratio": 0.182,
  "series": { "intensity": [ ], "residuals": [ ] }
}

forecast_fit¶

Forecast event arrivals from a stored fit — median plus a p25/p75 band. Reproducible for a given seed.

Param	Type	Required	Default	Notes
`fit_id`	string	yes		The fit to forecast from
`n_forecast`	int	no	`50`	Steps to forecast
`mc_paths`	int	no	`500`	Monte-Carlo paths; `>1` gives a p25/p75 band
`seed`	int	no		Reproducibility seed

{
  "tool": "forecast_fit",
  "arguments": { "fit_id": "fit_7c21…", "n_forecast": 10 }
}

{
  "fit_id": "fit_7c21…",
  "n_forecast": 10,
  "median_cumulative_gap_ms": 48183,
  "band": { "p25": [ ], "p75": [ ] }
}