Skip to content

Tools reference

Clippy's Revenge gives Claude Code thirteen tools. You normally don't call them yourself: you ask Claude in plain language and it picks the right tool. This page lists every tool and its parameters, which is useful when you want to know what Claude can and can't do.

Tool What it does
search_emails Search the local index
get_message Read one email in full
get_attachment Save one attachment to disk
save_attachments Save attachments of all emails matching a search
attachment_link Make a one-time download link for one attachment, for WSL or another shell
create_draft Save a new email draft
reply_draft Save a reply draft
list_events List calendar events
find_free_times Suggest meeting times from free/busy
create_meeting_draft Save a meeting unsent in your calendar. Nothing is sent
index_status Show index and sync state
email_stats Count mail by sender, domain, folder or time
query_index Run one read-only SELECT over the index

There is no send_meeting_invite tool. Older versions had one; it was replaced by create_meeting_draft, which never sends.

What the tools can and can't do

  • Nothing is ever sent. Clippy has no send function. Mail tools only save drafts in your Drafts folder, and the meeting tool only saves a meeting unsent in your calendar. You review and send both in Outlook.
  • Nothing is deleted. No tool deletes or moves your mail. The only mail Clippy ever moves is an outdated AI draft of its own, and that is not a tool: see Outdated drafts.
  • Read-only tools. search_emails, get_message, index_status, email_stats, query_index, list_events and find_free_times change nothing. get_attachment and save_attachments write files to disk, only inside the allowed folders. attachment_link also creates a file, but only a short-lived private copy for a download link. create_draft, reply_draft and create_meeting_draft create items in Outlook.
  • Which tools need Outlook running. search_emails, email_stats, query_index and index_status use the local index and work while Outlook is busy or closed. get_message falls back to Outlook for mail that isn't indexed. Attachments, drafts, list_events, find_free_times and create_meeting_draft always need Outlook.

Common conventions

  • mailbox: empty means your own mailbox. An SMTP address means that shared mailbox, which must be enabled in the tray. Search tools (search_emails, email_stats, query_index, save_attachments) also accept all. Tools that take an id find the mailbox from the id.
  • Dates: ISO date (2026-03-01) or date-time (2026-03-01T14:30), in local time. A space may replace the T, seconds are optional, and a date-time ending in Z, +hh:mm or -hh:mm is honored. A date-only end date includes the whole day.
  • Numbers out of range: limit, offset, top, max_rows, days_ahead and max_suggestions are moved into their range without an error. days (list_events), duration_minutes, earliest_hour and latest_hour give an error instead.
  • Recipients: "Last, First <address>; other-address". Separate people with ;, never ,, because names are often written "Last, First".
  • File paths: every path must be inside an allowed folder. See file access. Relative paths resolve under the attachment folder (see Settings). A refused path returns an error that names the allowed folders, and is recorded in Activity.
  • Errors: tools return a message that tells Claude what to fix. The most common ones are in Errors Claude may see.

Reading mail

search_emails

Searches the local index. It is fast and works while Outlook is busy. All filters are optional and combine with AND. Results are newest first. Only synced mail is indexed; use index_status to check coverage.

Parameter Type Description
query string Free text over subject, body, sender, recipients and attachment file names. Words are ANDed. Use OR between words for alternatives, "quotes" for a phrase, and a trailing * for a prefix.
sender string Substring of the sender's name or email address
recipient string Substring of To or CC. Also accepts a list like Name <address>; other-address, which matches mail involving any of them
subject string Substring of the subject
date_from string Earliest date, inclusive
date_to string Latest date, inclusive
folder string inbox, sent (or sent items), or another indexed folder path such as Inbox\Projects (not case-sensitive, / works as well as \). Subfolders are not included. Empty means all folders
has_attachment bool true: only mail with real (non-inline) attachments; false: only mail without
attachment_name string Substring of any attachment file name (inline images included)
attachment_ext string Exact attachment extension, with or without the dot (pdf or .pdf)
unread bool true: only unread; false: only read
mailbox string Empty, a shared mailbox address, or all
limit int Maximum results, 1 to 200 (default 50)
offset int Results to skip, for paging (default 0)

