chronary-toolkit

Chronary Toolkit

The @chronary/toolkit package provides 47 pre-built tools for AI agent frameworks. Each tool maps to Chronary API operations with typed parameters, descriptions, and MCP annotations.

npm install @chronary/toolkit

Available Tools

Calendars (5 tools)

Tool	Description	Read-only	Requires confirmation
list_calendars	List calendars, optionally filtered by agent. Returns paginated results.	Yes	No
get_calendar	Get a calendar by its ID, including its name, timezone, and iCal feed URL.	Yes	No
create_calendar	Create a new calendar. Specify a name and IANA timezone. Optionally scope it to an agent.	No	Yes
update_calendar	Update a calendar's name, timezone, or metadata.	No	Yes
delete_calendar	Permanently delete a calendar and all its events.	No	Yes

Events (7 tools)

Tool	Description	Read-only	Requires confirmation
list_events	List events on a calendar or for an agent. Supports date range and status filters. Provide calendar_id or agent_id.	Yes	No
get_event	Get a specific event by its calendar ID and event ID.	Yes	No
create_event	Create a new event on a calendar. The event blocks the agent's availability during the specified time window and appears in availability queries.	No	Yes
update_event	Update an existing event's title, times, status, or other properties.	No	Yes
cancel_event	Delete or cancel an event from a calendar. The event is marked cancelled and excluded from future availability calculations.	No	Yes
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.	No	Yes
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.	No	Yes

Agents (5 tools)

Tool	Description	Read-only	Requires confirmation
create_agent	Register your agent (AI assistant, human participant, or resource) with Chronary so it can own calendars, events, and webhooks.	No	Yes
list_agents	List all agents in your organization. Returns paginated results.	Yes	No
get_agent	Fetch a single agent by ID. An agent represents an AI assistant, human, or shared resource (e.g. a meeting room).	Yes	No
update_agent	Update an agent's name, description, metadata, or status (active/paused). Requires an org-level API key.	No	Yes
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.	No	Yes

Availability (2 tools)

Tool	Description	Read-only	Requires confirmation
get_availability	Check when a single agent is free within a time range. Returns available time slots and optionally busy blocks.	Yes	No
find_meeting_time	Find time slots when multiple agents are all free simultaneously. All agents must be free during the returned slots.	Yes	No

Calendar Context (1 tool)

Tool	Description	Read-only	Requires confirmation
get_calendar_context	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.	Yes	No

Scheduling Proposals (6 tools)

Tool	Description	Read-only	Requires confirmation
create_proposal	Create a scheduling proposal — 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.	No	Yes
list_proposals	List scheduling proposals for the org. Filter by status or organizer_agent_id. Requires an org-level API key.	Yes	No
get_proposal	Get a scheduling proposal by id, including its slots and per-participant responses. Requires an org-level API key.	Yes	No
respond_to_proposal	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.	No	Yes
resolve_proposal	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.	No	Yes
cancel_proposal	Cancel an open proposal. Fires a proposal.cancelled webhook with reason="organizer_cancelled". Requires an org-level API key. Pro plan only.	No	Yes

Availability Rules (3 tools)

Tool	Description	Read-only	Requires confirmation
set_availability_rules	Set or replace the availability rules on a calendar — buffer times before/after events and optional per-day working hours. Upsert: overwrites any existing rules.	No	Yes
get_availability_rules	Read the buffer times and working-hours rules configured on a calendar. Returns the rules row, or an error if none are set.	Yes	No
clear_availability_rules	Remove the availability rules from a calendar, reverting to the default (no buffers, no working-hours mask).	No	Yes

Webhooks (6 tools)

Tool	Description	Read-only	Requires confirmation
list_webhooks	List all webhook subscriptions for the organization.	Yes	No
get_webhook	Get a webhook subscription by its ID.	Yes	No
create_webhook	Create a webhook subscription to receive event notifications at a URL. Payloads are signed with HMAC-SHA256.	No	Yes
update_webhook	Update a webhook's URL, subscribed events, or active status.	No	Yes
delete_webhook	Delete a webhook subscription. No further events will be delivered to this URL.	No	Yes
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.	Yes	No

iCal Subscriptions (6 tools)

Tool	Description	Read-only	Requires confirmation
list_ical_subscriptions	List external calendar imports (iCal subscriptions) for an agent.	Yes	No
get_ical_subscription	Get an iCal subscription by its ID, including sync status and last error.	Yes	No
subscribe_ical	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.	No	Yes
update_ical_subscription	Update an iCal subscription's label or feed URL.	No	Yes
delete_ical_subscription	Remove an external calendar import. Previously synced events remain on the calendar.	No	Yes
sync_ical_subscription	Trigger an immediate sync of an iCal subscription instead of waiting for the next 30-minute poll.	No	Yes

Scoped Keys (3 tools)

Tool	Description	Read-only	Requires confirmation
create_scoped_key	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.	No	Yes
list_scoped_keys	List all live (non-revoked) agent-scoped API keys for this org. Returns key metadata only — never the plaintext secret. Requires an org-level API key.	Yes	No
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.	No	Yes

Audit Log (1 tool)

Tool	Description	Read-only	Requires confirmation
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.	Yes	No

Terms (1 tool)

Tool	Description	Read-only	Requires confirmation
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. Requires an org-level API key.	No	Yes

Usage (1 tool)

Tool	Description	Read-only	Requires confirmation
get_usage	Get quota and usage statistics for the current billing period.	Yes	No

Framework Adapters

Vercel AI SDK

import { ChronaryToolkit } from '@chronary/toolkit/ai-sdk';

const toolkit = new ChronaryToolkit({ apiKey: process.env.CHRONARY_API_KEY });
const tools = toolkit.getTools();

// Use with generateText or streamText
import { generateText } from 'ai';
const result = await generateText({
  model: yourModel,
  tools,
  prompt: 'Schedule a meeting tomorrow at 2pm on my work calendar',
});

OpenAI Function Calling

import { ChronaryToolkit } from '@chronary/toolkit/openai';

const toolkit = new ChronaryToolkit({ apiKey: process.env.CHRONARY_API_KEY });
const tools = toolkit.getTools();

// Returns OpenAI-formatted function definitions
// Use with openai.chat.completions.create({ tools })

LangChain

import { ChronaryToolkit } from '@chronary/toolkit/langchain';

const toolkit = new ChronaryToolkit({ apiKey: process.env.CHRONARY_API_KEY });
const tools = toolkit.getTools();

// Returns LangChain StructuredTool instances
// Use with AgentExecutor or tool-calling chains

Mastra

import { ChronaryToolkit } from '@chronary/toolkit/mastra';

const toolkit = new ChronaryToolkit({ apiKey: process.env.CHRONARY_API_KEY });
const tools = toolkit.getTools();

// Returns Mastra-compatible tool definitions

MCP (Model Context Protocol)

import { ChronaryToolkit } from '@chronary/toolkit/mcp';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

const server = new McpServer({ name: 'chronary', version: '1.0.0' });
const toolkit = new ChronaryToolkit({ apiKey: process.env.CHRONARY_API_KEY });
toolkit.registerAll(server);

Selective Tool Loading

Load only the tools you need:

const toolkit = new ChronaryToolkit({
  apiKey: process.env.CHRONARY_API_KEY,
  tools: ['list_calendars', 'create_event', 'find_meeting_time'],
});

Error Handling

All tools return a structured result:

// Success
{ result: { id: 'cal_...', name: 'Work', ... }, isError: false }

// Error
{ result: { error: { type: 'not_found', message: '...' } }, isError: true }

Tools never throw — they return isError: true with details. This is safe for agent loops.