update_collab

Writes to your heyBTW workspace: it changes only the settings you send on one of your own collabs (and its target spec, if you pass one). It sends nothing and never writes to the event on the event platform.

The same edit the dashboard’s Edit details does. Reach for it when an event’s details change: the time moves, the venue is added, the event is renamed, or create_collab assumed an end. Follows the heyBTW MCP rules.

When to use it

“The dinner moved to 7pm, same night.”
“Add the venue: Foreign Cinema, Mission St.”
“Our RSVP target for the summit is 150.”
“The end time was a guess. It actually ends at 10.”

Parameters

Send only the fields that change.

Parameter	Type	Required	Notes
`channel_id`	string	Yes	The collab, from list_events or create_collab.
`client_request_id`	string	Yes	A fresh hyphenated UUID for this edit.
`name`	string	No	One line, at most 200 characters.
`event_start`	string	No	RFC 3339 with an offset, or a local time read in the `timezone` you send or the collab already holds. A time with neither is refused, never guessed. A local time a daylight-saving change skips or repeats is refused with the two times it could mean.
`event_end`	string	No	Same rule as `event_start`. To move an event past its stored end, send both together.
`timezone`	string	No	IANA zone name (`America/Chicago`), never an offset. Sets or changes the zone and never moves the start or end. A zone cannot be cleared. Send it only when the person told you or the event page states it.
`location`	string	No	One line, at most 120 characters.
`region`	string	No	One line, at most 120 characters.
`rsvp_target`	integer	No	A whole number.
`landing_page_url`	string	No	One https link, at most 2048 characters, no user name or password, no parameter named like a key, token, secret, password or credential. heyBTW never opens it.
`clear_fields`	string[]	No	To empty `location`, `region` or `landing_page_url`. Never send a blank instead.
`target_spec`	object	No	The block save_target_spec takes at collab scope. Replaces this collab’s spec whole and keeps the prior version. Can be sent alone.
`contract_version`	string	No	Omit for v1, the only version advertised.

Workflow

There is no preview step. One call applies the edit.

Confirm the change with the user

Send only the fields that change. Re-sending a value create_collab assumed (an end it defaulted) confirms it: the field comes back applied and its origin becomes user_stated. So send only what you mean to state.

Generate a fresh client_request_id

On a transport error, retry with the SAME id: a committed edit is replayed (idempotent_replay: true), never repeated. Reusing the id for a different edit is refused. An edit that wrote nothing does not consume the key.

Read fields back to the user

Every field you sent comes back in data[0].fields with a status. Report each refused field and its reason.

Platform-owned fields are refused

A collab tied to a Luma, Splash or Zuddl event, or imported from a provider’s public page, has its name, dates, time zone, location and landing page owned by that platform, which rewrites them on its next import or sync. A different value for one of those is:

returned in fields as {"field": ..., "status": "refused", "reason": "provider_owned", "provider": "luma" | "splash" | "zuddl"},
reported as a partial_coverage gap (“Collab fields owned by the event platform were not changed”), so status is partial,
NOT saved. The fields the platform does not own (region, rsvp_target) are still saved.

Tell the user to make that change on the event platform itself.

Response

The shape below is from the contract and the code (tools/update_collab.py, collab-write-contract.json). A success was not captured live, because this tool edits a real collab.

Field	Meaning
`channel_id`	The collab.
`event_name`, `event_date`, `event_end`	Name, start and end after the edit.
`event_tense`	`upcoming`, `live` or `past`, read exactly as list_events reads it.
`timezone`, `location`, `region`, `rsvp_target`, `landing_page_url`	As stored after the edit.
`outcome`	`updated` or `no_change`.
`fields`	One entry per field you sent: `applied` (saved), `unchanged` (it already held that value) or `refused` (not saved, with `reason` and `provider`).
`sync_window`	`rederived` (the data-collection window was recalculated from the new dates) or `kept` (a window set by hand in heyBTW was kept and still covers the new dates). Null otherwise.
`idempotent_replay`	true when this answer replays an earlier committed edit.
`target_spec`	Present when you passed one: what was saved and any item left out.
`target_spec_geography`	After a `location` edit or a new spec: which city the spec serves, and `from: collab` (this collab’s spec pinned it) or `from: default` (the collab’s location).

A time edit moves the start and end everywhere at once, so list_events, get_event_details and the dashboard agree.

Rules the agent must follow

Change only these eight settings (plus the target spec). Briefs, drafts and event framing go to save_event_context; a new event goes to create_collab.
Never guess a time zone from an offset or a place.
To move an event later than its stored end, send event_start and event_end together. A lone event_start after the stored end is refused, naming that end.
Report every refused field to the user, with the platform named. Never say a refused change was saved.
This tool never edits the description, authored context, cost, rep, data-collection window, sign-ups, roster, partners or Playbook, and never touches the event on the event platform.

Errors and gaps

Code	What to do
`invalid_parameter`	Fix the named parameter and retry.
`entity_not_found`	A partner’s collab, the demo collab or an unknown id. Only the workspace’s own collabs can be edited.
`partial_coverage` gap	Platform-owned fields were refused. The rest of the edit was saved.
`insufficient_scope`	The OAuth token lacks `mcp:tools:write`. Nothing changed.
`internal_error`	Retry once with the SAME `client_request_id`.
429	Honor `Retry-After`. 30 requests per 5 s, 60 per minute, 1000 per day per workspace.

Trimmed from a real call with no arguments today:

{
  "tool": "update_collab",
  "status": "error",
  "data": null,
  "error": {
    "code": "invalid_parameter",
    "message": "A tool parameter is invalid",
    "what_failed": "A tool parameter (`channel_id`) is not valid for this tool.",
    "what_to_check": "The `channel_id` argument of this call.",
    "what_to_do": "Correct `channel_id` and retry.",
    "retryable": false
  }
}

create_collab
save_event_context, for briefs and drafts
archive_collab, to remove a collab
Playbook: Invite sprint

Get started

How heyBTW MCP works

Playbooks

Tools: orientation

Tools: events and rosters

Tools: people and invites

Tools: after the event

Tools: accounts and partners

Tools: pipeline

When to use it

Parameters

Workflow

Platform-owned fields are refused

Response

Rules the agent must follow

Errors and gaps

​When to use it

​Parameters

​Workflow

​Platform-owned fields are refused

​Response

​Rules the agent must follow

​Errors and gaps

​Related

When to use it

Parameters

Workflow

Platform-owned fields are refused

Response

Rules the agent must follow

Errors and gaps

Related