The text filters (sender, recipient, subject, attachment_name) ignore upper and lower case. A blank text filter means no filter. A recipient that contains ; or < is read as a list of people (up to 50 of them are used). Outlook's default folders keep their English names in the index (Inbox, Sent Items, Drafts, Deleted Items), also when Outlook shows them in another language.

Each result has id, mailbox, folder, date (local time), from, sender_email, to, subject, has_attachments, attachments[] (position, filename, size, inline) and snippet. With query, the snippet shows the matching words between **; otherwise it is the start of the body. Pass a result's id to get_message to read the body.

Errors: a date that can't be read gives date_from "<text>" is not a valid date. Use an ISO date like 2026-03-01 or a date-time like 2026-03-01T14:30 (local time).

Example request

"Find unread mail from accounting with a PDF attached since 1 March."

Claude calls search_emails with sender="accounting", unread=true, attachment_ext="pdf", date_from="2026-03-01".

get_message

Returns one email in full: headers, complete body and attachment list. It reads the index first. If the email isn't indexed yet, it reads it live from Outlook, which needs Outlook to be running.

Parameter Type Description
id string, required The id of an email, as returned by search_emails

The result has id, mailbox, folder, date, from, sender_email, to, cc, subject, unread, has_attachments, attachments[], internet_message_id, body and source (index or outlook). A very long email is stored cut at 2,000,000 characters and ends with the line [Clippy indexed only the first 2,000,000 characters of this email.]. If Outlook has to be asked and isn't running, the error is Outlook is not running. Ask the user to start Outlook (tray → Start Outlook) and try again.

index_status

Shows the state of the local index: per-mailbox counts, oldest and newest indexed mail, last sync and whether the first backfill is complete. It also says whether Outlook is running and what Clippy is doing right now. Use it to explain why a search found nothing, or to check indexing progress.

Parameter Type Description
mailbox string Optional shared mailbox address. Empty means all configured mailboxes

The result has state (what Clippy is doing: Idle, Serving, Drafting, Paused, Purging, Syncing, Backfilling, OutlookUnavailable or Error), progress (text such as Inbox (2025-11 → now) 1240/8000, or null when there is nothing to report), outlook_running (true, false, or null before the first attempt) and mailboxes[]. Each mailbox has mailbox, total_emails, folders (count per folder), oldest, newest, db_size_bytes, last_sync and backfill_complete.

email_stats

Counts emails in the local index, grouped, in one call. Use it for questions such as "top 10 people who emailed me last year" or "how much mail do I get per month". It returns counts and names only, never mail text. It is read-only and fast, because the counting runs inside the index.

All the filters of search_emails work here (query, sender, recipient, subject, date_from, date_to, folder, has_attachment, attachment_name, attachment_ext, unread, mailbox), with the same meaning. There is no limit or offset.

Parameter Type Description
group_by string, required What to group by. See the table below
top int Number of groups to return, 1 to 200 (default 10)
order string count: largest groups first (default). key: by key, chronological for month, week and hour, Mon to Sun for weekday
include_cc bool For recipient and recipient_domain: also count CC addresses (default true)
mailbox string Empty, a shared mailbox address, or all

group_by values

Value Key
sender The sender's email address, lower case. name is the display name in the newest email of the group
sender_domain The part of the sender address after the @
recipient Each To address, plus each CC address when include_cc is true. An address counts once per email. name is the display name seen in the newest email
recipient_domain The same, by domain. A domain counts once per email
folder The folder path
month yyyy-MM
week ISO week, yyyy-Www
weekday Mon to Sun
hour 00 to 23

