Propose meeting
propose_meetingCreate the meeting: places one tentative, opaque hold per (slot × host) on the host's calendar — reversible, invisible to the invitee, auto-released on expiry — and STAGES the invitee's pick-a-time email. This tool itself NEVER emails anyone. BEFORE calling, topic AND agenda MUST be confirmed with the user in chat (ONE confirmation: "Good to go, or want to tweak?") — the invitee reads both on the invite they receive after picking. Keep names OUT of the topic ("Intro call", not "Call with Sarah"); write the agenda in second person to the invitee. slots: exactly 3, passed back verbatim from find_times (opaque ISO identifiers — never reformat them); pass deliberately busy slots' starts_at in busy_override_starts so they are kept. co_host_emails is for WORKSPACE MEMBERS only (holds land on their calendars too); the invitee goes in invitee_email, CCs in additional_invitee_emails; a non-member matching a known contact is dropped (dropped_co_hosts) — relay it. Link account_id / contact_id / opportunity_id when known (resolve via search first; never invent ids). AFTER calling: it returns the meeting's full state, picker_url and staged_invite_preview. The user's go-ahead on the content was already the authorization to send, so in the SAME turn call send_meeting_invite — do NOT ask a second time and do NOT treat staging as a separate approval gate. Withhold the send ONLY if the user explicitly said to hold it (then show staged_invite_preview and wait) or in shareable mode (no invitee_email — hand over picker_url). Never send without a clear human go. Full choreography and signed_in_as: capable://guide/scheduling.
When to use: After find_times, once the user has okayed the topic + agenda. Holds land on every host's calendar and the invite is staged; the content okay is the go-ahead, so call send_meeting_invite in the same turn unless the user said to hold it.
Example: Set up the meeting with those three times — topic and agenda as we agreed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slots | Yes | Exactly 3 slots, byte-identical from find_times output. | |
| topic | Yes | Short subject — becomes the calendar invite title and the picker heading. E.g. "Intro call", "Portfolio review", "Partnership next steps". No participant names. | |
| agenda | Yes | Goes into the calendar event description; the invitee reads it. Second person, 2–4 sentences, no invitee name. | |
| account_id | No | Link the meeting to an account in your workspace. | |
| contact_id | No | Link the meeting to a contact (usually the invitee). | |
| window_end | No | Forward the window_end you gave find_times (ISO 8601) — stored with window_start as the meeting's search window for reschedule context. | |
| duration_min | Yes | Meeting duration in minutes — must match the find_times call. | |
| invitee_name | Yes | Primary invitee's full name. | |
| window_start | No | Forward the window_start you gave find_times (reschedule context). | |
| invitee_email | No | Primary invitee's email. OMIT for shareable mode — the picker URL comes back for the user to share manually, and the invitee enters their email when they pick. | |
| co_host_emails | No | WORKSPACE MEMBERS who co-host: holds land on their calendars too, and the confirmed event includes them. WORKSPACE MEMBERS ONLY — never the external invitee (the invitee goes in invitee_email / additional_invitee_emails, not here). A non-member address that matches a known workspace contact is dropped and the meeting is created without it. | |
| opportunity_id | No | Link the meeting to an opportunity. | |
| invitee_company | No | Primary invitee's company name, stored on the meeting; it appears in the host's booked notification and is matched by meeting search. | |
| expiration_hours | No | Hours before the held times auto-release if the invitee doesn't pick. Defaults to the host's saved default. | |
| busy_override_starts | No | ISO `starts_at` values (from `slots`) that the host DELIBERATELY chose over a busy time on their (or a co-host's) calendar — the find_times card flags these with `busy_override` after the host drops a slot onto a visible busy band. Pass them here ONLY after you've given the user a heads-up (a light note for the host's own busy; a STRONGER one — "only if you've cleared it with them" — for a co-host's). A start in this list is kept-while-busy (its hold is placed and honored at the invitee's confirm); a busy slot NOT in this list is a race and is dropped. Omit when no slot overrides a busy time. | |
| additional_invitee_emails | No | Secondary invitees — CC'd on the picker email and added to the calendar event; only the primary invitee picks. Requires invitee_email. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| slots | No | ||
| meeting | No | ||
| guidance | No | ||
| proposed | No | ||
| timed_out | No | ||
| picker_url | No | ||
| signed_in_as | No | ||
| dropped_slots | No | ||
| repairs_flagged | No | ||
| dropped_co_hosts | No | ||
| staged_invite_preview | No |