MCP Tools Reference

Chronary exposes 47 MCP tools. Each tool maps to one or more REST API endpoints but is designed for natural-language invocation by AI agents.

Note

All tools require a valid API key passed via the Authorization header during MCP connection. See MCP Setup for configuration details.

---

create_agent

Register your agent (AI assistant, human participant, or resource) with Chronary, creating a Chronary identity it can use to own calendars, events, and webhooks. The agent itself already exists in your system — this gives it a Chronary record.

Parameters

Parameter	Type	Required	Description
name	string	Yes	Display name for the agent
type	enum: ai, human, resource	Yes	Agent type — ai for bots, human for people, resource for rooms/equipment
description	string	No	Optional description of the agent’s purpose

Example

User: “Register an AI agent for my customer support team”

Tool call:

{
  "name": "create_agent",
  "arguments": {
    "name": "Customer Support Agent",
    "type": "ai",
    "description": "Handles scheduling for customer support calls"
  }
}

Response:

{
  "id": "agt_a1b2c3d4",
  "name": "Customer Support Agent",
  "type": "ai",
  "description": "Handles scheduling for customer support calls",
  "status": "active",
  "createdAt": "2026-04-04T10:00:00Z"
}

---

list_agents

List agents in your organization with optional filtering.

Parameters

Parameter	Type	Required	Default	Description
type	enum: ai, human, resource	No	—	Filter by agent type
status	enum: active, paused, decommissioned	No	—	Filter by status
limit	number (1–200)	No	50	Maximum results to return
offset	number	No	0	Pagination offset

Example

User: “Show me all my active AI agents”

Tool call:

{
  "name": "list_agents",
  "arguments": {
    "type": "ai",
    "status": "active"
  }
}

Response:

