update_commentary

Edit commentary text under optimistic concurrency. Pass the version you observed last (typically the value returned by create_commentary or get_commentary) as expected_version; if it no longer matches the stored row, the tool returns a commentary-stale-version error carrying expected_version and actual_version so the caller can re-fetch and merge. Successful updates bump version by one and append a new immutable row to the version history. Worked example — after the user edits a saved analysis: update_commentary(commentary_id='', text=‘Q3 revenue beat plan by 14% (revised after FX rebase).’, expected_version=2). Returns: commentary (object) — the updated row, including the new version; pass commentary.version back as expected_version on the next update_commentary call.

Parameters

Name	Type	Required	Default	Description
commentary_id	str	Yes	—
text	str	Yes	—
expected_version	int	Yes	—
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": "update_commentary",
  "arguments": {
    "commentary_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "text": "Revenue beat plan by 14% after FX rebase; SaaS expansion remains the primary driver.",
    "expected_version": 1,
    "change_note": "Revised after FX rebase"
  }
}

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 14% after FX rebase; SaaS expansion remains the primary driver.",
    "version": 2,
    "archived_at": null,
    "archived_by": null,
    "created_at": "2026-04-28T10:00:00+00:00",
    "updated_at": "2026-04-28T10:05:00+00:00"
  }
}

Notes

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