month, week, weekday and hour use your Windows time zone. (unknown) is the group for senders with no valid address. Recipients with no valid address are skipped, so recipient and recipient_domain have no (unknown) group. Any other group_by value returns an error that lists the valid ones.

The result is group_by, mailbox, total (matching emails, not recipient entries), distinct (number of groups), truncated (true when there are more groups than top) and rows. Each row has key, count, first and last (the dates of the oldest and newest email in the group, local time with offset), and name for sender and recipient.

With mailbox="all", the counts of every enabled mailbox are added together by key. An email that is in two mailboxes counts twice.

Example requests

"Who emailed me most in the last year? Top 10 with counts."

Claude calls email_stats with group_by="sender", folder="inbox", date_from one year ago.

"How much mail do I get per month?" is group_by="month", order="key". "Who do I write to most?" is group_by="recipient", folder="sent". "Which companies send me the most mail?" is group_by="sender_domain".

For joins, snippets or any other question that grouping can't answer, use query_index.

query_index

Runs one read-only SQLite SELECT over the local email index. Use it for questions the other tools can't answer in one call: joins, custom grouping and full-text search with snippets. For plain counts, email_stats is simpler. It works while Outlook is busy or closed, and only synced mail is indexed.

Parameter Type Description
sql string, required One SELECT (WITH and VALUES also work). Write values into the SQL; ? parameters are not supported
mailbox string Empty, a shared mailbox address, or all
max_rows int Maximum rows returned, 1 to 1000 (default 200)

Views. The query sees exactly these three views, which hold the same data that search_emails and get_message return.

View Columns
mail id (the id that get_message takes), doc (join key), mailbox (empty for your own), folder, date (local time, yyyy-MM-ddTHH:mm:ss), unix_time (UTC seconds), sender_name, sender_email, to_addrs, cc_addrs (Name <email>; ...), subject, topic (conversation topic), body (plain text), unread (0 or 1), has_attachments (0 or 1, not counting inline images), attachment_names (one file name per line)
mail_fts The full-text index: mail_fts (use it with MATCH, snippet(), highlight()), rank, doc, subject, body, sender_name, sender_email, to_addrs, cc_addrs, attachment_names. Join to mail on doc
mail_attachments doc, position, filename, size, is_inline (0 or 1). Only file names are indexed, never attachment content

For full-text search, filter with WHERE mail_fts MATCH '...' (FTS5 syntax: words are ANDed, OR, NOT, "a phrase", prefix*, column:word) and sort with ORDER BY rank (best first). snippet(mail_fts, n, ...) and highlight(mail_fts, n, ...) take a column number: 0 subject, 1 body, 2 sender name, 3 sender email, 4 To, 5 CC, 6 attachment names. bm25(mail_fts) also works.

Limits

  • One statement only. PRAGMA, ATTACH, every write and every other table are refused, with an error that names what was not allowed.
  • 10 seconds in total, at most 1000 rows (max_rows), at most 100 columns, long text cells cut at 2,000 characters, and about 1,000,000 characters of results in total. The SQL itself may be at most 20,000 characters. On a large mailbox add a LIMIT and a date or folder filter.
  • With mailbox="all" each mailbox is queried separately and the rows are joined with a leading mailbox column. Counts and other aggregates are therefore per mailbox; use email_stats for counts merged across mailboxes.

The result has columns, rows (numbers stay numbers, empty values are null), row_count, truncated, truncated_cells (how many cells were cut) and elapsed_ms. When it stops early it also gives truncated_reason: max_rows (the row limit was reached) or size (the next row would pass the total size limit).

Example queries

Top senders in your Inbox in the last year:

SELECT sender_email, count(*) AS n FROM mail
WHERE folder = 'Inbox' AND unix_time >= strftime('%s','now','-1 year')
GROUP BY sender_email ORDER BY n DESC LIMIT 10

Mail per month:

SELECT substr(date,1,7) AS month, count(*) AS n FROM mail
GROUP BY month ORDER BY month

