run_capability
Build (and optionally execute) a deterministic plan from a registered capability. Pass capability_id plus your question_id from start_question — the server re-derives the typed params from your question, so you can leave params as {} and don't need to know a capability's internal fields. Pass params only to refine a derived value (e.g. a specific region or date range); supplied keys override the derived ones. When you do send params, send only the fields params_contract marks required: everything else is optional, and the server applies schema defaults and rebuilds server_derived labels (chart titles, date-range prose, station and interconnector display names) from what you sent — never invent values for those. If something is genuinely missing you get every missing field back in one error, so one correction is enough. Returns the generated SQL, a chart spec, and a short data description — identical to what the chat pipeline would emit for the same capability. Pass execute: true to also run the SQL and get rows back (capped at the server's MCP_MAX_RESULT_ROWS limit) plus, when supported, a deterministic markdown answer. result has execute_sql's shape: a large result returns its first rows plus a result_id (page with fetch_result_rows, chart with build_chart); the answer and chart_figure are always built from every row. A chart_figure too big to inline comes back as a handle instead (chart_id, chart_url, summary, outline); see "Working with large results". Otherwise inspect the SQL and run it yourself with execute_sql.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"capability_id": "<capability_id>"
},
"name": "run_capability"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | Typed parameters for the chosen capability. **Optional when you passed a `question_id`** (from `start_question`): the server re-derives the params from your question, so `{}` is fine and you don't need to know each capability's internal fields. Anything you do pass overrides the derived value for that key — use it only to refine (e.g. a specific region or date range). Shape is capability-specific; see `list_capabilities`. Must be a JSON object (`{}`). Without an explicit `type: object` annotation, some MCP clients (e.g. Claude Code) stringify the value before sending; the explicit schema prevents that (#1144). | |
| execute | No | When true, execute the generated SQL and return rows alongside the plan. Rows are still capped at `MCP_MAX_RESULT_ROWS`. Defaults to false — callers can inspect the SQL and decide whether to run it. | |
| question_id | No | Optional UUID returned by an earlier `start_question` call. When provided, this tool call is attributed to that question, and so is a parked result. | |
| capability_id | Yes | Stable capability ID, e.g. `constraint_frequency_by_interconnector`. Call `list_capabilities` first to discover available IDs and their per-capability parameter schemas. |