create_commentary

Attach narrative analysis to a model run, or to one named output of the run. Use this after compare_runs / get_run_output to save the agent’s interpretation alongside the data it explains. If output_name is omitted, the commentary is run-level. If output_name is provided and the run has output data available, the name is validated against the same resolver as get_run_output. Worked example — after compare_runs surfaces a 12% revenue beat: create_commentary(run_id=‘<scenario_run_id>’, text=‘Q3 revenue beat plan by 12% — see compare_runs scenario_run vs base_run.’, output_name=‘forecast.json’). Returns: commentary (object) — the new row including commentary_id, version=1, run_id, project_name, output_name, text, author_id, and timestamps; pass commentary.version back as expected_version on the next update_commentary call.

Parameters

Name	Type	Required	Default
`run_id`	`str`	Yes	—
`text`	`str`	Yes	—
`output_name`	`str`	No	`''`
`change_note`	`str`	No	`''`

Returns

Returns a structured object. Top-level fields:

commentary (object)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "create_commentary",
  "arguments": {
    "run_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "output_name": "revenue",
    "text": "Revenue beat plan by 12% in March, mostly from SaaS expansion.",
    "change_note": "Initial variance readout"
  }
}

Response

{
  "commentary": {
    "commentary_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "tenant_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "project_name": "forecasts",
    "run_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "output_name": "revenue",
    "author_id": "22222222-2222-2222-2222-222222222222",
    "text": "Revenue beat plan by 12% in March, mostly from SaaS expansion.",
    "version": 1,
    "archived_at": null,
    "archived_by": null,
    "created_at": "2026-04-28T10:00:00+00:00",
    "updated_at": "2026-04-28T10:00:00+00:00"
  }
}

Notes

Module: Run Commentary
Requires authentication via API token or Auth0 JWT.