Full-text search with snippets:

SELECT m.id, m.date, m.subject,
       snippet(mail_fts, 1, '**', '**', '…', 12) AS hit
FROM mail_fts JOIN mail m ON m.doc = mail_fts.doc
WHERE mail_fts MATCH 'budget AND 2026' ORDER BY rank LIMIT 20

PDF attachments by sender:

SELECT m.sender_email, count(*) AS n
FROM mail_attachments a JOIN mail m ON m.doc = a.doc
WHERE lower(a.filename) LIKE '%.pdf' GROUP BY 1 ORDER BY n DESC LIMIT 20

Read-only, by several layers

The query runs on a read-only connection to the index with writing switched off, and every table and column access is checked. Only the three views above can be read, not sync state, settings or anything else in the database. See Security.

The main query_index errors:

Situation Message (shortened)
Empty sql sql is required: one SELECT over the views mail, mail_fts and mail_attachments.
Over 20,000 characters sql is longer than 20,000 characters. Shorten the query.
More than one statement query_index runs exactly one SELECT statement. Remove everything after the first statement.
A write, PRAGMA, ATTACH, another table or column query_index only reads the views mail, mail_fts and mail_attachments with one SELECT. Not allowed here: <what>.
? parameters query_index takes no parameters; write the values into the SQL.
More than 100 columns query_index returns at most 100 columns.
Longer than 10 seconds The query ran longer than 10 seconds and was stopped. Add a date range, a folder or a LIMIT, or use email_stats for counts.
Query needs too much memory The query needs too much memory. Simplify it: fewer nested WITH clauses, fewer or shorter computed columns.
A value over 16 MB A value in the query is too large (more than 16 MB).
SQL syntax or other SQLite error SQL error: <SQLite's message>. query_index reads the views ...
Index not ready (not indexed yet, being rebuilt) The index for <mailbox> isn't available right now. Check index_status.

email_stats errors: group_by must be one of sender, sender_domain, recipient, recipient_domain, folder, month, week, weekday, hour. and order must be count or key.

Attachments

Attachments are saved with a live call to Outlook, so Outlook must be running. Files are never overwritten: a duplicate name becomes name (2).ext.

get_attachment

Saves one attachment of an email to disk and returns its path, file name and size.

Parameter Type Description
id string, required The id of an email, from search_emails
filename string File name of the attachment (whole name, case-insensitive)
position int 1-based position in the email's attachment list
save_dir string Folder to save into. Empty means the attachment folder. Relative paths go under it. Must be inside an allowed folder

If you pass neither filename nor position, Clippy takes the only attachment, or the only real (non-inline) one when the rest are inline images. Otherwise the error lists the attachments (for example This email has 3 attachments. Pass filename or position to choose one: 1 "report.pdf", 2 "notes.docx", 3 "image001.png" (inline).) so Claude can choose; the list shows at most 20. If you pass both, they must agree. If two attachments have the same name, pass position. Inline attachments can be fetched by name or position. The returned filename is the attachment's original name; the saved file may be called name (2).ext, and characters Windows doesn't allow in file names become _.

An attached email that has no file name is listed as <subject>.msg (or (no name).msg); any other attachment without a name is listed as attachment-<n>. Names recorded in the index by older versions, without the .msg, still match in get_attachment, save_attachments and attachment_link.

save_attachments

Finds emails with the same filters as search_emails and saves their attachments into one folder. attachment_name and attachment_ext also choose which attachments are saved. Inline images are skipped unless include_inline is true. Returns saved[], failed[], count (number saved) and a note when nothing matched or nothing was eligible. Each saved entry has id, mailbox, position, filename, path and size; each failed entry has id, mailbox, position, filename and error. One failure doesn't stop the rest, except when Outlook closes or stops responding: then every attachment not yet saved is listed in failed with that error. Emails are saved newest first. The note is No emails matched the filters. or <n> email(s) matched, but none had attachments to save. Inline attachments are skipped unless include_inline is true.