{
  "data": [
    {
      "id": "agt_a1b2c3d4",
      "name": "Customer Support Agent",
      "type": "ai",
      "status": "active"
    },
    {
      "id": "agt_e5f6g7h8",
      "name": "Sales Agent",
      "type": "ai",
      "status": "active"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

---

get_agent

Fetch a single agent by ID. An agent represents an AI assistant, human, or shared resource (e.g. a meeting room). Agent-scoped API keys may only read their own agent.

Parameters

Parameter	Type	Required	Description
agent_id	string	Yes	Agent ID to fetch

Example

User: “Show me the details for my support agent”

Tool call:

{
  "name": "get_agent",
  "arguments": {
    "agent_id": "agt_a1b2c3d4"
  }
}

Response:

{
  "id": "agt_a1b2c3d4",
  "name": "Customer Support Agent",
  "type": "ai",
  "description": "Handles scheduling for customer support calls",
  "status": "active",
  "createdAt": "2026-04-04T10:00:00Z"
}

---

update_agent

Update an agent’s name, description, metadata, or status (active/paused). Requires an org-level API key — agent-scoped keys cannot mutate agents.

Parameters

Parameter	Type	Required	Description
agent_id	string	Yes	Agent ID to update
name	string (1–255)	No	New display name
description	string | null	No	New description (null to clear)
metadata	object	No	Arbitrary metadata (max 16KB)
status	enum: active, paused	No	Operational status

Example

User: “Pause my sales agent”

Tool call:

{
  "name": "update_agent",
  "arguments": {
    "agent_id": "agt_e5f6g7h8",
    "status": "paused"
  }
}

Response:

{
  "id": "agt_e5f6g7h8",
  "name": "Sales Agent",
  "type": "ai",
  "status": "paused",
  "updatedAt": "2026-04-04T10:30:00Z"
}

---

delete_agent

Decommission an agent. This marks the agent as decommissioned and revokes all of its scoped API keys. Requires an org-level API key — agent-scoped keys cannot delete agents.

Parameters

Parameter	Type	Required	Description
agent_id	string	Yes	Agent ID to decommission

Example

User: “Decommission the old test agent”

Tool call:

{
  "name": "delete_agent",
  "arguments": {
    "agent_id": "agt_a1b2c3d4"
  }
}

Response:

{
  "deleted": true,
  "id": "agt_a1b2c3d4"
}

---

create_calendar

Create a calendar. Calendars can belong to a specific agent or exist at the organization level.

Parameters

Parameter	Type	Required	Description
name	string	Yes	Calendar display name
agent_id	string	No	Agent to own this calendar. Omit for an org-level calendar.
timezone	string (IANA)	Yes	Calendar timezone, e.g. America/New_York, Europe/London, UTC

Example

User: “Create a calendar for my sales agent in New York timezone”

Tool call:

{
  "name": "create_calendar",
  "arguments": {
    "name": "Sales Calendar",
    "agent_id": "agt_e5f6g7h8",
    "timezone": "America/New_York"
  }
}

Response:

{
  "id": "cal_x1y2z3",
  "orgId": "org_a1b2c3",
  "agentId": "agt_e5f6g7h8",
  "name": "Sales Calendar",
  "timezone": "America/New_York",
  "agent_status": "idle",
  "default_reminders": null,
  "createdAt": "2026-04-04T10:05:00Z"
}

Tip

Fetch the calendar over REST (GET /v1/calendars/:id) to get its ical_url — a live iCal feed you can paste into Google Calendar, Apple Calendar, or Outlook. The MCP calendar tools omit ical_url.

---

list_calendars

List calendars in the org. Org-level API keys see every calendar (agent-owned and shared); agent-scoped keys see only their own agent’s calendars. Use this to discover calendar IDs before creating or listing events.

Parameters

Parameter	Type	Required	Default	Description
include	enum: all	No	—	Pass all to include calendars across all agents (org keys only)
limit	number (1–200)	No	50	Max results to return
offset	number	No	0	Pagination offset

Example

User: “List all my calendars”

Tool call:

{
  "name": "list_calendars",
  "arguments": {
    "include": "all"
  }
}

Response:

{
  "data": [
    {
      "id": "cal_x1y2z3",
      "agentId": "agt_e5f6g7h8",
      "name": "Sales Calendar",
      "timezone": "America/New_York"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

---

get_calendar

Fetch a single calendar by ID, including its name, timezone, agent status, and default reminders. Agent-scoped keys may only read calendars owned by their agent.

Parameters

Parameter	Type	Required	Description
calendar_id	string	Yes	Calendar ID to fetch

Example

User: “Show me the sales calendar”

Tool call:

{
  "name": "get_calendar",
  "arguments": {
    "calendar_id": "cal_x1y2z3"
  }
}

Response:

{
  "id": "cal_x1y2z3",
  "agentId": "agt_e5f6g7h8",
  "name": "Sales Calendar",
  "timezone": "America/New_York",
  "agent_status": "working",
  "default_reminders": [10]
}

---

update_calendar

Update a calendar’s name, timezone, agent status, default reminders, or metadata. Agent-scoped keys may only update calendars owned by their agent.

Parameters

Parameter	Type	Required	Description
calendar_id	string	Yes	Calendar ID to update
name	string (1–255)	No	New calendar name
timezone	string (IANA)	No	New IANA timezone (e.g. America/New_York)
agent_status	enum: idle, working, waiting, error	No	Owning agent’s status
default_reminders	array of number (1–40320) | null	No	Default reminder offsets in minutes; null for system default, [] for none
metadata	object	No	Arbitrary metadata (max 16KB)

Example

User: “Set my sales agent’s status to working”

Tool call:

{
  "name": "update_calendar",
  "arguments": {
    "calendar_id": "cal_x1y2z3",
    "agent_status": "working"
  }
}

Response:

{
  "id": "cal_x1y2z3",
  "name": "Sales Calendar",
  "timezone": "America/New_York",
  "agent_status": "working"
}

---

delete_calendar

Delete a calendar (soft delete). Its events are no longer returned and it stops contributing to availability. Agent-scoped keys may only delete calendars owned by their agent.

Parameters

Parameter	Type	Required	Description
calendar_id	string	Yes	Calendar ID to delete

Example

User: “Delete the old sales calendar”

Tool call:

{
  "name": "delete_calendar",
  "arguments": {
    "calendar_id": "cal_x1y2z3"
  }
}

Response:

{
  "deleted": true,
  "id": "cal_x1y2z3"
}

---

create_event

Create an event on a calendar.

Parameters

Parameter	Type	Required	Description
calendar_id	string	Yes	Target calendar ID (cal_ prefix)
title	string	Yes	Event title
start_time	string (ISO 8601)	Yes	Event start time, e.g. 2026-04-07T14:00:00Z
end_time	string (ISO 8601)	Yes	Event end time
description	string	No	Event description or notes
all_day	boolean	No	Set to true for all-day events

Example

User: “Schedule a 30-minute demo call for next Monday at 2pm UTC”

Tool call:

{
  "name": "create_event",
  "arguments": {
    "calendar_id": "cal_x1y2z3",
    "title": "Demo Call",
    "start_time": "2026-04-07T14:00:00Z",
    "end_time": "2026-04-07T14:30:00Z",
    "description": "Product demo for prospective client"
  }
}

Response:

{
  "id": "evt_m1n2o3",
  "calendarId": "cal_x1y2z3",
  "title": "Demo Call",
  "startTime": "2026-04-07T14:00:00Z",
  "endTime": "2026-04-07T14:30:00Z",
  "description": "Product demo for prospective client",
  "status": "confirmed",
  "createdAt": "2026-04-04T10:10:00Z"
}

---

list_events

List events on a calendar with optional time-range filtering.

Parameters

Parameter	Type	Required	Default	Description
calendar_id	string	Yes	—	Calendar ID to query
start_after	string (ISO 8601)	No	—	Only events starting after this time
start_before	string (ISO 8601)	No	—	Only events starting before this time
limit	number (1–200)	No	50	Maximum results to return
offset	number	No	0	Pagination offset

Example

User: “What meetings do I have next week?”

Tool call:

{
  "name": "list_events",
  "arguments": {
    "calendar_id": "cal_x1y2z3",
    "start_after": "2026-04-06T00:00:00Z",
    "start_before": "2026-04-13T00:00:00Z"
  }
}

Response:

{
  "data": [
    {
      "id": "evt_m1n2o3",
      "title": "Demo Call",
      "startTime": "2026-04-07T14:00:00Z",
      "endTime": "2026-04-07T14:30:00Z",
      "status": "confirmed"
    },
    {
      "id": "evt_p4q5r6",
      "title": "Team Standup",
      "startTime": "2026-04-08T09:00:00Z",
      "endTime": "2026-04-08T09:15:00Z",
      "status": "confirmed"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

---

get_event

Retrieve a single event by ID, including its title, times, status, location, reminders, and metadata. Works for both internally created events and externally synced iCal events. calendar_id is optional — if omitted the calendar is resolved from the event. Provide calendar_id to fail fast on cross-calendar typos.

Parameters

Parameter	Type	Required	Description
event_id	string	Yes	Event ID to retrieve
calendar_id	string	No	Calendar ID that owns the event. Optional — if omitted the calendar is resolved from the event.

Example

User: “Show me the details of my demo call”

Tool call:

{
  "name": "get_event",
  "arguments": {
    "event_id": "evt_m1n2o3"
  }
}

Response:

{
  "id": "evt_m1n2o3",
  "calendarId": "cal_x1y2z3",
  "title": "Demo Call",
  "startTime": "2026-04-07T14:00:00Z",
  "endTime": "2026-04-07T14:30:00Z",
  "status": "confirmed"
}

---

update_event

Reschedule or edit an event — change its title, description, start/end times, location, status, reminders, or metadata. Use this to move an appointment to a new time or update its details. Provide only the fields you want to change. Holds cannot be edited via this tool (use confirm_event / release_event). External iCal events are read-only. calendar_id is optional — if omitted it is resolved from the event.

Parameters

Parameter	Type	Required	Description
event_id	string	Yes	Event ID to update
calendar_id	string	No	Calendar ID that owns the event. Optional — if omitted the calendar is resolved from the event.
title	string (1–500)	No	New event title
description	string | null	No	New description, or null to clear it
start_time	string (ISO 8601)	No	New start time
end_time	string (ISO 8601)	No	New end time
all_day	boolean	No	Whether this is an all-day event
status	enum: confirmed, tentative, cancelled	No	New event status
metadata	object	No	Replacement metadata object
reminders	array of number (1–40320) | null	No	Reminder offsets in minutes before start_time. Omit to leave unchanged, null to inherit the calendar default, [] for no reminders.

At least one field beyond event_id / calendar_id must be supplied.

Example

User: “Move my demo call to 3pm UTC”

Tool call:

{
  "name": "update_event",
  "arguments": {
    "event_id": "evt_m1n2o3",
    "start_time": "2026-04-07T15:00:00Z",
    "end_time": "2026-04-07T15:30:00Z"
  }
}

Response:

{
  "id": "evt_m1n2o3",
  "calendarId": "cal_x1y2z3",
  "title": "Demo Call",
  "startTime": "2026-04-07T15:00:00Z",
  "endTime": "2026-04-07T15:30:00Z",
  "status": "confirmed"
}

---

cancel_event

Cancel an event. The event is marked as cancelled rather than deleted, preserving history.

Parameters

Parameter	Type	Required	Description
event_id	string	Yes	Event to cancel (evt_ prefix)
calendar_id	string	No	Calendar the event belongs to. Optional — if omitted, the calendar is resolved from the event (matching the behavior of confirm_event / release_event). Provide it to fail fast on cross-calendar typos.

Example

User: “Cancel my demo call on Monday”

Tool call:

{
  "name": "cancel_event",
  "arguments": {
    "calendar_id": "cal_x1y2z3",
    "event_id": "evt_m1n2o3"
  }
}

Response:

{
  "cancelled": true,
  "id": "evt_m1n2o3"
}

---

confirm_event

Promote a held event to a confirmed booking. The event must currently have status="hold" and its hold_expires_at must not have passed. After confirmation, event.started and event.ended lifecycle webhooks fire at the scheduled times.

Parameters

Parameter	Type	Required	Description
event_id	string	Yes	Event ID of the hold to confirm (evt_ prefix)

Example

User: “Lock in the 2 pm demo slot I placed a hold on”

Tool call:

{
  "name": "confirm_event",
  "arguments": {
    "event_id": "evt_h1a2b3c4"
  }
}

Response:

{
  "id": "evt_h1a2b3c4",
  "status": "confirmed",
  "holdExpiresAt": null,
  "startTime": "2026-04-05T14:00:00Z",
  "endTime": "2026-04-05T14:30:00Z"
}

---

release_event

Manually release a held event before its hold_expires_at. The event must currently have status="hold". Frees the slot for other agents to book.

Parameters

Parameter	Type	Required	Description
event_id	string	Yes	Event ID of the hold to release (evt_ prefix)

Example

User: “Never mind, release that 2 pm hold”

Tool call:

{
  "name": "release_event",
  "arguments": {
    "event_id": "evt_h1a2b3c4"
  }
}

Response:

{
  "released": true,
  "id": "evt_h1a2b3c4"
}

---

get_availability

Query available time slots for a single agent across all their calendars.

Parameters

Parameter	Type	Required	Default	Description
agent_id	string	Yes	—	Agent to check availability for
start	string (ISO 8601)	Yes¹	—	Start of the query window. Alias: start_time.
end	string (ISO 8601)	Yes¹	—	End of the query window. Alias: end_time.
slot_duration	enum: 15m, 30m, 45m, 1h, 2h	No	30m	Duration of each available slot
include_busy	boolean	No	false	Include busy periods in the response

¹ Use either start/end (canonical — matches the availability service) or start_time/end_time (aliases — match the REST events schema). Mixing forms is allowed; the canonical name wins.

Example

User: “When is my support agent free tomorrow afternoon for a 1-hour meeting?”

Tool call:

{
  "name": "get_availability",
  "arguments": {
    "agent_id": "agt_a1b2c3d4",
    "start": "2026-04-05T12:00:00Z",
    "end": "2026-04-05T18:00:00Z",
    "slot_duration": "1h"
  }
}

Response:

{
  "agents": ["agt_a1b2c3d4"],
  "slots": [
    { "start": "2026-04-05T12:00:00Z", "end": "2026-04-05T13:00:00Z" },
    { "start": "2026-04-05T13:00:00Z", "end": "2026-04-05T14:00:00Z" },
    { "start": "2026-04-05T15:00:00Z", "end": "2026-04-05T16:00:00Z" },
    { "start": "2026-04-05T16:00:00Z", "end": "2026-04-05T17:00:00Z" }
  ]
}

Note

The gap from 14:00–15:00 indicates the agent has an existing event during that time. Set include_busy: true to see what’s blocking.

---

find_meeting_time

Find overlapping free slots across multiple agents — ideal for scheduling group meetings.

Parameters

Parameter	Type	Required	Default	Description
agents	array of strings	Yes¹	—	Agent IDs to check (minimum 2). Alias: agent_ids.
start	string (ISO 8601)	Yes¹	—	Start of the query window. Alias: start_time.
end	string (ISO 8601)	Yes¹	—	End of the query window. Alias: end_time.
slot_duration	enum: 15m, 30m, 45m, 1h, 2h	No	30m	Duration of each slot
calendars	array of strings	No	—	Limit to specific calendars (default: all calendars for each agent)
include_busy	boolean	No	false	Include per-agent busy periods

¹ agents/start/end are the canonical names. agent_ids/start_time/end_time are accepted as aliases for clients written against the REST/scheduling-proposal naming. The canonical name wins if both are supplied.

Example

User: “Find a 30-minute slot next week where both my sales agent and support agent are free”

Tool call:

{
  "name": "find_meeting_time",
  "arguments": {
    "agents": ["agt_a1b2c3d4", "agt_e5f6g7h8"],
    "start": "2026-04-06T09:00:00Z",
    "end": "2026-04-10T17:00:00Z",
    "slot_duration": "30m"
  }
}

Response:

{
  "agents": ["agt_a1b2c3d4", "agt_e5f6g7h8"],
  "slots": [
    { "start": "2026-04-06T10:00:00Z", "end": "2026-04-06T10:30:00Z" },
    { "start": "2026-04-06T11:00:00Z", "end": "2026-04-06T11:30:00Z" },
    { "start": "2026-04-07T09:00:00Z", "end": "2026-04-07T09:30:00Z" },
    { "start": "2026-04-07T15:00:00Z", "end": "2026-04-07T15:30:00Z" }
  ]
}

---

subscribe_ical

Subscribe an agent’s calendar to an external iCal feed. Chronary will periodically sync events from the external URL into the agent’s calendar.

Caution

The target calendar must already be owned by the specified agent — create it via create_calendar with agent_id set. Org-level calendars (no agent_id) cannot host external iCal subscriptions; the call will fail with Calendar must belong to the specified agent.

Parameters

Parameter	Type	Required	Description
agent_id	string	Yes	Agent that owns the target calendar
calendar_id	string	Yes	Calendar to subscribe to the external feed. Must be agent-owned.
url	string (HTTPS)	Yes	URL of the external .ics feed
label	string	No	Display label for this subscription

Example

User: “Subscribe my sales agent’s calendar to our company holiday calendar”

Tool call:

{
  "name": "subscribe_ical",
  "arguments": {
    "agent_id": "agt_e5f6g7h8",
    "calendar_id": "cal_x1y2z3",
    "url": "https://company.example.com/holidays.ics",
    "label": "Company Holidays"
  }
}

Response:

{
  "id": "ics_k1l2m3",
  "agent_id": "agt_e5f6g7h8",
  "calendar_id": "cal_x1y2z3",
  "url": "https://company.example.com/holidays.ics",
  "label": "Company Holidays",
  "status": "active",
  "last_synced_at": null,
  "created_at": "2026-04-04T10:15:00Z"
}

Caution

The external URL must use HTTPS. HTTP URLs are rejected for security. The feed is synced periodically — initial sync may take a few minutes.

---

list_ical_subscriptions

List an agent’s external iCal feed subscriptions (e.g. linked Google Calendar / Outlook feeds), including their sync status and last sync time.

Parameters

Parameter	Type	Required	Default	Description
agent_id	string	Yes	—	Agent ID whose iCal subscriptions to list
status	enum: active, error, paused	No	—	Filter by subscription status
limit	number (1–200)	No	50	Max results to return
offset	number	No	0	Pagination offset

Example

User: “List my sales agent’s external calendar feeds”

Tool call:

{
  "name": "list_ical_subscriptions",
  "arguments": {
    "agent_id": "agt_e5f6g7h8"
  }
}

Response:

{
  "data": [
    {
      "id": "ics_k1l2m3",
      "calendar_id": "cal_x1y2z3",
      "label": "Company Holidays",
      "status": "active",
      "last_synced_at": "2026-04-04T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

---

get_ical_subscription

Get a single external iCal feed subscription by id, including its sync status, last sync time, and last error.

Parameters

Parameter	Type	Required	Description
subscription_id	string	Yes	iCal subscription ID to fetch

Example

User: “Show me the company holidays feed”

Tool call:

{
  "name": "get_ical_subscription",
  "arguments": {
    "subscription_id": "ics_k1l2m3"
  }
}

Response:

{
  "id": "ics_k1l2m3",
  "calendar_id": "cal_x1y2z3",
  "url": "https://company.example.com/holidays.ics",
  "label": "Company Holidays",
  "status": "active",
  "last_synced_at": "2026-04-04T10:30:00Z",
  "last_error": null
}

---

update_ical_subscription

Update an external iCal feed subscription — change its label or its feed URL. Changing the URL forces a full re-sync on the next poll.

Parameters

Parameter	Type	Required	Description
subscription_id	string	Yes	iCal subscription ID to update
label	string (1–255)	No	New label for this subscription
url	string (HTTPS)	No	New HTTPS URL of the iCal feed (.ics)

At least one of label or url must be supplied.

Example

User: “Rename the holidays feed to 2026 Holidays”

Tool call:

{
  "name": "update_ical_subscription",
  "arguments": {
    "subscription_id": "ics_k1l2m3",
    "label": "2026 Holidays"
  }
}

Response:

{
  "id": "ics_k1l2m3",
  "calendar_id": "cal_x1y2z3",
  "label": "2026 Holidays",
  "status": "active"
}

---

delete_ical_subscription

Delete an external iCal feed subscription. Events previously synced from the feed are no longer refreshed.

Parameters

Parameter	Type	Required	Description
subscription_id	string	Yes	iCal subscription ID to delete

Example

User: “Remove the company holidays feed”

Tool call:

{
  "name": "delete_ical_subscription",
  "arguments": {
    "subscription_id": "ics_k1l2m3"
  }
}

Response:

{
  "deleted": true,
  "id": "ics_k1l2m3"
}

---

sync_ical_subscription

Trigger an immediate sync of an external iCal feed subscription instead of waiting for the next scheduled poll. Returns once the sync has been queued.

Parameters

Parameter	Type	Required	Description
subscription_id	string	Yes	iCal subscription ID to sync

Example

User: “Sync the company holidays feed now”

Tool call:

{
  "name": "sync_ical_subscription",
  "arguments": {
    "subscription_id": "ics_k1l2m3"
  }
}

Response:

{
  "status": "syncing"
}

---

get_calendar_context

Fetch a calendar’s temporal context in one call — the current event, next upcoming event, recent past events, a short upcoming window, and the owning agent’s agent_status. Use this to answer “what is this agent doing right now?” without issuing multiple list_events queries.

Parameters

Parameter	Type	Required	Description
calendar_id	string	Yes	Calendar to inspect

Example

User: “What is the support agent up to right now?”

Tool call:

{
  "name": "get_calendar_context",
  "arguments": { "calendar_id": "cal_x1y2z3" }
}

Response (shape follows the REST /v1/calendars/:id/context response):

{
  "calendar_id": "cal_x1y2z3",
  "now": "2026-04-24T14:30:00.000Z",
  "agent_status": "working",
  "current_event": { "id": "evt_a1", "title": "Customer call", "endTime": "2026-04-24T15:00:00Z" },
  "next_event": { "id": "evt_a2", "startTime": "2026-04-24T15:30:00Z" },
  "recent_events": [],
  "upcoming": []
}

---

create_proposal

Send a set of candidate time slots to one or more participant agents so they can accept, decline, or counter-propose. Once every participant responds, the system auto-resolves to the highest-scoring slot (or cancels if all decline). Requires an org-level API key. Pro plan only.

Parameters

Parameter	Type	Required	Description
title	string	Yes	Short description of the meeting
description	string	No	Longer context / agenda
organizer_agent_id	string	Yes	Agent proposing the meeting
participant_agent_ids	string[]	Yes	Invited agents (1–50)
calendar_id	string	Yes	Calendar the resolved event lands on
slots	array	Yes	Candidate time slots (1–20). Each: { start_time, end_time, weight?, calendar_id? }
expires_at	string (ISO-8601)	No	Auto-cancel cutoff if unresolved

Fires proposal.created on the webhook stream.

---

list_proposals

List scheduling proposals for the current org. Filter by status or organizer agent, and page through results with limit and offset. Requires an org-level API key. Pro plan only.

Parameters

Parameter	Type	Required	Description
status	pending|confirmed|expired|cancelled	No	Filter proposals by lifecycle state
organizer_agent_id	string	No	Filter to proposals created by one agent
limit	integer	No	Page size, 1-200. Default 50
offset	integer	No	Page offset. Default 0

---

get_proposal

Fetch a scheduling proposal with its candidate slots and participant responses. Use this before respond_to_proposal to find a selected_slot_id. Requires an org-level API key. Pro plan only.

Parameters

Parameter	Type	Required	Description
proposal_id	string	Yes	Proposal to fetch

---

respond_to_proposal

Submit a response on behalf of one participant agent. An accept requires the slot id from the proposal; a counter can suggest alternative slots. When all participants have responded the proposal auto-resolves. Requires an org-level API key. Pro plan only.

Parameters

Parameter	Type	Required	Description
proposal_id	string	Yes	Proposal to respond to
agent_id	string	Yes	Participant agent responding
response	accept|decline|counter	Yes	Decision
selected_slot_id	string	When accept	Slot the agent is accepting
counter_slots	array	When counter	Alternative slots (up to 20)
message	string	No	Optional note for the organizer

Response includes auto_resolved: "confirmed", "cancelled", or null.

---

resolve_proposal

Force-resolve an open proposal using responses collected so far — picks the highest-scoring slot accepted by the most participants and creates a confirmed event. If every response was decline, the proposal is cancelled instead. Use when you want to close out a proposal without waiting for every participant. Requires an org-level API key. Pro plan only.

Parameters

Parameter	Type	Required	Description
proposal_id	string	Yes	Proposal to resolve

Response is either { status: "confirmed", resolved_slot } or { status: "cancelled", reason: "all_declined" }.

---

cancel_proposal

Cancel an open proposal. Fires proposal.cancelled with reason: "organizer_cancelled". Requires an org-level API key. Pro plan only.

Parameters

Parameter	Type	Required	Description
proposal_id	string	Yes	Proposal to cancel

---

set_availability_rules

Set (or replace) the availability rules on a calendar — buffer times before/after events and optional per-day working hours. Once set, every availability query on this calendar automatically applies them: busy blocks expand by the buffers, and slots outside working hours are masked. Upsert semantics — overwrites any existing rules.

Parameters

Parameter	Type	Required	Description
calendar_id	string	Yes	Calendar to configure
buffer_before_minutes	integer (0–120)	No	Buffer before each event. Default 0.
buffer_after_minutes	integer (0–120)	No	Buffer after each event. Default 0.
working_hours	object | null	No	Per-day map { mon: { start: "09:00", end: "17:00" }, ... }. Pass null to disable the mask.
timezone	string	No	IANA timezone used to interpret working_hours. Default UTC.

---

get_availability_rules

Read the buffer times and working-hours rules configured on a calendar. Returns the rules row, or not_found if none are set.

Parameters

Parameter	Type	Required	Description
calendar_id	string	Yes	Calendar to read

---

clear_availability_rules

Remove the availability rules from a calendar, reverting to the default (no buffers, no working-hours mask). Returns the deleted row, or not_found if none were set.

Parameters

Parameter	Type	Required	Description
calendar_id	string	Yes	Calendar whose rules should be cleared

---

create_webhook

Create a webhook subscription so the org receives HTTP POST notifications when events occur (e.g. event.created, proposal.confirmed). The signing secret is returned ONCE in this response — store it to verify the HMAC-SHA256 signature on delivered payloads. Requires an org-level API key.

Parameters

Parameter	Type	Required	Description
url	string (HTTPS)	Yes	HTTPS endpoint that will receive event deliveries
events	array of string	Yes	Event types to subscribe to (minimum 1)

Example

User: “Send me a webhook whenever an event is created or cancelled”

Tool call:

{
  "name": "create_webhook",
  "arguments": {
    "url": "https://example.com/hooks/chronary",
    "events": ["event.created", "event.cancelled"]
  }
}

Response:

{
  "id": "whk_a1b2c3",
  "url": "https://example.com/hooks/chronary",
  "events": ["event.created", "event.cancelled"],
  "active": true,
  "createdAt": "2026-04-04T10:20:00Z",
  "secret": "whsec_xxxxxxxxxxxxxxxx"
}

Caution

The secret is shown only in this response — store it now. It is needed to verify the HMAC-SHA256 signature on every delivered payload and cannot be retrieved later.

---

list_webhooks

List the org’s webhook subscriptions with their subscribed event types and active state. Signing secrets are never returned. Requires an org-level API key.

Parameters

Parameter	Type	Required	Default	Description
limit	number (1–100)	No	20	Max results to return
offset	number	No	0	Pagination offset

Example

User: “List my webhook subscriptions”

Tool call:

{
  "name": "list_webhooks",
  "arguments": {}
}

Response:

{
  "data": [
    {
      "id": "whk_a1b2c3",
      "url": "https://example.com/hooks/chronary",
      "events": ["event.created", "event.cancelled"],
      "active": true
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

---

get_webhook

Get a single webhook subscription by id, including its subscribed event types and active state. The signing secret is never returned. Requires an org-level API key.

Parameters

Parameter	Type	Required	Description
webhook_id	string	Yes	Webhook subscription to fetch

Example

User: “Show me my event-created webhook”

Tool call:

{
  "name": "get_webhook",
  "arguments": {
    "webhook_id": "whk_a1b2c3"
  }
}

Response:

{
  "id": "whk_a1b2c3",
  "url": "https://example.com/hooks/chronary",
  "events": ["event.created", "event.cancelled"],
  "active": true
}

---

update_webhook

Update a webhook subscription — change its delivery URL, the set of subscribed event types, or pause/resume it via active. At least one field must be supplied. Requires an org-level API key.

Parameters

Parameter	Type	Required	Description
webhook_id	string	Yes	Webhook subscription to update
url	string (HTTPS)	No	New HTTPS delivery endpoint
events	array of string	No	Replacement set of event types to subscribe to (minimum 1)
active	boolean	No	Set false to pause deliveries, true to resume

Example

User: “Pause my webhook for now”

Tool call:

{
  "name": "update_webhook",
  "arguments": {
    "webhook_id": "whk_a1b2c3",
    "active": false
  }
}

Response:

{
  "id": "whk_a1b2c3",
  "url": "https://example.com/hooks/chronary",
  "events": ["event.created", "event.cancelled"],
  "active": false
}

---

delete_webhook

Permanently delete a webhook subscription. This frees its endpoint slot against the per-plan cap. Requires an org-level API key.

Parameters

Parameter	Type	Required	Description
webhook_id	string	Yes	Webhook subscription to delete

Example

User: “Delete my old webhook”

Tool call:

{
  "name": "delete_webhook",
  "arguments": {
    "webhook_id": "whk_a1b2c3"
  }
}

Response:

{
  "deleted": true,
  "id": "whk_a1b2c3"
}

---

list_webhook_deliveries

List delivery attempts for a webhook subscription, with per-status counts (pending/delivered/failed). Use this to debug failing deliveries. Requires an org-level API key.

Parameters

Parameter	Type	Required	Default	Description
webhook_id	string	Yes	—	Webhook subscription whose deliveries to list
limit	number (1–100)	No	20	Max results to return
offset	number	No	0	Pagination offset
status	enum: pending, delivered, failed	No	—	Filter to a single delivery status
include_payload	boolean	No	false	Include the full event payload sent on each delivery

Example

User: “Show me the failed deliveries for my webhook”

Tool call:

{
  "name": "list_webhook_deliveries",
  "arguments": {
    "webhook_id": "whk_a1b2c3",
    "status": "failed"
  }
}

Response:

{
  "data": [
    {
      "id": "whd_x9y8z7",
      "subscription_id": "whk_a1b2c3",
      "event_type": "event.created",
      "status": "failed",
      "attempts": 3,
      "last_attempt_at": "2026-04-04T10:25:00Z",
      "next_retry_at": null,
      "created_at": "2026-04-04T10:20:00Z"
    }
  ],
  "total": 13,
  "limit": 20,
  "offset": 0,
  "stats": { "pending": 0, "delivered": 12, "failed": 1 }
}

---

create_scoped_key

Create an agent-scoped API key (chr_ak_*) that can only act on behalf of a single agent. Use this to self-provision or rotate per-agent credentials. The plaintext key is returned exactly once in the response — store it immediately, it cannot be retrieved later. Requires an org-level API key.

Parameters

Parameter	Type	Required	Description
agent_id	string (agt_ prefix)	Yes	Agent ID this key is scoped to
label	string (1–100)	No	Human-readable label for the key

Example

User: “Create a scoped key for my support agent”

Tool call:

{
  "name": "create_scoped_key",
  "arguments": {
    "agent_id": "agt_a1b2c3d4",
    "label": "Support agent runtime"
  }
}

Response:

{
  "id": "key_p1q2r3",
  "key_prefix": "chr_ak_0A1B2C3D",
  "agent_id": "agt_a1b2c3d4",
  "label": "Support agent runtime",
  "key": "chr_ak_xxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-04-04T10:35:00Z"
}

Caution

The key is returned only once. Store it immediately — it cannot be retrieved later.

---

list_scoped_keys

List all live (non-revoked) agent-scoped API keys for this org. Returns key metadata only (id, key_prefix, agent_id, label, created_at) — never the plaintext secret. Requires an org-level API key.

Parameters

This tool takes no parameters.

Example

User: “List my scoped API keys”

Tool call:

{
  "name": "list_scoped_keys",
  "arguments": {}
}

Response:

{
  "keys": [
    {
      "id": "key_p1q2r3",
      "key_prefix": "chr_ak_0A1B2C3D",
      "agent_id": "agt_a1b2c3d4",
      "label": "Support agent runtime",
      "created_at": "2026-04-04T10:35:00Z"
    }
  ]
}

---

revoke_scoped_key

Revoke an agent-scoped API key by ID. Revocation is permanent (cannot be un-revoked); the key stops authenticating within about a minute. Requires an org-level API key.

Parameters

Parameter	Type	Required	Description
key_id	string	Yes	ID of the scoped key to revoke

Example

User: “Revoke the support agent’s key”

Tool call:

{
  "name": "revoke_scoped_key",
  "arguments": {
    "key_id": "key_p1q2r3"
  }
}

Response:

{
  "revoked": true,
  "id": "key_p1q2r3"
}

---

get_usage

Get the calling org’s current-period usage and plan limits (agents, calendars, events, API calls, webhooks, availability queries, iCal subscriptions, proposals, scoped keys, holds, cross-calendar queries). Requires an org-level API key (chr_sk_*); agent-scoped keys cannot read org-wide usage.

Parameters

This tool takes no parameters.

Example

User: “How much of my quota have I used this month?”

Tool call:

{
  "name": "get_usage",
  "arguments": {}
}

Response:

{
  "period_start": "2026-04-01T00:00:00.000Z",
  "period_end": "2026-05-01T00:00:00.000Z",
  "plan": "free",
  "agents": { "used": 2, "limit": 5 },
  "events": { "used": 140, "limit": 1000 },
  "api_calls": { "used": 3200, "limit": 10000 }
}

---

get_audit_log

List audit-log entries for the calling org — mutating operations and auth-lifecycle events, newest first. Results are clamped to the plan’s retention window. Requires an org-level API key (chr_sk_*); agent-scoped keys cannot read the org-wide audit log.

Parameters

Parameter	Type	Required	Default	Description
from	string (ISO 8601)	No	—	Start of the window. Silently clamped to the plan retention window if older.
to	string (ISO 8601)	No	—	End of the window
action	string (1–64)	No	—	Filter by action name (e.g. event.created)
actor_key_prefix	string (1–32)	No	—	Filter by the API key prefix that performed the action
cursor	string (1–256)	No	—	Opaque pagination cursor from a previous response
limit	number (1–200)	No	50	Max results to return

Example

User: “Show me everything that’s happened to my events recently”

Tool call:

{
  "name": "get_audit_log",
  "arguments": {
    "action": "event.created",
    "limit": 50
  }
}

Response:

{
  "data": [
    {
      "id": "aud_a1b2c3",
      "action": "event.created",
      "actor_key_prefix": "chr_sk_abcdef12345678",
      "created_at": "2026-04-04T10:10:00Z"
    }
  ],
  "pagination": { "next_cursor": null },
  "retention_days": 3,
  "range_clamped": false
}

---

accept_terms

Re-accept the current Chronary terms of service on behalf of the calling org. Use this when responses carry the Chronary-Terms-Upgrade-Required header — a material ToS bump otherwise leaves MCP-only agents stuck without a console session. Pass the current tos_version (read it from GET /v1/auth/terms/current). Requires an org-level API key (chr_sk_*); agent-scoped keys cannot accept org-wide terms.

Parameters

Parameter	Type	Required	Description
tos_version	string	Yes	The terms-of-service version to accept; must match the current version

Example

User: “Accept the latest terms of service”

Tool call:

{
  "name": "accept_terms",
  "arguments": {
    "tos_version": "2026-04-01"
  }
}

Response:

{
  "accepted": true,
  "tos_version": "2026-04-01",
  "accepted_at": "2026-04-04T10:40:00Z"
}

---

Quick reference

Tool	Purpose	Key parameters
create_agent	Register agent	name, type
list_agents	List/filter agents	type, status, limit
get_agent	Fetch one agent	agent_id
update_agent	Update agent	agent_id, name, status
delete_agent	Decommission agent	agent_id
create_calendar	Create calendar	name, timezone, agent_id
list_calendars	List calendars	include, limit
get_calendar	Fetch one calendar	calendar_id
update_calendar	Update calendar	calendar_id, name, timezone, agent_status
delete_calendar	Delete calendar	calendar_id
create_event	Schedule event	calendar_id, title, start_time, end_time
list_events	List/filter events	calendar_id, start_after, start_before
get_event	Fetch one event	event_id, calendar_id
update_event	Reschedule/edit event	event_id, start_time, end_time
cancel_event	Cancel event	calendar_id, event_id
confirm_event	Promote hold to confirmed	event_id
release_event	Release a hold early	event_id
get_availability	Single-agent free slots	agent_id, start, end, slot_duration
find_meeting_time	Cross-agent free slots	agents, start, end, slot_duration
subscribe_ical	Subscribe to external iCal	agent_id, calendar_id, url
list_ical_subscriptions	List iCal subscriptions	agent_id, status, limit
get_ical_subscription	Fetch one iCal subscription	subscription_id
update_ical_subscription	Update iCal subscription	subscription_id, label, url
delete_ical_subscription	Delete iCal subscription	subscription_id
sync_ical_subscription	Force immediate iCal sync	subscription_id
get_calendar_context	Current + upcoming context	calendar_id
create_proposal	Open a multi-agent scheduling proposal	organizer_agent_id, participant_agent_ids, calendar_id, slots
list_proposals	List scheduling proposals	status, organizer_agent_id, limit
get_proposal	Fetch a scheduling proposal	proposal_id
respond_to_proposal	Participant response	proposal_id, agent_id, response
resolve_proposal	Force-resolve a pending proposal	proposal_id
cancel_proposal	Cancel a pending proposal	proposal_id
set_availability_rules	Configure buffers + working hours	calendar_id, buffer_before_minutes, buffer_after_minutes, working_hours
get_availability_rules	Read configured rules	calendar_id
clear_availability_rules	Remove rules	calendar_id
create_webhook	Create webhook subscription	url, events
list_webhooks	List webhook subscriptions	limit, offset
get_webhook	Fetch one webhook	webhook_id
update_webhook	Update webhook	webhook_id, url, events, active
delete_webhook	Delete webhook	webhook_id
list_webhook_deliveries	List delivery attempts	webhook_id, status, include_payload
create_scoped_key	Create agent-scoped key	agent_id, label
list_scoped_keys	List scoped keys	none
revoke_scoped_key	Revoke a scoped key	key_id
get_usage	Current-period usage + limits	none
get_audit_log	List audit-log entries	from, to, action, limit
accept_terms	Re-accept current ToS	tos_version