---
title: Agents schedule for you
description: "Ask venom, Chat or Claude to find time with someone: it finds real free times, holds them, sends the options in their time zone with a one-tap link, and books the one they pick. The same Share availability works by hand from the week view."
section: calendar
order: 50
audience: [user, builder, agent]
sources: [services/nodejs-cloud/lib/calendar/offers.ts, services/nodejs-cloud/lib/calendar/offers-pure.ts, services/nodejs-cloud/lib/calendar/offers-http.ts, services/nodejs-cloud/lib/calendar/mcp.ts, services/nodejs-cloud/components/calendar/ShareAvailability.tsx, services/nodejs-cloud/migrations/0208_calendar_offers.sql, packages/harness/src/compat/mcp.ts, cli/src/library-command.ts]
features: []
---

You say: "find 30 minutes with Dana next week, mornings preferred, send her three options on WhatsApp". The agent
finds real free times across every calendar you connected, holds them so nothing else takes them, and writes the
options in Dana's time zone and language with a link she can tap to book. When she answers, it books the time she
picked and lets the other times go.

This works from venom in your terminal, from Chat, from Claude or any other MCP client connected to your workspace, and
by hand from the week view's **Share availability** button.

## What an offer is

An **offer** is a few free times proposed to one person:

- **Picked well.** The times come from your real availability (working hours, every connected calendar, buffers,
  notice). The part of the day you prefer comes first, the times are spread across days, and no day gets more than two.
  Nothing is offered inside the event type's notice.
- **Held.** Each time is held, so your booking pages and other bookings skip it. By default the holds last 48 hours
  (`hold_hours`, up to 14 days).
- **One link.** The offer has a single-use link that shows only the times still on offer. Picking one books it and
  frees the others at once.
- **Kept honest.** If busy time lands on a held time (you booked something else by hand), that time drops out of the
  offer and its link. When the offer expires, every hold goes.
- **In their words.** The message is in the invitee's time zone and language. The zone comes from what People knows
  (their last booking, the country of their number) unless you name one.

The message looks like this:

```text
Here are a few times that work for me:
Tue 10 Nov: 10:00, 10:30
Wed 11 Nov: 15:00 (Singapore time)
Pick one here: https://cloud.example.com/meet/l/…
```

## Nothing goes out by itself

- **From the app,** you press **Send** yourself. WhatsApp, Telegram and SMS go through [Comms](/docs/comms) from your
  org's own numbers; email goes through the org's mail provider (Support settings).
- **From an agent,** a send follows Comms' approval rules: it waits as `pending_approval` until a person approves it in
  Settings, Comms. If an admin opened a Comms profile to agents, an agent that names that profile sends at once.
- **Replies don't book.** When the person answers ("Wed 3pm works"), the answer lands in your bell as a suggestion:
  "Dana replied 'Wed 3pm works'. Book Wed 11 Nov 15:00?". You press **Book** or **Dismiss**. If the reply names one of
  the offered times, it's picked for you; otherwise you choose. An agent may book after the person chose, with
  `calendar_offer_accept`. Nothing is booked from free text on its own.

Replies are matched to the offer by the address it was sent to, or by the person's handles in People. Opted-out
numbers are never contacted, and quiet hours hold a send until they end.

## Share availability, by hand

On the week view, **Share availability** opens a short form:

1. Pick the meeting (one of your event types) and the times: **Next 3 mornings**, afternoons, evenings, or **Pick
   times myself** to click free times.
2. Set their time zone, the language and how long to hold the times.
3. Press **Hold and write the message**. Copy the text, or choose WhatsApp, Telegram, SMS or Email, enter the
   address and press **Send**.

**Sent** lists your open offers, with any reply waiting and **Book**, **Dismiss** and **Withdraw**. The bell links
straight to the offer a reply is about.

## Example: venom in the terminal

When you're logged in to Venom Cloud (`venom cloud login`), venom registers your workspace's calendar MCP server as
`calendar`, beside `globe`, `tasks` and the other Venom products
([What agents connect to by default](/docs/cloud/agent-defaults)). Its tools load only when the agent searches for them, so the prompt stays the
same. Set `VENOM_CALENDAR_MCP=off` to leave it out.

```text
> find 30 minutes with Dana next week, mornings preferred, send her three options on WhatsApp

● calendar_offer_create  person_id: 5c1e…, duration: 30, prefer: morning, count: 3, from: 2026-11-16, to: 2026-11-21
  Offer 9f2a… (open, held until 2026-11-12T09:14:00Z):
  - 2026-11-17 09:30–10:00 · 2026-11-17T01:30:00.000Z
  - 2026-11-18 10:00–10:30 · 2026-11-18T02:00:00.000Z
  - 2026-11-19 09:00–09:30 · 2026-11-19T01:00:00.000Z

● calendar_offer_send  offer_id: 9f2a…, channel: whatsapp
  Asked to send by whatsapp to …4567: it waits for a person to approve it in Settings, Comms.

I've held three mornings in Dana's time (Singapore) and queued the WhatsApp message. Approve it in Settings, Comms
and it goes out. When she answers, I'll book the time she picks.

> she said Wednesday works

● calendar_offer_accept  offer_id: 9f2a…, start: 2026-11-18T02:00:00.000Z
  Booked: Intro call, 2026-11-18T02:00:00.000Z → 2026-11-18T02:30:00.000Z with Dana Lim (confirmed)

Booked Wednesday 18 Nov, 10:00 her time. The other two times are free again.
```

## MCP tools

Product `calendar`, on `/workspace/mcp/calendar` (scopes `calendar:read` and `calendar:write`):

| Tool | Does |
|---|---|
| `calendar_slots_find` | Free times. `prefer` puts a part of the day first, `spread: true` spreads them across days (at most 2 a day), and `person_id` shows them in that person's zone. |
| `calendar_offer_create` | Picks and holds times (or takes the `slots` given), mints the link and returns the offer with its text. Takes `event_type_id` or `duration`, `person_id` or `invitee`, `from`/`to`, `count`, `prefer`, `hold_hours`, `time_zone`, `locale`. |
| `calendar_offer_list` | Your offers, newest first, with any reply waiting. |
| `calendar_offer_get` | One offer: the times still held, the link, the text, sends and the reply. |
| `calendar_offer_cancel` | Withdraws it: the holds go and the link stops working. |
| `calendar_offer_send` | Sends it through Comms (`whatsapp`, `telegram`, `sms`) or email, to the person's channel of choice or to `to`. An agent's send waits for approval unless `profile` names a Comms profile open to agents. |
| `calendar_offer_accept` | Books the offered time the person chose and releases the rest. One booking per offer: a retry with the same time returns it. |
| `calendar_offer_dismiss` | Clears a reply suggestion; the offer stays open. |

The same calls are on the REST API under `/api/v1/calendar/offers` (see [the REST twin](/docs/developers/rest)),
and the app uses `/api/workspace/calendar/offers`:

| Method and path | Does |
|---|---|
| `GET` / `POST /api/workspace/calendar/offers` | List your offers (`status`, `person_id`, `limit`), or make one |
| `GET /api/workspace/calendar/offers/{id}` | One offer |
| `POST /api/workspace/calendar/offers/{id}/send` | Send it now (you pressed Send): `{channel?, to?}` |
| `POST /api/workspace/calendar/offers/{id}/accept` | Book `{start, invitee?}` |
| `POST /api/workspace/calendar/offers/{id}/cancel` | Withdraw it |
| `POST /api/workspace/calendar/offers/{id}/dismiss` | Clear the reply suggestion |