Parameter Type Description
save_dir string Folder to save into. Empty means the attachment folder
query, sender, recipient, subject, date_from, date_to, folder, has_attachment, attachment_name, attachment_ext, unread, mailbox Same as in search_emails
include_inline bool true: also save inline attachments such as embedded images (default false)
limit int Maximum number of emails, 1 to 200 (default 50)
offset int Emails to skip, for paging

Makes a one-time download link for one attachment of an email. Use it when Claude Code runs in WSL (or any other shell) and should get the attachment as a real file in its own working folder, without you copying it over from the Windows side.

Tool Where the file goes Result
get_attachment A Windows folder inside the allowed folders A Windows path (C:\...)
save_attachments One Windows folder, for many emails A list of Windows paths
attachment_link The shell's current folder, through curl A link and a curl command

The file's bytes never pass through Claude: the tool returns only the link, and the shell downloads the file. Nothing about the attachment's content is indexed or put into the conversation. get_attachment is unchanged and stays the right tool when you want the file on the Windows side.

Setup needed once: the shell must have CLIPPY_TOKEN set, because the download needs your auth token as well as the link. See Set CLIPPY_TOKEN in WSL.

Parameter Type Description
id string, required The id of an email, from search_emails
filename string File name of the attachment (whole name, case-insensitive)
position int 1-based position in the email's attachment list

Choosing the attachment works exactly as in get_attachment: with more than one attachment, pass filename or position; with neither, the error lists the attachments so Claude can choose; with both, they must agree; inline attachments can be fetched by name or position. There is no save_dir, because the file is not saved to a folder you choose.

Result:

Field Meaning
url http://127.0.0.1:<port>/files/<link token>. The link token is 43 characters of letters, digits, - and _
filename The attachment's original name
size Size in bytes of the copy Clippy made
expires_at When the link stops working: 10 minutes after it was made, in your local time with the offset, for example 2026-11-15T14:35:00+01:00
curl The command to run in the shell (below)
note One download only. If curl answers 401, CLIPPY_TOKEN isn't set in this shell: ask the user to copy the auth token from the Clippy tray menu and add export CLIPPY_TOKEN=<token> to ~/.bashrc.

The curl command has this shape:

curl -fsS -H "Authorization: Bearer $CLIPPY_TOKEN" -o 'Q3 report.pdf' 'http://127.0.0.1:8765/files/<link token>'

The real token is never in the result: the shell fills in $CLIPPY_TOKEN itself. The file name in the command is made safe to put in single quotes: characters Windows doesn't allow in file names and every ' become _, and a leading - or . is replaced by _, so the name can never be taken for an option or be a hidden file. The file is saved with that name in the folder where the command runs, and an existing file with the same name is overwritten by curl, so ask Claude to run it in the folder you want.

How the link behaves:

  • One download only. The first successful request uses the link up. Running the same command again gives 404.
  • Expires after 10 minutes. After that the link is gone, even if never used.
  • Needs both tokens. The request must carry your bearer token ($CLIPPY_TOKEN) and the link token. A request without the bearer token gets 401 and does not use the link up.
  • Made at once. Clippy saves the attachment through Outlook when the link is made, not when it is downloaded. The download then works even if Outlook closes or gets busy, and Outlook problems show up as normal tool errors instead of a curl failure.
  • Gone after use. Clippy deletes its private copy right after the download (finished or interrupted), when the link expires, and when Clippy starts or exits. Changing the port or restarting the server also drops every open link, because the links name the old port. See Security.
  • The download is GET only (other methods get 405) and the whole file is always sent.

Expired links don't count. A link whose download is still running counts until the download ends.

