Find free time
well_find_free_timeFind when the user is free, or when the user and other workspace members are all free. Use it when the user asks when they are free, which slots are open, or when a meeting could fit. It reads the user's own synced calendars: every timed event that is not cancelled blocks its time, and all-day events do not. It returns the free slots between 09:00 and 18:00 in the user's time zone, or between the working_hours the user named. To find a time that suits workspace members too, pass their person ids in member_person_ids: it then returns only the slots where the user and every connected member are free, and a member's private meeting blocks time like any other. It never shows what anyone's events are, only the shared free slots: time outside a slot is busy and the reason is never given. A member whose calendar is not connected to Well is listed in members_not_connected and is not counted: tell the user that member's free time was not checked. Someone outside the workspace, such as a guest, cannot be checked: say so and do not guess when they are free. If truncated is true, some calendar events could not be read: tell the user the check is incomplete and give incomplete_check.message; never suggest a time after incomplete_check.checked_until. If capped_range is set, the range was longer than 31 days and only its first 31 days were searched: tell the user the range was shortened and to which date, and offer to search the rest; never suggest a time beyond searched_to_date. If the result has a note, give it to the user as it is: it invites them to connect their own calendar.
The result's connection describes the user's own calendar. Its state is one of "connected" (say nothing about it), "syncing" (the first sync has not finished: say the result can be incomplete), "stale" (say the result can be out of date and give last_synced_at as the time of the last update), "needs_reconnect" (say Well lost access to the calendar, that the result holds only what was synced before, and give reconnect_link once) or "not_connected" (say the user's own calendar is not connected and give reconnect_link once, unless the note already gave it). When the state is not "connected", never call the result complete or up to date, and never call a time free on its strength alone. A null connection means the state could not be read: say nothing about it.
When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to_date | No | Last day to search, inclusive; defaults to from_date; a range over 31 days is shortened to its first 31 days and the result says so | |
| from_date | Yes | First day to search, YYYY-MM-DD, in the user's own time zone | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which. | |
| working_hours | No | Only when the user names other hours than 09:00-18:00, as HH:MM | |
| 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. | |
| 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. | |
| min_slot_minutes | No | Shortest free slot to return, in minutes; defaults to 30 | |
| member_person_ids | No | Person ids of workspace members to find a shared free time with, at most 5; look a member up with well_query_records, or take the owner_person_id of their calendar from well_list_calendars. Leave it out for the user's own free time |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | ||
| error | No | ||
| slots | Yes | ||
| success | Yes | ||
| timezone | Yes | ||
| truncated | Yes | ||
| connection | Yes | ||
| capped_range | Yes | ||
| 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. | |
| incomplete_check | Yes | ||
| members_included | Yes | ||
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| members_not_connected | Yes | ||
| 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. |