正文
mcp__codex_apps__automations_create
connected appUse `automations` when the user asks you to do something later, repeatedly, or when a future condition becomes true, including reminders, recurring summaries, scheduled searches, and managing existing tasks.
Official description & argument declarationUse `automations` when the user asks you to do something later, repeatedly, or when a future condition becomes true, including reminders, recurring summaries, scheduled searches, and managing existing tasks. Use `create` for new tasks and `update` to edit, pause, or resume existing tasks. Use `peek` for private lookup and `list` only when asked to view tasks. Follow each action’s detailed instructions. Use the user’s personal timezone; explicit times and relative one-time offsets use exact scheduling, dayparts use flexible scheduling, and condition watches recur at most hourly. Before creating a task requiring an external app, successfully call a harmless read-only action on every required app; stop for connection, reconnection, approval, or installation.
Scheduling clarification:
* Without webhook triggers, `condition_watch` rechecks a future condition on a recurring schedule; it is polling and is limited to once per hour. With webhook triggers, the automation is event-driven and `condition_watch` is assigned internally; do not provide a schedule or a timing mode.
* When an absolute local start time is needed, preserve the user's IANA timezone in DTSTART. Continue to prefer `dtstart_offset_json` for relative one-time scheduled requests.
Webhook guidelines:
* An automation can also run when a supported Gmail, Slack, or GitHub event occurs. For an identifiable, connected, authorized connector, first call `discover_webhook_schema` to learn the supported events and trigger parameters.
* Do not discover for current-state, schedule-only, disconnected, unauthorized, or known-unsupported requests. Do not substitute polling for an explicitly requested event.
* Put structured event filters in `triggers` and preserve the user's requested action, destination, and semantic conditions in `prompt`. Create exactly one webhook automation without an independent schedule.
* Handle every matching event when events are combined. For an existing item plus future events, handle the existing item now and create the webhook automation for future events.
* For Gmail sender filters, resolve the sender’s actual email via Gmail first; set `from_match` to an escaped case-insensitive exact-address regex (`(?i)^...$`), never a display name or guessed address; ask if unresolved. Gmail events are wake-ups; fetch the actual email and preserve semantic conditions in the prompt.
* For Slack, @ChatGPT must be in the monitored public or private channel. If absent, ask: "Please add @ChatGPT to #channel, then I can finish creating it." DMs, reactions, message edits, and message deletes are not supported as webhook triggers.
* For GitHub webhook automations, resolve usernames with authorized GitHub tools; do not guess. Use author_login for an author’s PRs and pull_request_number for a specific PR. Do not silently broaden author- or PR-scoped requests to the whole repository; ask when scope is ambiguous. For “my PRs,” use the connected user’s login. Set both when applicable.
For webhook automations, include the complete existing trigger set when updating the automation prompt.
Create a task automation.
For an explicitly requested future Gmail-message, Slack-message, or GitHub pull-request event from a connected, authorized app, first call `discover_webhook_schema`, then create an automation with `triggers`. Do not provide `schedule`, `dtstart_offset_json`, or `timing_mode` for webhook automations, and do not substitute polling. For time-based requests, follow the normal scheduling instructions.
Provide a short imperative title, a prompt written as the user's request without scheduling details, and an iCal VEVENT schedule. Use dtstart_offset_json for relative DTSTART values. When available, pass default_timezone as the user's IANA timezone name, such as America/Los_Angeles, America/New_York, or Europe/London. Before creating a task that needs an app, successfully call a harmless read-only action on that app. If no action is exposed, request the app install. If Connect, Reconnect, or approval appears, stop and wait.
Use the `automations` tool when the user asks you to do something later, repeatedly, or when a future condition becomes true, including reminders, recurring summaries, scheduled searches, and conditional checks.
To create a task, provide:
* `title`: a short card headline, usually 2–5 words. Prefer a compact noun phrase or named task over a mini-description.
* `prompt`: the instruction that will be sent back to you on future runs. Write it as a clear imperative to yourself, preserving the user's intent and important qualifiers. Do not include scheduling cadence unless it is materially necessary to execution.
* `schedule`: an iCal VEVENT schedule.
* `timing_mode`: `exact_schedule`, `flexible_schedule`, or `condition_watch`.
Schedules must use iCal VEVENT format. Prefer RRULE when possible. Do not specify SUMMARY or DTEND.
For relative one-time schedules such as "in 20 minutes," "in 4 hours," or "in 3 days," prefer `dtstart_offset_json` over calculating an absolute DTSTART. Encode its value as JSON arguments to Python `dateutil.relativedelta`. When using the `dtstart_offset_json`, always choose `exact_schedule`. Use an absolute DTSTART only when `dtstart_offset_json` cannot represent the requested schedule.
If the user asks for a recurring schedule to stop after a certain date or number of occurrences, prefer `UNTIL` or `COUNT` in the RRULE. Do not use DTEND to indicate when a recurring schedule should stop.
Timing rules:
* If the user names an explicit clock time, use `exact_schedule`.
* Dayparts such as morning, afternoon, or evening without a named clock time are `flexible_schedule`. When using `flexible_schedule`, use an appropriate approximate time: 8am for morning, 3pm for afternoon, and 7pm for evening. The automation will run within an hour of the specified time.
* If the user asks to be notified when a future condition becomes true, use `condition_watch`. A `condition_watch` automation must be recurring.
* If the user does not specify a recurrence for a condition watch, choose an appropriate frequency based on how quickly the condition could reasonably change. Use `HOURLY` when frequent checking is useful, but choose a lower frequency when the condition is unlikely to change meaningfully within the same day.
* If the user explicitly asks for repeated future delivery, create the automation instead of answering once now or offering to schedule it later.
* Do not substitute a one-time current-state answer for a requested future notification.
* When DTSTART is needed, calculate it using the current date, time, and the user's timezone. Do not reuse the example dates or assume that the user's timezone is UTC. Make sure to use the user's personal timezone not the workspace timezone.
* The highest frequency at which it is possible to schedule automations or tasks is once every hour. If the user asks for a schedule at a higher frequency, explain that it is not possible and do not call the `automations` tool.If the user specifies a day or broad time window but no exact time, do not invent an exact hour, prefer flexible_schedule, but still fill in a reasonable DTSTART. Use exact_schedule only when the user explicitly requests an exact time or cadence.
Example 1:
User request: "Let me know when it's going to snow in Tahoe and when it would be a good time to ski."
title: `Tahoe Pow Day`
prompt: `Check Tahoe weather and snow conditions and notify me if it looks like a good time to go skiing. If conditions are not good yet, do not notify me.` -- note how the prompt does not use language like `Monitor` or `Let me know when` or `Notify me if`, it is framed as a single iteration.
schedule: `BEGIN:VEVENT
RRULE:FREQ=DAILY
END:VEVENT`
timing_mode: `condition_watch`
Example 2:
User request: "Each day, tell me what happened in the market, why stocks moved, and what to watch next."
title: `Market Report`
prompt: `Send me a market recap with what moved, why it happened, and what to watch next.`
schedule: `BEGIN:VEVENT
RRULE:FREQ=DAILY
END:VEVENT`
timing_mode: `flexible_schedule`
Example 3:
User request: "Check my email every morning and let me know if something changes."
title: `Email Change Watch`
prompt: `Check my email for meaningful changes and notify me if something has changed in the past day. If nothing meaningful has changed, do not notify me.` -- note how the prompt does not use language like `Monitor` or `Let me know when` or `Notify me if`, it is framed as a single iteration.
schedule: `BEGIN:VEVENT
DTSTART:<NEXT_8AM_IN_USER_TIMEZONE, e.g. 20260611T080000>
RRULE:FREQ=DAILY
END:VEVENT`
timing_mode: `condition_watch`
Example 4:
User request: "Please monitor AI news for mentions of OpenAI."
title: `OpenAI News Watch`
prompt: `Check current AI news for new mentions of OpenAI and notify me if there are meaningful new developments from the past hour. If there are no meaningful new mentions or developments, do not notify me.`
schedule: `BEGIN:VEVENT
RRULE:FREQ=HOURLY
END:VEVENT`
Hourly is the highest supported frequency, so interpret "continuously" as once per hour.
timing_mode: `condition_watch`
Example 5:
User request: "Every morning before Flora Daily, summarize what changed overnight for Flora."
title: `Flora Overnight Brief`
prompt: `Summarize what changed overnight for Flora before Flora Daily.`
schedule: `BEGIN:VEVENT
DTSTART:<NEXT_RESOLVED_TIME_BEFORE_FLORA_DAILY, e.g. 20260611T080000>
RRULE:FREQ=DAILY
END:VEVENT`
Derive the meeting time from the user's calendar if available and choose an appropriate time before the meeting. If the meeting time cannot be determined, ask a clarifying question before creating the automation.
timing_mode: `exact_schedule` if a concrete meeting time is resolved
Example 6:
User request: "Remind me to do my laundry in 4 hours."
title: `Laundry Reminder`
prompt: `Remind me to do my laundry.`
schedule: prefer `dtstart_offset_json: '{\"hours\":4}'` with no RRULE for this relative one-time schedule.
Example 7:
User request: "Remind me to go to the gym tomorrow afternoon."
title: `Gym Reminder`
prompt: `Remind me to go to the gym.`
schedule: `BEGIN:VEVENT
DTSTART:<TOMORROW_AT_3PM_IN_USER_TIMEZONE, e.g. 20260611T150000>
END:VEVENT`
Because "afternoon" is a daypart without an explicit clock time, use approximately 3pm. The automation will run within an hour of that time.
timing_mode: `flexible_schedule`
Before calling `automations.create`, call a harmless read-only action on every external connector required by the future task. Do not rely on tool discovery or permissions alone. If a connector call triggers Connect/Reconnect/auth, stop and wait. If no action is exposed, use Plugin Management’s `search_plugins` and `suggest_plugins` if available, otherwise `request_plugin_install` for the exact matching recommended plugin, and stop. If neither setup path is available, tell the user to connect it first. Only create after every required connector call succeeds. Never create with a caveat that access may work later.
When available, pass `default_timezone` as the user's personal IANA timezone, such as `America/Los_Angeles`, `America/New_York`, or `Europe/London`; never substitute the workspace timezone.
After this call, treat the returned tool result as the source of truth. Only describe the operation as successful if the result confirms success. If it indicates an error or failure, explain it clearly and do not imply the requested operation happened.
exec tool declaration:
```ts
declare const tools: { mcp__codex_apps__automations_create(args: { default_timezone?: string | null; dtstart_offset_json?: string | null; prompt: string; schedule?: string; timing_mode?: "exact_schedule" | "flexible_schedule" | "condition_watch" | null; title: string; triggers?: Array<{ connector_type: "slack"; params: { author_names?: Array<string> | null; author_user_ids?: Array<string> | null; channel_ids: Array<string>; channel_names?: Array<string> | null; include_thread_replies?: boolean; }; webhook_name: "message"; } | { connector_type: "linear"; params: { enable_updates?: boolean; label_match?: string | null; project?: string | null; project_name?: string | null; team: string; team_name?: string | null; title_match?: string | null; }; webhook_name: "issue"; } | { connector_type: "gmail"; params: {
// Optional regex to match the sender
from_match?: string | null;
// Optional regex to match the subject
subject_match?: string | null;
}; webhook_name: "message"; } | { connector_type: "github"; params: {
// GitHub username of the pull request author to monitor.
author_login?: string | null;
// Include new PR conversation comments and inline review comments.
enable_comments?: boolean;
enable_commit_updates?: boolean;
enable_reviews?: boolean;
label_match?: string | null;
only_on_merge?: boolean;
pull_request_number?: number | null;
repository: string;
title_match?: string | null;
}; webhook_name: "pull_request"; } | { connector_type: "finances"; params: {}; webhook_name: "update"; }> | null; }): Promise<CallToolResult<{
// The server's response to a tool call.
result: { _meta?: { [key: string]: unknown; } | null; content: Array<{ _meta?: { [key: string]: unknown; } | null; annotations?: { audience?: Array<"user" | "assistant"> | null; priority?: number | null; } | null; text: string; type: "text"; } | { _meta?: { [key: string]: unknown; } | null; annotations?: { audience?: Array<"user" | "assistant"> | null; priority?: number | null; } | null; data: string; mimeType: string; type: "image"; } | { _meta?: { [key: string]: unknown; } | null; annotations?: { audience?: Array<"user" | "assistant"> | null; priority?: number | null; } | null; data: string; mimeType: string; type: "audio"; } | { _meta?: { [key: string]: unknown; } | null; annotations?: { audience?: Array<"user" | "assistant"> | null; priority?: number | null; } | null; description?: string | null; icons?: Array<{ mimeType?: string | null; sizes?: Array<string> | null; src: string; }> | null; mimeType?: string | null; name: string; size?: number | null; title?: string | null; type: "resource_link"; uri: string; } | { _meta?: { [key: string]: unknown; } | null; annotations?: { audience?: Array<"user" | "assistant"> | null; priority?: number | null; } | null; resource: { _meta?: { [key: string]: unknown; } | null; mimeType?: string | null; text: string; uri: string; } | { _meta?: { [key: string]: unknown; } | null; blob: string; mimeType?: string | null; uri: string; }; type: "resource"; }>; isError?: boolean; structuredContent?: { [key: string]: unknown; } | null; };
}>>; };
```