Limit Refusal text
100 MiB per attachment The attachment is <n> MB; attachment_link handles up to 100 MB. Use get_attachment to save it on the Windows side. (<n> is the size rounded up)
At most 10 open links Too many open download links (10). Download them or wait until they expire (10 minutes), then try again.
At most 200 MiB of open links in total The open download links already hold 200 MB. Download them or wait until they expire, then try again.
At most 20 links per rolling 10 minutes Too many download links in the last 10 minutes (20). Try again in <n> min. (<n> is whole minutes, at least 1)

Before Clippy asks Outlook for anything, it checks the number of open links, the open bytes (refused when they already reach 200 MiB) and the rate, in that order. The size limit is checked when Outlook reports the attachment's size, and again on the saved copy. When the copy is registered, all four are checked once more (size first); a link that would push the open total over 200 MiB is refused then, and the copy is deleted.

Other errors:

Situation What the message says
No id id is required. Use the id from search_emails.
Outlook isn't running, busy, or the email is gone The same messages as in Errors Claude may see
Several attachments and none chosen, or a name that doesn't match The attachment list, as for get_attachment
The private folder can't be used Clippy can't use its private download folder. Use get_attachment instead.
The server is restarting Clippy's server isn't running, so it can't make a download link. Try again in a moment.
Example request

"Get the PDF attached to the email about the Q3 numbers into this folder."

Claude finds the email with search_emails, then calls attachment_link with its id and filename="Q3 report.pdf". It gets back size: 482113, an expires_at ten minutes from now and the curl command above. In WSL, Claude runs the command and Q3 report.pdf appears in the current folder. If you ask it to run the same command again, curl fails with 404, because the link was single use. Ask for a new link instead.

Drafts

Drafts are only ever saved to the Drafts folder. You review and send them from Outlook. Nothing is sent by these tools. Drafts made by these tools carry a hidden marker that says Clippy's tools created them (AI drafts have their own marker, see AI drafts).

create_draft

Creates a new draft. The default signature is added below the text when you have one set. Every attachment path is checked before anything is created; if one is refused, nothing is created, and the error ends with Nothing was created. Checks run in this order: mailbox (all is refused), recipients (to needs at least one), attachments. Line breaks in the subject become spaces.

Parameter Type Description
to string, required Recipients, separated by ;
subject string, required Subject line
body string, required Plain text, or an HTML fragment when html is true
cc string Same format as to
bcc string Same format as to
html bool true when body is HTML (default false)
attachments string[] Paths to existing files in allowed folders. Relative paths resolve under the attachment folder
mailbox string Empty means your own mailbox, or an enabled shared mailbox. The draft goes to that mailbox's Drafts folder and is sent on its behalf

Returns id, subject, mailbox (empty for your own) and signature_added.

Example request

"Draft an email to my manager asking for the Q3 numbers."

Claude calls create_draft with to set to your manager's address, subject="Q3 numbers" and a body. The draft appears in Drafts. You edit and send it yourself.

reply_draft

Creates a reply draft to an email. The body is placed above the quoted original, followed by your reply signature when one is set.

Subjects start with Re::

Reply subjects start with Re:: (a double colon). This is intentional.

Parameter Type Description
id string, required Id of the email to reply to, from search_emails
body string, required Plain text reply, or an HTML fragment when html is true
reply_all bool true: reply to all recipients (default false)
html bool true when body is HTML (default false)
mailbox string Empty means the mailbox the original is in, or an enabled shared mailbox

Returns id, subject, mailbox and signature_added. mailbox defaults to the mailbox the original email is in.

Calendar

See Calendar and meetings for how these fit together.

list_events

Lists calendar events in a time window, with recurring events expanded into instances. Sorted by start, at most 500. Defaults to the next 7 days.

Parameter Type Description
start string Window start. Default: today 00:00
end string Window end. A date-only end covers that whole day. Default: start plus days
days int Window length in days when end isn't given, 1 to 366 (default 7). Outside that range: days must be between 1 and 366.
mailbox string An enabled shared mailbox's calendar. Empty means yours

