Set timezone
well_set_timezoneSave the time zone the caller is in now. Call it whenever the person states where they are or which zone they are in now, including travel and a passing correction ("I'm in Hawaii right now", "it's not the morning here", "I'm in Lisbon this week", "I moved to Lisbon"), and when the person agrees to update the saved zone after you offered to. Call it before you answer: read their times and later replies in the saved zone, and never reply only with clock arithmetic. It saves the caller's own zone only, never another member's.
zone is an IANA city zone such as "Pacific/Honolulu" or "Europe/Lisbon". If the user names only a country or an abbreviation, ask which city they are in. UTC and abbreviations such as "EST" or "CET" are refused. Well reads the user's times in this zone.
The result holds zone (now in force), previous_zone, and calendar_zone: the zone the user's calendar last showed, or null. When calendar_out_of_date is true, the calendar still shows calendar_zone: tell the user their calendar is out of date and shows that zone. Never change the calendar yourself. A later change of the calendar's own zone or a visit to the web app can replace the saved zone.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| zone | Yes | The IANA city zone the user is in, e.g. "Pacific/Honolulu". Never UTC or an abbreviation. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| idempotency_key | No | Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| zone | No | The zone now saved. | |
| error | No | ||
| success | Yes | ||
| calendar_zone | No | The zone the user's calendar last showed, or null when none was read. | |
| previous_zone | No | The zone saved before this call, or null when none was. | |
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| calendar_out_of_date | No | True when the calendar still shows another zone than the saved one. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |