@chronary/toolkit 1.0.1 → 1.2.0

package/dist/mcp.js

@@ -6,72 +6,94 @@ import { Chronary } from "@chronary/sdk";
 
 // src/schemas.ts
 import { z } from "zod";
+var WEBHOOK_EVENT_TYPES = [
+  "agent.created",
+  "agent.updated",
+  "event.created",
+  "event.updated",
+  "event.deleted",
+  "event.started",
+  "event.ended",
+  "event.reminder",
+  "event.hold_created",
+  "event.hold_expired",
+  "event.hold_released",
+  "event.hold_confirmed",
+  "proposal.created",
+  "proposal.responded",
+  "proposal.confirmed",
+  "proposal.expired",
+  "proposal.cancelled",
+  "webhook.deactivated"
+];
+var WEBHOOK_DELIVERY_STATUSES = ["pending", "delivered", "failed"];
 var ListCalendarsSchema = z.object({
-  agent_id: z.string().optional().describe("Filter calendars by agent ID"),
-  include: z.enum(["all"]).optional().describe('Set to "all" to include soft-deleted calendars'),
-  limit: z.number().int().min(1).max(200).optional().describe("Max results per page (default 50)"),
-  offset: z.number().int().min(0).optional().describe("Pagination offset (default 0)")
+  agent_id: z.string().optional().describe("Filter to calendars owned by this agent. Org keys only \u2014 agent-scoped keys are always limited to their own agent and ignore this."),
+  include: z.enum(["all"]).optional().describe('Pass "all" to include calendars across all agents (org keys only)'),
+  limit: z.number().int().min(1).max(200).default(50).describe("Max results to return"),
+  offset: z.number().int().min(0).default(0).describe("Pagination offset")
 });
 var GetCalendarSchema = z.object({
-  calendar_id: z.string().describe("The calendar ID to retrieve")
+  calendar_id: z.string().describe("Calendar ID to fetch")
 });
 var CreateCalendarSchema = z.object({
-  name: z.string().describe("Calendar name"),
-  timezone: z.string().describe('IANA timezone (e.g., "America/New_York")'),
-  agent_id: z.string().optional().describe("Agent ID to associate the calendar with"),
-  default_reminders: z.array(z.number().int().min(1).max(40320)).max(5).nullable().optional().describe("Default reminder offsets in minutes before start, inherited by events that don't set their own (e.g. [10, 1440]). null/omit = system default (10 min); [] = no reminders. Max 5, each 1\u201340320."),
-  metadata: z.record(z.string(), z.unknown()).optional().describe("Arbitrary key-value metadata")
+  name: z.string().min(1).max(255).describe("Calendar name"),
+  agent_id: z.string().optional().describe("Agent ID to own this calendar (omit for org-level)"),
+  timezone: z.string().min(1).describe("IANA timezone (e.g. America/New_York)"),
+  default_reminders: z.array(z.number().int().min(1).max(40320)).max(5).nullable().optional().describe("Default reminder offsets in minutes before start, inherited by events on this calendar that don't set their own. Omit or null to use the system default (10 min); [] for no reminders.")
 });
 var UpdateCalendarSchema = z.object({
-  calendar_id: z.string().describe("The calendar ID to update"),
-  name: z.string().optional().describe("New calendar name"),
-  timezone: z.string().optional().describe("New IANA timezone"),
-  default_reminders: z.array(z.number().int().min(1).max(40320)).max(5).nullable().optional().describe("New default reminder offsets in minutes before start. null = system default (10 min); [] = no reminders. Max 5, each 1\u201340320."),
-  metadata: z.record(z.string(), z.unknown()).optional().describe("Updated metadata")
+  calendar_id: z.string().describe("Calendar ID to update"),
+  name: z.string().min(1).max(255).optional().describe("New calendar name"),
+  timezone: z.string().min(1).optional().describe("New IANA timezone (e.g. America/New_York)"),
+  agent_status: z.enum(["idle", "working", "waiting", "error"]).optional().describe("Owning agent's status"),
+  default_reminders: z.array(z.number().int().min(1).max(40320)).max(5).nullable().optional().describe("Default reminder offsets in minutes; null for system default, [] for none"),
+  metadata: z.record(z.string(), z.unknown()).optional().describe("Arbitrary metadata (max 16KB)")
 });
 var DeleteCalendarSchema = z.object({
-  calendar_id: z.string().describe("The calendar ID to delete")
+  calendar_id: z.string().describe("Calendar ID to delete")
 });
 var ListEventsSchema = z.object({
-  calendar_id: z.string().optional().describe("Calendar ID to list events from (provide this or agent_id)"),
-  agent_id: z.string().optional().describe("Agent ID to list events for (provide this or calendar_id)"),
-  start_after: z.string().optional().describe("Only events starting after this ISO 8601 datetime"),
-  start_before: z.string().optional().describe("Only events starting before this ISO 8601 datetime"),
-  status: z.enum(["confirmed", "tentative", "cancelled"]).optional().describe("Filter by event status"),
-  source: z.enum(["internal", "external_ical"]).optional().describe("Filter by event source"),
-  limit: z.number().int().min(1).max(200).optional().describe("Max results per page (default 50)"),
-  offset: z.number().int().min(0).optional().describe("Pagination offset (default 0)")
+  calendar_id: z.string().optional().describe("Calendar ID to list events from. Provide this or agent_id."),
+  agent_id: z.string().optional().describe("Agent ID to list events for across all of the agent's calendars. Provide this or calendar_id."),
+  start_after: z.string().datetime().optional().describe("Only events starting after this ISO 8601 time"),
+  start_before: z.string().datetime().optional().describe("Only events starting before this ISO 8601 time"),
+  status: z.enum(["confirmed", "tentative", "cancelled", "hold"]).optional().describe("Filter by event status"),
+  source: z.enum(["internal", "external_ical"]).optional().describe('Filter by source: "internal" (created via the API) or "external_ical" (synced from an iCal subscription)'),
+  limit: z.number().int().min(1).max(200).default(50).describe("Max results to return"),
+  offset: z.number().int().min(0).default(0).describe("Pagination offset")
 });
 var GetEventSchema = z.object({
-  calendar_id: z.string().describe("Calendar ID the event belongs to"),
-  event_id: z.string().describe("The event ID to retrieve")
+  event_id: z.string().describe("Event ID to retrieve"),
+  calendar_id: z.string().optional().describe("Calendar ID that owns the event. Optional \u2014 if omitted the calendar is resolved from the event.")
 });
 var CreateEventSchema = z.object({
-  calendar_id: z.string().describe("Calendar ID to create the event on"),
-  title: z.string().describe("Event title"),
-  start_time: z.string().describe("Start time in ISO 8601 format"),
-  end_time: z.string().describe("End time in ISO 8601 format"),
-  description: z.string().optional().describe("Event description"),
-  all_day: z.boolean().optional().describe("Whether this is an all-day event"),
-  status: z.enum(["confirmed", "tentative", "cancelled"]).optional().describe('Event status (default "confirmed")'),
-  reminders: z.array(z.number().int().min(1).max(40320)).max(5).nullable().optional().describe("Reminder offsets in minutes before start (e.g. [10, 1440]). Each fires an event.reminder webhook. null/omit = inherit calendar default (then 10 min); [] = no reminders. Max 5, each 1\u201340320."),
-  metadata: z.record(z.string(), z.unknown()).optional().describe("Arbitrary key-value metadata")
+  calendar_id: z.string().describe("Calendar ID to add the event to"),
+  title: z.string().min(1).max(500).describe("Event title"),
+  start_time: z.string().datetime().describe("Start time (ISO 8601)"),
+  end_time: z.string().datetime().describe("End time (ISO 8601)"),
+  description: z.string().optional().describe("Optional event description"),
+  all_day: z.boolean().default(false).describe("Whether this is an all-day event"),
+  status: z.enum(["confirmed", "tentative", "hold"]).optional().describe('Event status. "hold" creates a tentative reservation that auto-expires at hold_expires_at. Defaults to "confirmed".'),
+  reminders: z.array(z.number().int().min(1).max(40320)).max(5).nullable().optional().describe("Reminder offsets in minutes before start_time (e.g. [10, 1440]). Each fires an event.reminder webhook and shows as an alarm in the iCal feed. Omit or null to inherit the calendar default (then the system default of 10 min); [] for no reminders."),
+  hold_expires_at: z.string().datetime().optional().describe('Required when status="hold". ISO 8601 timestamp 30s-15min in the future. Auto-releases the hold when reached.'),
+  hold_priority: z.number().int().min(0).max(100).optional().describe('Only valid with status="hold". Higher-priority overlapping holds pre-empt lower-priority ones. Defaults to 0.')
 });
 var UpdateEventSchema = z.object({
-  calendar_id: z.string().describe("Calendar ID the event belongs to"),
-  event_id: z.string().describe("The event ID to update"),
-  title: z.string().optional().describe("New event title"),
-  description: z.string().nullable().optional().describe("New description (null to clear)"),
-  start_time: z.string().optional().describe("New start time in ISO 8601 format"),
-  end_time: z.string().optional().describe("New end time in ISO 8601 format"),
+  event_id: z.string().describe("Event ID to update"),
+  calendar_id: z.string().optional().describe("Calendar ID that owns the event. Optional \u2014 if omitted the calendar is resolved from the event."),
+  title: z.string().min(1).max(500).optional().describe("New event title"),
+  description: z.string().nullable().optional().describe("New description, or null to clear it"),
+  start_time: z.string().datetime().optional().describe("New start time (ISO 8601)"),
+  end_time: z.string().datetime().optional().describe("New end time (ISO 8601)"),
   all_day: z.boolean().optional().describe("Whether this is an all-day event"),
   status: z.enum(["confirmed", "tentative", "cancelled"]).optional().describe("New event status"),
-  reminders: z.array(z.number().int().min(1).max(40320)).max(5).nullable().optional().describe("New reminder offsets in minutes before start. null = inherit calendar default; [] = no reminders. Max 5, each 1\u201340320."),
-  metadata: z.record(z.string(), z.unknown()).optional().describe("Updated metadata")
+  metadata: z.record(z.string(), z.unknown()).optional().describe("Replacement metadata object"),
+  reminders: z.array(z.number().int().min(1).max(40320)).max(5).nullable().optional().describe("Reminder offsets in minutes before start_time. Omit to leave unchanged, null to inherit the calendar default, [] for no reminders.")
 });
 var CancelEventSchema = z.object({
-  calendar_id: z.string().describe("Calendar ID that owns the event"),
-  event_id: z.string().describe("Event ID to cancel")
+  event_id: z.string().describe("Event ID to cancel"),
+  calendar_id: z.string().optional().describe("Calendar ID that owns the event. Optional \u2014 if omitted the calendar is resolved from the event. Matches the asymmetry with confirm_event / release_event which never required this arg.")
 });
 var ConfirmEventSchema = z.object({
   event_id: z.string().describe("Event ID of the hold to confirm")
@@ -82,14 +104,13 @@ var ReleaseEventSchema = z.object({
 var CreateAgentSchema = z.object({
   name: z.string().min(1).max(255).describe("Display name for the agent"),
   type: z.enum(["ai", "human", "resource"]).describe("Agent type"),
-  description: z.string().optional().describe("Optional description"),
-  metadata: z.record(z.string(), z.unknown()).optional().describe("Arbitrary key-value metadata")
+  description: z.string().optional().describe("Optional description")
 });
 var ListAgentsSchema = z.object({
   type: z.enum(["ai", "human", "resource"]).optional().describe("Filter by agent type"),
   status: z.enum(["active", "paused", "decommissioned"]).optional().describe("Filter by status"),
-  limit: z.number().int().min(1).max(200).optional().describe("Max results per page (default 50)"),
-  offset: z.number().int().min(0).optional().describe("Pagination offset (default 0)")
+  limit: z.number().int().min(1).max(200).default(50).describe("Max results to return"),
+  offset: z.number().int().min(0).default(0).describe("Pagination offset")
 });
 var GetAgentSchema = z.object({
   agent_id: z.string().describe("Agent ID to fetch")
@@ -106,27 +127,32 @@ var DeleteAgentSchema = z.object({
 });
 var GetAvailabilitySchema = z.object({
   agent_id: z.string().describe("Agent ID to check availability for"),
-  start: z.string().describe("Range start (ISO 8601)"),
-  end: z.string().describe("Range end (ISO 8601)"),
-  slot_duration: z.enum(["15m", "30m", "45m", "1h", "2h"]).optional().describe('Minimum slot duration required (default "30m")'),
-  include_busy: z.boolean().optional().describe("Include busy blocks in response")
+  start: z.string().datetime().optional().describe("Range start (ISO 8601). Alias: start_time."),
+  end: z.string().datetime().optional().describe("Range end (ISO 8601). Alias: end_time."),
+  start_time: z.string().datetime().optional().describe("Alias for `start` (matches REST events naming)."),
+  end_time: z.string().datetime().optional().describe("Alias for `end` (matches REST events naming)."),
+  slot_duration: z.enum(["15m", "30m", "45m", "1h", "2h"]).default("30m").describe("Minimum slot duration required \u2014 only free blocks at least this long are returned"),
+  include_busy: z.boolean().default(false).describe("Include busy blocks in response")
 });
 var FindMeetingTimeSchema = z.object({
-  agents: z.array(z.string()).min(1).describe("Array of agent IDs to find common free time for. All agents must be free during the returned slots."),
-  start: z.string().describe("Search range start (ISO 8601)"),
-  end: z.string().describe("Search range end (ISO 8601)"),
-  slot_duration: z.enum(["15m", "30m", "45m", "1h", "2h"]).optional().describe('Minimum slot duration required (default "30m")'),
+  agents: z.array(z.string()).min(1).optional().describe("Array of agent IDs to find common free time for. All agents must be free during the returned slots. Alias: agent_ids."),
+  agent_ids: z.array(z.string()).min(1).optional().describe("Alias for `agents` (matches REST/scheduling-proposal naming)."),
+  start: z.string().datetime().optional().describe("Search range start (ISO 8601). Alias: start_time."),
+  end: z.string().datetime().optional().describe("Search range end (ISO 8601). Alias: end_time."),
+  start_time: z.string().datetime().optional().describe("Alias for `start` (matches REST events naming)."),
+  end_time: z.string().datetime().optional().describe("Alias for `end` (matches REST events naming)."),
+  slot_duration: z.enum(["15m", "30m", "45m", "1h", "2h"]).default("30m").describe("Minimum slot duration required \u2014 only free blocks at least this long are returned"),
   calendars: z.array(z.string()).optional().describe("Additional shared calendar IDs to treat as busy"),
-  include_busy: z.boolean().optional().describe("Include per-agent busy blocks in response")
+  include_busy: z.boolean().default(false).describe("Include per-agent busy blocks in response")
 });
 var GetCalendarContextSchema = z.object({
   calendar_id: z.string().describe("Calendar ID")
 });
 var proposalSlotSchema = z.object({
-  start_time: z.string().describe("Slot start (ISO 8601)"),
-  end_time: z.string().describe("Slot end (ISO 8601)"),
-  weight: z.number().min(0).max(10).optional().describe("Preference weight (default 1.0)"),
-  calendar_id: z.string().optional().describe("Override calendar for this slot")
+  start_time: z.string().datetime(),
+  end_time: z.string().datetime(),
+  weight: z.number().min(0).max(10).default(1).optional(),
+  calendar_id: z.string().optional()
 });
 var CreateProposalSchema = z.object({
   title: z.string().min(1).max(500).describe("Short description of what the meeting is about"),
@@ -135,7 +161,7 @@ var CreateProposalSchema = z.object({
   participant_agent_ids: z.array(z.string()).min(1).max(50).describe("Agent IDs invited to respond"),
   calendar_id: z.string().describe("Calendar the resolved event will be created on"),
   slots: z.array(proposalSlotSchema).min(1).max(20).describe("Candidate time slots (up to 20)"),
-  expires_at: z.string().optional().describe("Auto-cancel cutoff if unresolved (ISO 8601)")
+  expires_at: z.string().datetime().optional().describe("Auto-cancel cutoff if unresolved")
 });
 var ListProposalsSchema = z.object({
   status: z.enum(["pending", "confirmed", "expired", "cancelled"]).optional().describe("Filter by proposal status"),
@@ -160,10 +186,11 @@ var ResolveProposalSchema = z.object({
 var CancelProposalSchema = z.object({
   proposal_id: z.string().describe("Proposal to cancel")
 });
+var timeOfDay = z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "must be HH:MM in 24-hour time");
 var workingHoursDaySchema = z.object({
-  start: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "must be HH:MM in 24-hour time"),
-  end: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "must be HH:MM in 24-hour time")
-});
+  start: timeOfDay,
+  end: timeOfDay
+}).refine((v) => v.end > v.start, "end must be after start").describe("A single day's working hours window");
 var workingHoursSchema = z.object({
   mon: workingHoursDaySchema.optional(),
   tue: workingHoursDaySchema.optional(),
@@ -172,13 +199,13 @@ var workingHoursSchema = z.object({
   fri: workingHoursDaySchema.optional(),
   sat: workingHoursDaySchema.optional(),
   sun: workingHoursDaySchema.optional()
-}).nullable();
+}).refine((v) => Object.keys(v).length > 0, "at least one day must be specified").nullable();
 var SetAvailabilityRulesSchema = z.object({
   calendar_id: z.string().describe("Calendar to configure"),
-  buffer_before_minutes: z.number().int().min(0).max(120).optional().describe("Minutes of buffer before each event (0\u2013120)"),
-  buffer_after_minutes: z.number().int().min(0).max(120).optional().describe("Minutes of buffer after each event (0\u2013120)"),
-  working_hours: workingHoursSchema.optional().describe("Per-day working hours map in the calendar's timezone; omit keys for off-days. Pass null to remove any working-hours constraint."),
-  timezone: z.string().min(1).max(64).optional().describe("IANA timezone used to interpret working_hours (e.g. America/New_York)")
+  buffer_before_minutes: z.number().int().min(0).max(120).default(0).describe("Minutes of buffer before each event (0\u2013120)"),
+  buffer_after_minutes: z.number().int().min(0).max(120).default(0).describe("Minutes of buffer after each event (0\u2013120)"),
+  working_hours: workingHoursSchema.default(null).describe("Per-day working hours map in the calendar's timezone; omit keys for off-days. Pass null to remove any working-hours constraint."),
+  timezone: z.string().min(1).max(64).default("UTC").describe("IANA timezone used to interpret working_hours (e.g. America/New_York)")
 });
 var GetAvailabilityRulesSchema = z.object({
   calendar_id: z.string().describe("Calendar to read")
@@ -195,8 +222,8 @@ var RevokeScopedKeySchema = z.object({
   key_id: z.string().describe("ID of the scoped key to revoke")
 });
 var GetAuditLogSchema = z.object({
-  from: z.string().optional().describe("Start of the window (ISO 8601). Silently clamped to the plan retention window if older."),
-  to: z.string().optional().describe("End of the window (ISO 8601)"),
+  from: z.string().datetime({ offset: true }).optional().describe("Start of the window (ISO 8601). Silently clamped to the plan retention window if older."),
+  to: z.string().datetime({ offset: true }).optional().describe("End of the window (ISO 8601)"),
   action: z.string().min(1).max(64).optional().describe("Filter by action name (e.g. event.created)"),
   actor_key_prefix: z.string().min(1).max(32).optional().describe("Filter by the API key prefix that performed the action"),
   cursor: z.string().min(1).max(256).optional().describe("Opaque pagination cursor from a previous response"),
@@ -206,33 +233,40 @@ var AcceptTermsSchema = z.object({
   tos_version: z.string().min(1).describe("The terms-of-service version to accept; must match the current version")
 });
 var ListWebhooksSchema = z.object({
-  limit: z.number().int().min(1).max(100).optional().describe("Max results per page (default 20)"),
-  offset: z.number().int().min(0).optional().describe("Pagination offset (default 0)")
+  limit: z.number().int().min(1).max(100).default(20).describe("Max results to return"),
+  offset: z.number().int().min(0).default(0).describe("Pagination offset")
 });
 var GetWebhookSchema = z.object({
-  webhook_id: z.string().describe("The webhook ID to retrieve")
+  webhook_id: z.string().describe("Webhook subscription to fetch")
 });
 var CreateWebhookSchema = z.object({
-  url: z.string().describe("HTTPS URL to receive webhook payloads"),
-  events: z.array(z.string()).describe('Event types to subscribe to (e.g., ["event.created", "event.updated"])')
+  url: z.string().url().describe("HTTPS endpoint that will receive event deliveries"),
+  events: z.array(z.enum(WEBHOOK_EVENT_TYPES)).min(1).describe("Event types to subscribe to")
 });
 var UpdateWebhookSchema = z.object({
-  webhook_id: z.string().describe("The webhook ID to update"),
-  url: z.string().optional().describe("New webhook URL"),
-  events: z.array(z.string()).optional().describe("New event type subscriptions"),
-  active: z.boolean().optional().describe("Enable or disable the webhook")
+  webhook_id: z.string().describe("Webhook subscription to update"),
+  url: z.string().url().optional().describe("New HTTPS delivery endpoint"),
+  events: z.array(z.enum(WEBHOOK_EVENT_TYPES)).min(1).optional().describe("Replacement set of event types to subscribe to"),
+  active: z.boolean().optional().describe("Set false to pause deliveries, true to resume")
 });
 var DeleteWebhookSchema = z.object({
-  webhook_id: z.string().describe("The webhook ID to delete")
+  webhook_id: z.string().describe("Webhook subscription to delete")
+});
+var ListWebhookDeliveriesSchema = z.object({
+  webhook_id: z.string().describe("Webhook subscription whose deliveries to list"),
+  limit: z.number().int().min(1).max(100).default(20).describe("Max results to return"),
+  offset: z.number().int().min(0).default(0).describe("Pagination offset"),
+  status: z.enum(WEBHOOK_DELIVERY_STATUSES).optional().describe("Filter to a single delivery status"),
+  include_payload: z.boolean().optional().describe("Include the full event payload sent on each delivery")
 });
 var ListICalSubscriptionsSchema = z.object({
-  agent_id: z.string().describe("Agent ID to list subscriptions for"),
+  agent_id: z.string().describe("Agent ID whose iCal subscriptions to list"),
   status: z.enum(["active", "error", "paused"]).optional().describe("Filter by subscription status"),
-  limit: z.number().int().min(1).max(200).optional().describe("Max results per page (default 50)"),
-  offset: z.number().int().min(0).optional().describe("Pagination offset (default 0)")
+  limit: z.number().int().min(1).max(200).default(50).describe("Max results to return"),
+  offset: z.number().int().min(0).default(0).describe("Pagination offset")
 });
 var GetICalSubscriptionSchema = z.object({
-  subscription_id: z.string().describe("The iCal subscription ID to retrieve")
+  subscription_id: z.string().describe("iCal subscription ID to fetch")
 });
 var SubscribeICalSchema = z.object({
   agent_id: z.string().describe("Agent ID that will own this subscription"),
@@ -240,23 +274,16 @@ var SubscribeICalSchema = z.object({
   url: z.string().url().describe("HTTPS URL of the iCal feed (.ics) to subscribe to"),
   label: z.string().optional().describe("Optional label for this subscription")
 });
-var ListWebhookDeliveriesSchema = z.object({
-  webhook_id: z.string().describe("Webhook subscription whose deliveries to list"),
-  limit: z.number().int().min(1).max(100).optional().describe("Max results to return (default 20)"),
-  offset: z.number().int().min(0).optional().describe("Pagination offset (default 0)"),
-  status: z.enum(["pending", "delivered", "failed"]).optional().describe("Filter to a single delivery status"),
-  include_payload: z.boolean().optional().describe("Include the full event payload sent on each delivery")
-});
 var UpdateICalSubscriptionSchema = z.object({
-  subscription_id: z.string().describe("The iCal subscription ID to update"),
-  label: z.string().optional().describe("New label"),
-  url: z.string().optional().describe("New iCal feed URL")
+  subscription_id: z.string().describe("iCal subscription ID to update"),
+  label: z.string().min(1).max(255).optional().describe("New label for this subscription"),
+  url: z.string().url().startsWith("https://", "URL must use HTTPS").optional().describe("New HTTPS URL of the iCal feed (.ics)")
 });
 var DeleteICalSubscriptionSchema = z.object({
-  subscription_id: z.string().describe("The iCal subscription ID to delete")
+  subscription_id: z.string().describe("iCal subscription ID to delete")
 });
 var SyncICalSubscriptionSchema = z.object({
-  subscription_id: z.string().describe("The iCal subscription ID to sync immediately")
+  subscription_id: z.string().describe("iCal subscription ID to sync")
 });
 var GetUsageSchema = z.object({});
 
@@ -313,6 +340,9 @@ var deleteCalendar = safeFunc(async (ctx) => {
 });
 var listEvents = safeFunc(async (ctx) => {
   const { client, params } = ctx;
+  if (!params.calendar_id && !params.agent_id) {
+    throw new Error("Provide calendar_id or agent_id");
+  }
   const iter = client.events.list({
     calendarId: params.calendar_id,
     agentId: params.agent_id,
@@ -325,7 +355,8 @@ var listEvents = safeFunc(async (ctx) => {
   return fetchPage(iter, params.offset, params.limit);
 });
 var getEvent = safeFunc(async (ctx) => {
-  return ctx.client.events.get(ctx.params.calendar_id, ctx.params.event_id);
+  const { calendar_id, event_id } = ctx.params;
+  return calendar_id ? ctx.client.events.get(calendar_id, event_id) : ctx.client.events.getById(event_id);
 });
 var createEvent = safeFunc(async (ctx) => {
   const { client, params } = ctx;
@@ -335,10 +366,15 @@ var createEvent = safeFunc(async (ctx) => {
 var updateEvent = safeFunc(async (ctx) => {
   const { client, params } = ctx;
   const { calendar_id, event_id, ...updates } = params;
-  return client.events.update(calendar_id, event_id, updates);
+  return calendar_id ? client.events.update(calendar_id, event_id, updates) : client.events.updateById(event_id, updates);
 });
 var cancelEvent = safeFunc(async (ctx) => {
-  await ctx.client.events.delete(ctx.params.calendar_id, ctx.params.event_id);
+  const { calendar_id, event_id } = ctx.params;
+  if (calendar_id) {
+    await ctx.client.events.delete(calendar_id, event_id);
+  } else {
+    await ctx.client.events.deleteById(event_id);
+  }
   return void 0;
 });
 var confirmEvent = safeFunc(async (ctx) => {
@@ -369,15 +405,34 @@ var deleteAgent = safeFunc(async (ctx) => {
 });
 var getAvailability = safeFunc(async (ctx) => {
   const { client, params } = ctx;
+  const start = params.start ?? params.start_time;
+  const end = params.end ?? params.end_time;
+  if (!start || !end) {
+    throw new Error("start (or start_time) and end (or end_time) are required");
+  }
   return client.availability.forAgent(params.agent_id, {
-    start: params.start,
-    end: params.end,
+    start,
+    end,
     slot_duration: params.slot_duration,
     include_busy: params.include_busy
   });
 });
 var findMeetingTime = safeFunc(async (ctx) => {
-  return ctx.client.availability.check(ctx.params);
+  const { client, params } = ctx;
+  const agents = params.agents ?? params.agent_ids;
+  const start = params.start ?? params.start_time;
+  const end = params.end ?? params.end_time;
+  if (!agents || !start || !end) {
+    throw new Error("agents (or agent_ids), start (or start_time), and end (or end_time) are required");
+  }
+  return client.availability.check({
+    agents,
+    start,
+    end,
+    slot_duration: params.slot_duration,
+    calendars: params.calendars,
+    include_busy: params.include_busy
+  });
 });
 var getCalendarContext = safeFunc(async (ctx) => {
   return ctx.client.calendars.getContext(ctx.params.calendar_id);
@@ -551,35 +606,35 @@ var TOOL_DEFINITIONS = [
   // ── Calendars ──────────────────────────────────────────────────
   {
     name: "list_calendars",
-    description: "List calendars, optionally filtered by agent. Returns paginated results.",
+    description: "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.",
     schema: ListCalendarsSchema,
     annotations: { title: "List Calendars", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(listCalendars)
   },
   {
     name: "get_calendar",
-    description: "Get a calendar by its ID, including its name, timezone, and iCal feed URL.",
+    description: "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.",
     schema: GetCalendarSchema,
     annotations: { title: "Get Calendar", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(getCalendar)
   },
   {
     name: "create_calendar",
-    description: "Create a new calendar. Specify a name and IANA timezone. Optionally scope it to an agent.",
+    description: 'Create a calendar to hold events and track availability. Calendars are required before creating events \u2014 call this first when setting up a new agent. An agent can have multiple calendars (e.g. "Work", "Personal"). Org-level calendars (no agent_id) can be used as shared resources like meeting rooms.',
     schema: CreateCalendarSchema,
     annotations: { title: "Create Calendar", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     execute: createExecutor(createCalendar)
   },
   {
     name: "update_calendar",
-    description: "Update a calendar's name, timezone, or metadata.",
+    description: "Update a calendar's name, timezone, agent status, default reminders, or metadata. Agent-scoped keys may only update calendars owned by their agent.",
     schema: UpdateCalendarSchema,
     annotations: { title: "Update Calendar", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(updateCalendar)
   },
   {
     name: "delete_calendar",
-    description: "Permanently delete a calendar and all its events.",
+    description: "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.",
     schema: DeleteCalendarSchema,
     annotations: { title: "Delete Calendar", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(deleteCalendar)
@@ -587,42 +642,42 @@ var TOOL_DEFINITIONS = [
   // ── Events ─────────────────────────────────────────────────────
   {
     name: "list_events",
-    description: "List events on a calendar or for an agent. Supports date range and status filters. Provide calendar_id or agent_id.",
+    description: "List events on a calendar or across an agent's calendars, including internally created events and externally synced events from iCal subscriptions (e.g. Google Calendar, Outlook). Provide `calendar_id` OR `agent_id`. Narrow with `start_after`/`start_before` (time window), `status`, and `source`.",
     schema: ListEventsSchema,
     annotations: { title: "List Events", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(listEvents)
   },
   {
     name: "get_event",
-    description: "Get a specific event by its calendar ID and event ID.",
+    description: "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 \u2014 if omitted the calendar is resolved from the event. Provide `calendar_id` to fail fast on cross-calendar typos.",
     schema: GetEventSchema,
     annotations: { title: "Get Event", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(getEvent)
   },
   {
     name: "create_event",
-    description: "Create a new event on a calendar. The event blocks the agent's availability during the specified time window and appears in availability queries.",
+    description: `Create a booking, appointment, meeting, hold, or any scheduled event on a calendar. The calendar_id comes from create_calendar or list_events. Once created, this event blocks the agent's availability during that time and appears in availability queries. Use status="hold" with hold_expires_at to tentatively reserve a slot that auto-releases on TTL.`,
     schema: CreateEventSchema,
     annotations: { title: "Create Event", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     execute: createExecutor(createEvent)
   },
   {
     name: "update_event",
-    description: "Update an existing event's title, times, status, or other properties.",
+    description: "Reschedule or edit an event \u2014 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 \u2014 if omitted it is resolved from the event.",
     schema: UpdateEventSchema,
     annotations: { title: "Update Event", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(updateEvent)
   },
   {
     name: "cancel_event",
-    description: "Delete or cancel an event from a calendar. The event is marked cancelled and excluded from future availability calculations.",
+    description: "Delete or cancel an event from a calendar. Use this to remove, cancel, or delete any scheduled event or appointment. The event is marked cancelled and excluded from future availability calculations. `calendar_id` is optional \u2014 if omitted the calendar is looked up from the event. Provide `calendar_id` to fail fast on cross-calendar typos.",
     schema: CancelEventSchema,
     annotations: { title: "Cancel Event", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(cancelEvent)
   },
   {
     name: "confirm_event",
-    description: 'Promote a held event to a confirmed booking. The event must currently have status="hold" and its hold_expires_at must not have passed.',
+    description: '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.',
     schema: ConfirmEventSchema,
     annotations: { title: "Confirm Event", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(confirmEvent)
@@ -644,28 +699,28 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "list_agents",
-    description: "List all agents in your organization. Returns paginated results.",
+    description: "List all agents in your organization",
     schema: ListAgentsSchema,
     annotations: { title: "List Agents", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(listAgents)
   },
   {
     name: "get_agent",
-    description: "Fetch a single agent by ID. An agent represents an AI assistant, human, or shared resource (e.g. a meeting room).",
+    description: "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.",
     schema: GetAgentSchema,
     annotations: { title: "Get Agent", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(getAgent)
   },
   {
     name: "update_agent",
-    description: "Update an agent's name, description, metadata, or status (active/paused). Requires an org-level API key.",
+    description: "Update an agent's name, description, metadata, or status (active/paused). Requires an org-level API key \u2014 agent-scoped keys cannot mutate agents.",
     schema: UpdateAgentSchema,
     annotations: { title: "Update Agent", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(updateAgent)
   },
   {
     name: "delete_agent",
-    description: "Decommission an agent. This marks the agent as decommissioned and revokes all of its scoped API keys. Requires an org-level API key.",
+    description: "Decommission an agent. This marks the agent as decommissioned and revokes all of its scoped API keys. Requires an org-level API key \u2014 agent-scoped keys cannot delete agents.",
     schema: DeleteAgentSchema,
     annotations: { title: "Delete Agent", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(deleteAgent)
@@ -673,14 +728,14 @@ var TOOL_DEFINITIONS = [
   // ── Availability ───────────────────────────────────────────────
   {
     name: "get_availability",
-    description: "Check when a single agent is free within a time range. Returns available time slots and optionally busy blocks.",
+    description: "Check when a single agent is free within a time range. Accepts `start`/`end` (preferred \u2014 matches the underlying availability service) or `start_time`/`end_time` (aliases that match the REST events schema).",
     schema: GetAvailabilitySchema,
     annotations: { title: "Get Availability", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(getAvailability)
   },
   {
     name: "find_meeting_time",
-    description: "Find time slots when multiple agents are all free simultaneously. All agents must be free during the returned slots.",
+    description: "Find time slots when multiple agents are all free simultaneously. Accepts `agents`/`start`/`end` (preferred \u2014 matches the availability service) or `agent_ids`/`start_time`/`end_time` (aliases that match the REST/scheduling-proposal naming).",
     schema: FindMeetingTimeSchema,
     annotations: { title: "Find Meeting Time", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(findMeetingTime)
@@ -688,7 +743,7 @@ var TOOL_DEFINITIONS = [
   // ── Calendar context ───────────────────────────────────────────
   {
     name: "get_calendar_context",
-    description: "Get a calendar's temporal context in a single call: the current event, the next upcoming event, recent past events, a short upcoming window, and the owning agent's status.",
+    description: `Get a calendar's temporal context in a single call: the current event (if one is happening now), the next upcoming event, recent past events, a short upcoming window, and the owning agent's status (idle/working/waiting/error). Use this to answer "what is this agent doing right now?" without issuing multiple list_events queries.`,
     schema: GetCalendarContextSchema,
     annotations: { title: "Get Calendar Context", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(getCalendarContext)
@@ -696,14 +751,14 @@ var TOOL_DEFINITIONS = [
   // ── Scheduling proposals ───────────────────────────────────────
   {
     name: "create_proposal",
-    description: "Create a scheduling proposal \u2014 send candidate time slots to one or more participant agents so they can accept, decline, or counter-propose. Requires an org-level API key. Pro plan only.",
+    description: "Create a scheduling proposal \u2014 send a set of candidate time slots to one or more participant agents so they can accept, decline, or counter-propose. The organizer agent owns the proposal; 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.",
     schema: CreateProposalSchema,
     annotations: { title: "Create Proposal", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     execute: createExecutor(createProposal)
   },
   {
     name: "list_proposals",
-    description: "List scheduling proposals for the org. Filter by status or organizer_agent_id. Requires an org-level API key.",
+    description: "List scheduling proposals for the org. Filter by status (pending|confirmed|expired|cancelled) or organizer_agent_id. Requires an org-level API key.",
     schema: ListProposalsSchema,
     annotations: { title: "List Proposals", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(listProposals)
@@ -717,14 +772,14 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "respond_to_proposal",
-    description: "Submit a response (accept / decline / counter) on behalf of one participant agent to an open proposal. Requires an org-level API key. Pro plan only.",
+    description: 'Submit a response (accept / decline / counter) on behalf of one participant agent to an open proposal. An "accept" requires the slot id from the proposal; a "counter" can suggest alternative slots. When all participants have responded the proposal auto-resolves \u2014 no separate resolve call needed in the normal flow. Requires an org-level API key. Pro plan only.',
     schema: RespondToProposalSchema,
     annotations: { title: "Respond To Proposal", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     execute: createExecutor(respondToProposal)
   },
   {
     name: "resolve_proposal",
-    description: "Force-resolve an open proposal using responses collected so far. Picks the highest-scoring slot and creates a confirmed calendar event. Requires an org-level API key. Pro plan only.",
+    description: 'Force-resolve an open proposal using responses collected so far. Picks the highest-scoring slot among those accepted by the most participants and creates a confirmed calendar 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.',
     schema: ResolveProposalSchema,
     annotations: { title: "Resolve Proposal", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(resolveProposal)
@@ -739,7 +794,7 @@ var TOOL_DEFINITIONS = [
   // ── Availability rules ─────────────────────────────────────────
   {
     name: "set_availability_rules",
-    description: "Set or replace the availability rules on a calendar \u2014 buffer times before/after events and optional per-day working hours. Upsert: overwrites any existing rules.",
+    description: "Set or replace the availability rules on a calendar \u2014 buffer times before/after events and optional per-day working hours. When these rules are set, every availability query on this calendar automatically applies them (busy-block expansion for buffers, masking outside working hours). Upsert: overwrites any existing rules.",
     schema: SetAvailabilityRulesSchema,
     annotations: { title: "Set Availability Rules", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(setAvailabilityRules)
@@ -753,7 +808,7 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "clear_availability_rules",
-    description: "Remove the availability rules from a calendar, reverting to the default (no buffers, no working-hours mask).",
+    description: "Remove the availability rules from a calendar, reverting to the default (no buffers, no working-hours mask). Returns the deleted row, or an error if none were set.",
     schema: ClearAvailabilityRulesSchema,
     annotations: { title: "Clear Availability Rules", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(clearAvailabilityRules)
@@ -761,35 +816,35 @@ var TOOL_DEFINITIONS = [
   // ── Webhooks ───────────────────────────────────────────────────
   {
     name: "list_webhooks",
-    description: "List all webhook subscriptions for the organization.",
+    description: "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.",
     schema: ListWebhooksSchema,
     annotations: { title: "List Webhooks", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(listWebhooks)
   },
   {
     name: "get_webhook",
-    description: "Get a webhook subscription by its ID.",
+    description: "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.",
     schema: GetWebhookSchema,
     annotations: { title: "Get Webhook", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(getWebhook)
   },
   {
     name: "create_webhook",
-    description: "Create a webhook subscription to receive event notifications at a URL. Payloads are signed with HMAC-SHA256.",
+    description: "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 \u2014 store it to verify the HMAC-SHA256 signature on delivered payloads. Requires an org-level API key.",
     schema: CreateWebhookSchema,
     annotations: { title: "Create Webhook", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     execute: createExecutor(createWebhook)
   },
   {
     name: "update_webhook",
-    description: "Update a webhook's URL, subscribed events, or active status.",
+    description: "Update a webhook subscription \u2014 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.",
     schema: UpdateWebhookSchema,
     annotations: { title: "Update Webhook", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(updateWebhook)
   },
   {
     name: "delete_webhook",
-    description: "Delete a webhook subscription. No further events will be delivered to this URL.",
+    description: "Permanently delete a webhook subscription. This frees its endpoint slot against the per-plan cap. Requires an org-level API key.",
     schema: DeleteWebhookSchema,
     annotations: { title: "Delete Webhook", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(deleteWebhook)
@@ -804,42 +859,42 @@ var TOOL_DEFINITIONS = [
   // ── iCal Subscriptions ─────────────────────────────────────────
   {
     name: "list_ical_subscriptions",
-    description: "List external calendar imports (iCal subscriptions) for an agent.",
+    description: "List an agent's external iCal feed subscriptions (e.g. linked Google Calendar / Outlook feeds), including their sync status and last sync time.",
     schema: ListICalSubscriptionsSchema,
     annotations: { title: "List iCal Subscriptions", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(listICalSubscriptions)
   },
   {
     name: "get_ical_subscription",
-    description: "Get an iCal subscription by its ID, including sync status and last error.",
+    description: "Get a single external iCal feed subscription by id, including its sync status, last sync time, and last error.",
     schema: GetICalSubscriptionSchema,
     annotations: { title: "Get iCal Subscription", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(getICalSubscription)
   },
   {
     name: "subscribe_ical",
-    description: "Link an external iCal feed (e.g. a human's Google Calendar) to an agent's calendar so external events appear in availability calculations. Events are synced every 30 minutes.",
+    description: "Link an external iCal feed (e.g. a human's Google Calendar) to an agent's calendar so external events appear in availability calculations. The target calendar must be owned by the specified agent \u2014 create the calendar with that agent_id first (org-level calendars without an agent_id cannot host external iCal subscriptions; create a dedicated per-agent calendar for sync targets).",
     schema: SubscribeICalSchema,
     annotations: { title: "Subscribe iCal", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     execute: createExecutor(subscribeICal)
   },
   {
     name: "update_ical_subscription",
-    description: "Update an iCal subscription's label or feed URL.",
+    description: "Update an external iCal feed subscription \u2014 change its label or its feed URL. Changing the URL forces a full re-sync on the next poll.",
     schema: UpdateICalSubscriptionSchema,
     annotations: { title: "Update iCal Subscription", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(updateICalSubscription)
   },
   {
     name: "delete_ical_subscription",
-    description: "Remove an external calendar import. Previously synced events remain on the calendar.",
+    description: "Delete an external iCal feed subscription. Events previously synced from the feed are no longer refreshed.",
     schema: DeleteICalSubscriptionSchema,
     annotations: { title: "Delete iCal Subscription", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(deleteICalSubscription)
   },
   {
     name: "sync_ical_subscription",
-    description: "Trigger an immediate sync of an iCal subscription instead of waiting for the next 30-minute poll.",
+    description: "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.",
     schema: SyncICalSubscriptionSchema,
     annotations: { title: "Sync iCal Subscription", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     execute: createExecutor(syncICalSubscription)
@@ -847,14 +902,14 @@ var TOOL_DEFINITIONS = [
   // ── Scoped keys ────────────────────────────────────────────────
   {
     name: "create_scoped_key",
-    description: "Create an agent-scoped API key (chr_ak_*) that can only act on behalf of a single agent. The plaintext key is returned exactly once. Requires an org-level API key.",
+    description: "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 \u2014 store it immediately, it cannot be retrieved later. Requires an org-level API key.",
     schema: CreateScopedKeySchema,
     annotations: { title: "Create Scoped Key", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     execute: createExecutor(createScopedKey)
   },
   {
     name: "list_scoped_keys",
-    description: "List all live (non-revoked) agent-scoped API keys for this org. Returns key metadata only \u2014 never the plaintext secret. Requires an org-level API key.",
+    description: "List all live (non-revoked) agent-scoped API keys for this org. Returns key metadata only (id, prefix, agent_id, label, created_at) \u2014 never the plaintext secret. Requires an org-level API key.",
     schema: ListScopedKeysSchema,
     annotations: { title: "List Scoped Keys", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(listScopedKeys)
@@ -869,7 +924,7 @@ var TOOL_DEFINITIONS = [
   // ── Audit log ──────────────────────────────────────────────────
   {
     name: "get_audit_log",
-    description: "List audit-log entries for the calling org \u2014 mutating operations and auth-lifecycle events, newest first. Results are clamped to the plan's retention window. Requires an org-level API key.",
+    description: "List audit-log entries for the calling org \u2014 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.",
     schema: GetAuditLogSchema,
     annotations: { title: "Get Audit Log", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(getAuditLog)
@@ -877,7 +932,7 @@ var TOOL_DEFINITIONS = [
   // ── Terms ──────────────────────────────────────────────────────
   {
     name: "accept_terms",
-    description: "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. Requires an org-level API key.",
+    description: "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 \u2014 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.",
     schema: AcceptTermsSchema,
     annotations: { title: "Accept Terms", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(acceptTerms)
@@ -885,7 +940,7 @@ var TOOL_DEFINITIONS = [
   // ── Usage ──────────────────────────────────────────────────────
   {
     name: "get_usage",
-    description: "Get quota and usage statistics for the current billing period.",
+    description: "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.",
     schema: GetUsageSchema,
     annotations: { title: "Get Usage", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     execute: createExecutor(getUsage)