The result has the resolved start and end of the window, count, truncated (true when the 500 limit was reached) and events[]. Each event has id, subject, start, end, all_day, location, organizer, is_recurring and busy_status (free, tentative, busy, out_of_office or working_elsewhere). An end that isn't after start gives end must be after start.

find_free_times

Finds times when everyone is free, from Outlook free/busy. Nothing is booked. Returns numbered suggestions (whole free blocks) with start, end, adjacent and a ready-to-show text, and offers: options of exactly duration_minutes, with offer_text ready to paste into an email. People whose free/busy can't be read (for example, people outside your organization) are listed in unknown_attendees and ignored.

Ranking. Times right before or after one of your meetings come first (within 15 minutes, on the same day), then times next to a tentative meeting, then everything else, each group in date order. adjacent says which: busy, tentative or none. Free/busy can't tell a meeting from other busy time, so "next to a meeting" means "next to busy time". Without your own calendar (include_me=false, or your free/busy can't be read), every time is none. Whether tentative time blocks a slot follows Tentative counts as busy in Settings, and the zone label (PT below) follows Time-zone label.

Offers. offers and offer_text hold at most max_suggestions options of exactly duration_minutes, in the same ranking, one per line. Options are taken in 30-minute steps from the start of each free block (plus one that ends exactly at its end) and never overlap each other:

1. Tue 11/18  10:00–11:00 PT  (19:00–20:00 CET)
2. Wed 11/19  14:00–15:00 PT  (23:00–00:00 CET)

With offer_cet=true (for someone in Europe) each line also shows the time in Central European time, always labelled CET, also in summer. Options between 08:00 and 18:00 CET come first. If there are fewer than wanted, the rest follow in a second list headed Outside European office hours:, numbered on from the first. Each offer has list: main or outside_hours. If your PC is already on Central European time, there is no CET part and no second list. See Meeting times in AI drafts.

Parameter Type Description
recipients string, required Attendees as Name <email>; Name <email>. At most 50. May be empty when include_me is true
duration_minutes int Minimum free block length, and the exact length of each offer, 1 to 1440 (default 60)
days_ahead int Calendar days to search, counted from the day of date_from, 1 to 60 (default 10)
date_from string Start date or date-time. Default: now
earliest_hour int Working-hours start, 0 to 23. Default: from Settings
latest_hour int Working-hours end, 1 to 24, later than earliest_hour. Default: from Settings
business_days_only bool Skip Saturdays and Sundays. Default: from Settings
include_me bool Also check the calendar owner (default true)
max_suggestions int 1 to 20 (default 5). Also the most offers returned
mailbox string Empty means your calendar, or an enabled shared mailbox
offer_cet bool true when the person you are writing to is in Europe: offers also show CET, Europe office hours first (default false)

The result has suggestions[] (n, label, start, end, adjacent), text, offers[] (n, label, start, end, adjacent, list), offer_text, unknown_attendees[] and attendees[] (the people whose free/busy was read, with name and email). start and end are local times with offset, for example 2026-10-15T13:00:00-07:00. With no suggestions, text says why: no readable free/busy, or no free block in the days searched. The server remembers nothing between calls, so to book option N, Claude passes that option's start and end to create_meeting_draft.

If offer_cet is true but the PC has no Central European time zone, the offers have no CET part, and a warning is written to the log once.

Example request

"Find an hour next week for me and the two people on this email. One of them is in Berlin."

Claude calls find_free_times with recipients set to their two addresses, duration_minutes=60, date_from set to next Monday and offer_cet=true, then pastes offer_text into the email it drafts.

create_meeting_draft

Saves a meeting in your calendar without sending it. Clippy never sends anything. You add the Zoom or Teams link in Outlook and send the invite yourself. See Meeting drafts for the whole workflow.

The meeting gets the category Clippy draft invite, is listed in the tray under Draft invites, and counts toward the tray icon's badge. If the invite answers an email, pass reply_to_id and a note is saved in Drafts.

Every recipient must resolve in Outlook, or nothing is created. In Disabled mode (see Settings, Scheduling) the tool refuses with Meeting drafts are disabled in Clippy's Revenge. Ask the user to enable them in the tray settings (Meeting invites: Draft only), then try again. Clippy checks the arguments first, then reply_to_id, then the recipients, and only then creates and saves the meeting. With mailbox, you need delegate or editor rights on that mailbox's calendar, or the tool refuses. Each call adds one line to Activity, such as meeting draft saved for 2 attendees: Thu 10/15 10:00–11:00, or meeting draft not created: <reason> when it fails. The body never appears there.

Parameter Type Description
recipients string, required Attendees as Name <email>; Name <email> or bare emails, separated by ;
subject string, required Meeting subject
start string, required Local start date-time, e.g. 2026-03-01T14:30. A date without a time is not accepted. An offset is converted to local time
end string, required Local end date-time, after start and in the future
body string Plain-text invite body
location string Location, for example a room
mailbox string An enabled shared mailbox to save the meeting in. Empty means yours
reply_to_id string The id of the email that asked for the meeting (from search_emails). Saves a note in Drafts as a reply to it. An unknown id is an error and nothing is created

To book option N of a find_free_times result, or of times offered in a draft, pass that option's start and end.

No Teams or Zoom link

Outlook's object model has no supported call to add a Teams or Zoom link. The result always tells Claude that the meeting has none and that you add it in Outlook. The old teams argument is gone.

The result has:

Field Meaning
status Always saved_as_draft
message For Claude: the meeting was saved without sending, it has no Teams or Zoom link, and it is listed in the tray under Draft invites. With a note, it adds A note was saved in Drafts as a reply to the email.
subject, start, end What was saved. Times are in the same format as find_free_times
mailbox, organizer, recipients Whose calendar it is in, who organizes it and who is invited
category Clippy draft invite, or null if the category couldn't be set (the meeting is still saved)
note_draft_id Only with reply_to_id: the id of the note draft
note_error Only if the note failed: the meeting is saved, but the note in Drafts couldn't be created

Example

Claude calls create_meeting_draft with recipients set to the sender's address, subject="Project sync", start="2026-10-15T10:00", end="2026-10-15T11:00" and reply_to_id set to the id of the sender's email. The meeting appears unsent in your calendar, a note reply appears in Drafts, and the tray shows Draft invites (1).

Errors Claude may see

Every tool error is a plain sentence that tells Claude what to do next. Common ones:

Situation What the message says
Outlook isn't running Outlook is not running. Ask the user to start Outlook (tray → Start Outlook) and try again.
Outlook is busy Outlook isn't responding. It may be busy, offline or showing a dialog box. Ask the user to check Outlook, then try again. If this call was creating a draft or a meeting, check Outlook for it before retrying.
Index can't be opened The email index could not be opened; see the tray (Error state). Restart Clippy or use Rebuild index.
Unknown or disabled mailbox Mailbox "<input>" is not configured or not enabled. Available mailboxes: <list>. To use another shared mailbox, ask the user to enable it in the Clippy tray menu under Shared mailboxes.
Mailbox enabled but not in your Outlook profile Mailbox "<address>" is configured but is not open in Outlook. Ask the user to add it to their Outlook profile, then try again.
mailbox="all" on a tool that doesn't support it Mailbox "all" only works with search tools. Use one mailbox: <list>. (create_draft and reply_draft word the second sentence a little differently)
Unknown email id Email "<id>" was not found in Outlook. It may have been deleted or moved to a folder that isn't indexed. Run search_emails again to get a current id.
attachment_link refused One of the limit messages
Path outside the allowed folders Path '<path>' is not allowed: <reason>. Allowed folders: <list>. See file access
Meeting drafts turned off See create_meeting_draft

Tool errors are not written to the log with their text, because they can quote what was searched for.