Skip to main content
Glama
temporal-cortex

Temporal Cortex MCP

by temporal-cortex
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

Temporal Cortex MCP

CI npm version npm downloads Smithery License: MIT

v0.9.1 · March 2026 · Changelog · Website: temporal-cortex.com

Give any AI agent autonomous scheduling capabilities. Temporal Cortex is open scheduling infrastructure that lets any AI agent schedule reliably — whether the other person has an AI agent or not, uses Google Calendar or Outlook, or responds instantly or days later. 18 tools across 5 layers handle contact resolution, temporal reasoning, cross-provider availability, and atomic booking. Accessible via MCP, A2A, REST, and browser. Powered by Truth Engine. Install: npx @temporal-cortex/cortex-mcp.

Two ways to use Temporal Cortex

For individuals

Connect your calendars. Your AI agent handles the rest — checking availability, resolving time zones, and booking meetings without double-booking. Works with Claude Desktop, Cursor, OpenClaw, Manus, and any MCP-compatible AI client.

npx @temporal-cortex/cortex-mcp setup

The setup wizard walks you through provider authentication, timezone configuration, and MCP client setup interactively. You'll be scheduling in under a minute.

Or use the managed Platform — no Node.js required. Sign up at app.temporal-cortex.com, connect your calendars via OAuth, and add a single MCP config with your API key.

For developers

Add scheduling to your AI agent or product. 18 tools across 5 layers, 4 protocols (MCP, A2A, REST, Browser), atomic booking with Two-Phase Commit, and deterministic temporal computation powered by Truth Engine.

Related MCP server: calendar-mcp

Why do AI agents fail at calendar tasks?

Even the latest LLMs — GPT-5, Claude, Gemini — score below 50% on temporal reasoning tasks (OOLONG benchmark). Earlier models scored as low as 29% on scheduling and 13% on duration calculations (Test of Time, ICLR 2025). Ask "Schedule for next Tuesday at 2pm" and it picks the wrong Tuesday. Ask "Am I free at 3pm?" and it checks the wrong timezone. Then it double-books your calendar.

Most calendar tools for AI agents are thin CRUD wrappers that pass these failures through to a single calendar provider — no temporal awareness, no conflict detection, no safety net.

What makes Temporal Cortex different?

  • Temporal awareness — Agents call get_temporal_context to know the actual time and timezone. resolve_datetime turns "next Tuesday at 2pm" into a precise RFC 3339 timestamp. No hallucination.

  • Atomic booking — Lock the time slot, verify no conflicts exist, then write. Two agents booking the same 2pm slot? Exactly one succeeds. The other gets a clear error. No double-bookings.

  • Computed availability — Merges free/busy data across multiple calendars into a single unified view. The AI sees actual availability, not a raw dump of events to misinterpret.

  • Deterministic RRULE expansion — Handles DST transitions, BYSETPOS=-1 (last weekday of month), EXDATE with timezones, leap year recurrences, and INTERVAL>1 with BYDAY. Powered by Truth Engine, not LLM inference.

  • Token-efficient output — TOON format compresses calendar data by ~40% fewer tokens than standard JSON, reducing costs and context window usage. TOON is the default output format for all data tools (list_calendars, list_events, find_free_slots, expand_rrule, get_availability). JSON is available via explicit format: "json".

What do I need to run Temporal Cortex?

How do I install Temporal Cortex?

The fastest way to get started:

npx @temporal-cortex/cortex-mcp setup

The cortex-mcp setup wizard walks you through provider authentication, timezone configuration, and MCP client setup interactively. See the First Run Guide for a detailed walkthrough.

Or set up manually in 3 steps:

  1. Install prerequisites — Node.js 18+ (or Docker) and at least one calendar provider (Google Calendar, Microsoft Outlook, or CalDAV).

  2. Add the MCP configuration to your AI client's config file (see client-specific examples below).

  3. Run the auth flow — npx @temporal-cortex/cortex-mcp auth google (or outlook / caldav). This authenticates and configures timezone, week start, and telemetry preferences.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["-y", "@temporal-cortex/cortex-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}

Cursor

Add to Cursor's MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["-y", "@temporal-cortex/cortex-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}

Windsurf

Add to Windsurf's MCP config (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["-y", "@temporal-cortex/cortex-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}

Docker

docker run --rm -i \
  -e GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com" \
  -e GOOGLE_CLIENT_SECRET="your-client-secret" \
  -e TIMEZONE="America/New_York" \
  -v ~/.config/temporal-cortex:/root/.config/temporal-cortex \
  cortex-mcp

Build the image first: docker build -t cortex-mcp . (or build directly from the repo: docker build -t cortex-mcp https://github.com/temporal-cortex/mcp.git).

Need help with provider credentials? See the setup guides: Google Calendar, Microsoft Outlook, CalDAV (iCloud/Fastmail). For a complete reference of all environment variables and configuration options, see the Configuration Guide.

How do I verify the installation?

SHA256 checksums are published with every GitHub Release and embedded in the npm package as checksums.json for automatic postinstall verification. The postinstall script downloads the platform-specific binary and compares its SHA256 hash against the expected checksum in checksums.json. On mismatch, installation fails with an error — the binary is not installed and the error message includes both the expected and actual hashes.

Verify manually:

# Download the published checksums
curl -sL https://github.com/temporal-cortex/mcp/releases/download/mcp-v0.9.1/SHA256SUMS.txt

# Compare against your installed binary
sha256sum "$(dirname "$(which cortex-mcp)")/../cortex-mcp" 2>/dev/null || \
  shasum -a 256 "$(npm root -g)/@temporal-cortex/cortex-mcp/bin/cortex-mcp" 2>/dev/null

Build provenance: Binaries are cross-compiled from Rust source in GitHub Actions across 5 platforms (darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64). The computation layer is open source at temporal-cortex/core.

Docker containment: For maximum isolation, run the MCP server in a container:

docker build -t cortex-mcp https://github.com/temporal-cortex/mcp.git
docker run --rm -i -v ~/.config/temporal-cortex:/root/.config/temporal-cortex cortex-mcp

No Node.js on the host, no direct filesystem access beyond the mounted config directory.

How do I authenticate with calendar providers?

The easiest path is npx @temporal-cortex/cortex-mcp setup, which handles authentication, configuration, and MCP client setup in one guided flow. For individual provider auth, run the commands below:

# Google Calendar (default)
npx @temporal-cortex/cortex-mcp auth google

# Microsoft Outlook
npx @temporal-cortex/cortex-mcp auth outlook

# CalDAV (iCloud, Fastmail, or custom server)
npx @temporal-cortex/cortex-mcp auth caldav

# Docker (interactive auth — needs terminal + browser)
docker run --rm -it \
  -e GOOGLE_CLIENT_ID="your-id" -e GOOGLE_CLIENT_SECRET="your-secret" \
  -p 8085:8085 \
  -v ~/.config/temporal-cortex:/root/.config/temporal-cortex \
  cortex-mcp auth google

Each auth flow saves credentials to ~/.config/temporal-cortex/credentials.json and registers the provider in ~/.config/temporal-cortex/config.json. You can connect multiple providers — the server discovers all configured providers on startup and merges their calendars into a unified view.

During auth, the server guides you through interactive setup:

  • Timezone — auto-detects your system timezone and opens a fuzzy-search picker with all 597 IANA timezones (type to filter, arrow keys to navigate)

  • Week start — arrow-key selection between Monday (ISO standard) and Sunday

  • Telemetry — optional anonymous usage data (default: off)

All preferences are stored in ~/.config/temporal-cortex/config.json and used by all temporal tools. You can override them per-session with the TIMEZONE and WEEK_START env vars.

After authentication, verify it works by asking your AI assistant: "What time is it?" — the agent should call get_temporal_context and return your current local time.

For a guided workflow, install the Temporal Cortex Agent Skills to teach your AI agent the orient-resolve-query-book pattern.

Temporal Cortex Platform

Instead of running the MCP server locally via npx, you can use the managed Temporal Cortex Platform. No Node.js installation or local OAuth credentials required.

Getting started:

  1. Sign up at app.temporal-cortex.com.

  2. Connect your Google Calendar or Microsoft Outlook account via OAuth in the dashboard.

  3. Generate an API key from the dashboard.

  4. Add the MCP config to your AI client (see examples below).

Claude Desktop (Platform)

Add to your Claude Desktop config file:

{
  "mcpServers": {
    "temporal-cortex": {
      "url": "https://mcp.temporal-cortex.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor (Platform)

Add to Cursor's MCP settings (~/.cursor/mcp.json) using the same format:

{
  "mcpServers": {
    "temporal-cortex": {
      "url": "https://mcp.temporal-cortex.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Platform capabilities (beyond Local Mode):

  • No OAuth credentials to manage -- calendar connections are handled in the dashboard via standard OAuth flows.

  • No Node.js required -- the client connects directly to the cloud endpoint over HTTP.

  • Usage dashboard -- monitor tool calls, connected calendars, and billing from app.temporal-cortex.com.

  • Managed calendar connections -- token refresh, re-authentication, and provider health are handled server-side.

  • Multi-agent coordination -- distributed locking prevents double-bookings when multiple agents schedule simultaneously.

  • Usage metering -- track tool calls per agent and team from the dashboard.

  • Content firewall -- automatic prompt injection detection and zero-width Unicode stripping.

  • Caller-based policies -- enforce booking rules per agent (max duration, allowed hours, booking limits).

All 15 core tools and 5 layers work identically. The Platform adds safety, coordination, and visibility infrastructure on top, plus 3 additional Open Scheduling tools (see below).

Open Scheduling + Temporal Links

Platform users can enable Open Scheduling to make their availability publicly queryable by AI agents and humans — no API key required.

  1. Go to Settings > Scheduling in the dashboard.

  2. Set a slug (e.g., billy) and enable Open Scheduling.

  3. Share your Temporal Link: book.temporal-cortex.com/billy

What callers get:

  • Agent Card (A2A discovery): GET /public/{slug}/.well-known/agent-card.json

  • Availability (REST): GET /public/{slug}/availability?date=2026-03-15

  • Booking (REST): POST /public/{slug}/book

  • A2A JSON-RPC: POST /public/{slug}/a2a with query_availability or book_slot methods

  • Identity resolution: GET /resolve?identity=email@example.com resolves to the user's Agent Card

Human fallback: The same Temporal Link works in a browser — humans see a booking page with date/time picker and form.

Viral loop: Every Agent Card exposes Temporal Cortex to the calling agent's framework. Every booking includes "Powered by Temporal Cortex" in the event description.

What tools does Temporal Cortex provide?

Temporal Cortex exposes up to 18 Model Context Protocol tools organized in 5 layers. The 15 core tools are always available; 3 additional Open Scheduling tools are available in Platform Mode.

Layer 0 — Discovery

Tool

Description

resolve_identity

Resolves an identity (email, slug, or URL) to a Temporal Cortex user's Agent Card — returns slug, display name, and Open Scheduling status. Platform Mode only.

search_contacts

Searches the user's address book by name (Google People API, Microsoft Graph). Returns matching contacts with emails, phones, organization, and job title. Opt-in — requires contacts permission.

resolve_contact

Given a confirmed contact's email, determines the best scheduling path: Open Scheduling (instant booking), email, or phone. Chains with resolve_identity when Platform API is available.

Layer 1 — Temporal Context

Tool

Description

get_temporal_context

Returns the current time, timezone, UTC offset, DST status, DST prediction (next transition date and direction), and day of week for the configured locale. Call this tool first in any calendar session.

resolve_datetime

Resolves human language expressions like "next Tuesday at 2pm" or "tomorrow morning" into precise RFC 3339 timestamps.

convert_timezone

Converts any RFC 3339 datetime from one IANA timezone to another, reporting the target timezone's DST status.

compute_duration

Computes the duration between two timestamps, returning days, hours, minutes, and a human-readable string.

adjust_timestamp

Adjusts a timestamp by a compound duration like "+1d2h30m" with DST-aware day-level shifts that preserve wall-clock time.

Layer 2 — Calendar Operations

Tool

Description

list_calendars

Lists all calendars across connected providers with provider-prefixed IDs, names, colors, and access roles. TOON output by default (~40% fewer tokens).

list_events

Lists calendar events within a time range, supporting provider-prefixed IDs. TOON output by default (~40% fewer tokens); use format: "json" for JSON.

find_free_slots

Finds available time slots in a calendar by computing gaps between events, with support for minimum slot duration. TOON output by default.

expand_rrule

Expands RFC 5545 recurrence rules into concrete datetime instances, handling DST transitions, BYSETPOS, leap years, and EXDATE exclusions deterministically. TOON output by default.

check_availability

Checks whether a specific time slot is available by examining both calendar events and active booking locks.

Layer 3 — Availability

Tool

Description

get_availability

Merges free/busy data across multiple calendars into a single unified view with configurable privacy levels (Opaque or Full). TOON output by default.

query_public_availability

Queries another user's public availability by slug — returns available time slots for a given date and duration. No API key required. Platform Mode only.

Layer 4 — Booking

Tool

Description

book_slot

Books a calendar slot using Two-Phase Commit: acquires a time-range lock, verifies no conflicts exist, writes the event, then releases the lock.

request_booking

Requests a booking on another user's public calendar by slug — creates a calendar event on their behalf with attendee and title information. Platform Mode only.

compose_proposal

Composes a scheduling proposal message for email, Slack, or SMS with proposed time slots formatted in the recipient's timezone. Includes optional Temporal Link self-serve booking URL. Does NOT send — returns formatted text for the agent to send via its channel MCP.

See docs/tools.md for full input/output schemas and usage examples.

How does Temporal Cortex handle recurrence rules?

Most AI models and calendar tools silently fail on recurrence rule edge cases. Run the challenge to see the difference:

npx @temporal-cortex/cortex-mcp rrule-challenge

5 cases where LLMs consistently fail

1. "Third Tuesday of every month" across DST (March 2026, America/New_York)

The third Tuesday is March 17. Spring-forward on March 8 shifts UTC offsets from -05:00 to -04:00. LLMs often produce the wrong UTC time or skip the month entirely.

2. "Last Friday of every month" (BYSETPOS=-1)

RRULE:FREQ=MONTHLY;BYDAY=FR;BYSETPOS=-1 — LLMs frequently return the first Friday instead of the last, or fail to handle months with 4 vs 5 Fridays.

3. "Every weekday except holidays" (EXDATE with timezone)

EXDATE values with explicit timezone offsets require exact matching against generated instances. LLMs often ignore EXDATE entirely or apply it to the wrong date.

4. "Biweekly on Monday, Wednesday, Friday" (INTERVAL=2 + BYDAY)

RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE,FR — The INTERVAL=2 applies to weeks, not individual days. LLMs frequently generate every-week occurrences instead of every-other-week.

5. "February 29 yearly" (leap year recurrence)

RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=29 — Should only produce instances in leap years (2028, 2032...). LLMs often generate Feb 28 or Mar 1 in non-leap years.

Truth Engine handles all of these deterministically using the RFC 5545 specification. No inference, no hallucination.

How does the MCP server architecture work?

The MCP server is a single Rust binary distributed via npm and Docker. It runs locally on your machine and communicates with MCP clients over stdio (standard input/output) or streamable HTTP.

Request flow in 4 stages:

  1. Receive — The server accepts JSON-RPC messages from MCP clients over stdio (default) or streamable HTTP (when HTTP_PORT is set).

  2. Resolve — Truth Engine converts human datetime expressions into precise UTC timestamps, handling timezone conversion and DST transitions deterministically.

  3. Compute — For availability queries, the engine merges free/busy data across all connected calendar providers. For RRULE expansion, it generates concrete instances following RFC 5545 rules.

  4. Execute — For booking operations, Two-Phase Commit acquires a lock, verifies the slot is free, writes the event, and releases the lock. Failure at any step triggers rollback.

TOON (Token-Oriented Object Notation) compresses calendar data for LLM consumption — ~40% fewer tokens than JSON, with perfect roundtrip fidelity. TOON is the default output format for all data tools; use format: "json" when you need structured JSON.

Stdio vs HTTP Transport

Transport mode is auto-detected — set HTTP_PORT to switch from stdio to HTTP.

  • Stdio (default): Standard MCP transport for local clients (Claude Desktop, VS Code, Cursor). The server reads/writes JSON-RPC messages over stdin/stdout.

  • HTTP (when HTTP_PORT is set): Streamable HTTP transport per MCP 2025-11-25 spec. The server listens on http://{HTTP_HOST}:{HTTP_PORT}/mcp with SSE streaming, session management (Mcp-Session-Id header), and Origin validation. Requests with an invalid Origin header are rejected with HTTP 403.

# HTTP mode example
HTTP_PORT=8009 npx @temporal-cortex/cortex-mcp

Local Mode vs Platform Mode

Mode is auto-detected — there is no configuration flag.

  • Local Mode (default): No infrastructure required. Uses in-memory locking and local file credential storage. Supports multiple calendar providers (Google, Outlook, CalDAV) with multi-calendar availability merging. Designed for individual developers.

  • Platform Mode (managed service at mcp.temporal-cortex.com): Managed multi-tenant hosting with Postgres-backed credentials, Bearer token authentication, guardrails (rate limiting + booking caps), usage metering, and distributed locking for multi-agent safety. Designed for teams and production deployments.

How do I configure Temporal Cortex?

Variable

Required

Default

Description

GOOGLE_CLIENT_ID

For Google

—

Google OAuth Client ID from Cloud Console

GOOGLE_CLIENT_SECRET

For Google

—

Google OAuth Client Secret

GOOGLE_OAUTH_CREDENTIALS

No

—

Path to Google OAuth JSON credentials file (alternative to CLIENT_ID + CLIENT_SECRET)

MICROSOFT_CLIENT_ID

For Outlook

—

Azure AD application (client) ID for Outlook calendar access

MICROSOFT_CLIENT_SECRET

For Outlook

—

Azure AD client secret for Outlook calendar access

TIMEZONE

No

auto-detected

IANA timezone override (e.g., America/New_York). Overrides stored config and OS detection.

WEEK_START

No

monday

Week start day: monday (ISO 8601) or sunday. Affects "start of week", "next week", etc.

REDIS_URLS

No

—

Comma-separated Redis URLs for distributed locking within Platform Mode. Optional — falls back to in-memory locking if not set.

TENANT_ID

No

auto-generated

UUID for tenant isolation

LOCK_TTL_SECS

No

30

Lock time-to-live in seconds

OAUTH_REDIRECT_PORT

No

8085

Port for the local OAuth callback server

HTTP_PORT

No

—

Port for HTTP transport. When set, enables streamable HTTP mode instead of stdio.

HTTP_HOST

No

127.0.0.1

Bind address for HTTP transport. Use 0.0.0.0 only behind a reverse proxy.

ALLOWED_ORIGINS

No

—

Comma-separated allowed Origin headers for HTTP mode (e.g., http://localhost:3000). All cross-origin requests rejected if unset.

At least one calendar provider must be configured. See the provider setup guides: Google Calendar, Microsoft Outlook, CalDAV (iCloud/Fastmail). For a complete configuration reference, see the Configuration Guide.

How do I troubleshoot common issues?

Problem

Solution

"No credentials found"

Run npx @temporal-cortex/cortex-mcp auth google (or outlook / caldav) to authenticate

OAuth error / "Access blocked"

Verify GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET (or MICROSOFT_CLIENT_ID and MICROSOFT_CLIENT_SECRET for Outlook) are correct. Ensure the OAuth consent screen is configured.

Port 8085 already in use

Set OAUTH_REDIRECT_PORT to a different port (e.g., 8086)

Server not appearing in MCP client

Ensure Node.js 18+ is installed (node --version). Check your MCP client's logs for errors.

Provider not discovered on startup

Verify the provider is registered in ~/.config/temporal-cortex/config.json (run auth again if needed)

See provider-specific troubleshooting: Google Calendar, Microsoft Outlook, CalDAV.

Frequently Asked Questions

Does Temporal Cortex work without internet access?

Layer 1 tools (temporal context, datetime resolution, timezone conversion, duration computation, timestamp adjustment) are pure computation and need no network access. Calendar tools (Layers 2-4) require network access to reach Google Calendar, Microsoft Outlook, or CalDAV APIs. The MCP server itself runs locally on your machine.

Which AI clients are supported?

Any Model Context Protocol-compatible client works. Tested configurations are provided for Claude Desktop, Claude Code, VS Code with GitHub Copilot, Cursor, and Windsurf. The server uses stdio transport by default and also supports streamable HTTP transport for custom integrations.

How do I use Temporal Cortex with CrewAI?

Temporal Cortex works with CrewAI via the native MCPServerAdapter — no wrapper needed. See the CrewAI integration guide and example code for a complete multi-agent scheduling crew.

Quick start (DSL — simplest):

from crewai import Agent
from crewai.mcp import MCPServerStdio

scheduler = Agent(
    role="Calendar Scheduling Assistant",
    goal="Schedule meetings using deterministic calendar tools",
    backstory="You always call get_temporal_context first to orient in time.",
    mcps=[
        MCPServerStdio(
            command="npx",
            args=["-y", "@temporal-cortex/cortex-mcp"],
            env={"TIMEZONE": "America/New_York"},
        ),
    ],
)

Platform Mode (SSE — no local server):

from crewai.mcp import MCPServerSSE

scheduler = Agent(
    ...,
    mcps=[
        MCPServerSSE(
            url="https://mcp.temporal-cortex.com/mcp",
            headers={"Authorization": "Bearer YOUR_API_KEY"},
        ),
    ],
)

How do I use Temporal Cortex with LangGraph?

Temporal Cortex works with LangGraph via langchain-mcp-adapters — the adapter auto-discovers all MCP tools and converts them into LangChain-compatible StructuredTool objects. See the LangGraph integration guide and example code for ReAct agent, multi-agent StateGraph, and human-in-the-loop examples.

Quick start (ReAct agent):

from langchain_anthropic import ChatAnthropic
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

model = ChatAnthropic(model="claude-sonnet-4-6")

async with MultiServerMCPClient(
    {
        "temporal-cortex": {
            "command": "npx",
            "args": ["-y", "@temporal-cortex/cortex-mcp"],
            "env": {"TIMEZONE": "America/New_York"},
            "transport": "stdio",
        }
    }
) as client:
    tools = client.get_tools()
    agent = create_react_agent(model, tools)

Platform Mode (HTTP — no local server):

async with MultiServerMCPClient(
    {
        "temporal-cortex": {
            "url": "https://mcp.temporal-cortex.com/mcp",
            "headers": {"Authorization": "Bearer YOUR_API_KEY"},
            "transport": "streamable_http",
        }
    }
) as client:
    tools = client.get_tools()
    agent = create_react_agent(model, tools)

How do I use Temporal Cortex with OpenAI Agents SDK?

Temporal Cortex works with the OpenAI Agents SDK via HostedMCPTool — OpenAI handles the MCP connection server-side, no local server needed. See the OpenAI Agents SDK integration guide and example code for single-agent, multi-agent, and approval workflow examples.

Quick start:

from agents import Agent, HostedMCPTool

agent = Agent(
    name="Calendar Scheduler",
    instructions="You schedule meetings using Temporal Cortex calendar tools.",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "temporal-cortex",
                "server_url": "https://mcp.temporal-cortex.com/mcp",
                "headers": {"Authorization": "Bearer YOUR_API_KEY"},
                "require_approval": "never",
            }
        ),
    ],
)

Can I connect multiple calendar providers simultaneously?

Yes. Run the auth flow for each provider (Google, Outlook, CalDAV) separately. The server discovers all configured providers on startup and merges their calendars into a unified availability view. Use provider-prefixed IDs like google/primary or outlook/work to target specific calendars.

How does Two-Phase Commit prevent double-bookings?

When book_slot is called, the server acquires a time-range lock, verifies no conflicting events or active locks exist, writes the event to the calendar API, then releases the lock. If any step fails, the operation rolls back. Two agents booking the same slot simultaneously will have exactly one succeed and the other receive a clear error.

What is TOON and why does it reduce costs?

TOON (Token-Oriented Object Notation) compresses calendar payloads by ~40% fewer tokens compared to JSON (38% on a Google Calendar event schema benchmark) while maintaining perfect roundtrip fidelity. Fewer tokens means lower API costs and more room in the LLM context window. TOON is now the default output format for all data tools (list_calendars, list_events, find_free_slots, expand_rrule, get_availability). Use format: "json" to get JSON output instead.

How does Temporal Cortex handle daylight saving time?

All temporal tools are DST-aware. adjust_timestamp with "+1d" across a spring-forward boundary preserves wall-clock time (1:00 AM EST becomes 1:00 AM EDT). RRULE expansion keeps recurring events at their local time across DST transitions. get_temporal_context reports whether DST is currently active and predicts the next DST transition — including the transition date, direction (spring-forward or fall-back), and days until it occurs.

What is the difference between Local Mode and Platform Mode?

Local Mode (default) runs on your machine with in-memory locking, local file credential storage, and no infrastructure required — all 15 core tools work with zero setup (contact tools require opt-in contacts permission). Platform Mode (at mcp.temporal-cortex.com) adds managed OAuth lifecycle, multi-agent coordination with distributed locking, usage metering, caller-based policies, a content firewall, a dashboard UI, and 3 additional Open Scheduling tools (resolve_identity, query_public_availability, request_booking). Both expose the same 15 core tools and 5 layers — the Platform adds safety, coordination, visibility, and up to 18 tools total for teams.

How bad are LLMs at temporal reasoning?

Even the latest frontier models — GPT-5, Claude Sonnet 4, Gemini 2.5 Pro — score below 50% on temporal reasoning tasks (OOLONG benchmark, arXiv:2511.02817). Earlier models scored as low as 29% on scheduling and 13% on duration calculations (Test of Time, ICLR 2025, arXiv:2406.09170). Temporal questions are consistently the most challenging category for LLMs. Temporal Cortex replaces LLM inference with deterministic computation for all calendar math.

Is there a managed cloud option?

Yes. The Temporal Cortex Platform is available at app.temporal-cortex.com. Sign up for free — individuals get 20 bookings/month on the Starter tier, developers get 100 bookings/month. Paid tiers (Individual Pro, Developer Growth/Scale) add higher limits and priority support. All scheduling features are available on every tier, including free.

Does Temporal Cortex collect telemetry?

During setup, an interactive prompt asks if you'd like to share anonymous usage data (default: off).

Collected: tool names, success/error counts, platform, version. Never collected: calendar data, events, or personal info.

Non-interactive sessions (MCP stdio) auto-opt-out. Change your choice anytime:

export TEMPORAL_CORTEX_TELEMETRY=off

How do I teach my AI agent the scheduling workflow?

The Temporal Cortex Agent Skills teach AI agents the correct workflow for using these tools — from temporal orientation through conflict-free booking. Install them to give your agent procedural knowledge for calendar operations:

# Claude Code
npx skills add temporal-cortex/skills

The skill follows the Agent Skills specification and works with Claude Code, OpenAI Codex, Google Gemini, GitHub Copilot, Cursor, and 20+ other platforms.

What is the computation layer behind Temporal Cortex?

The computation layer is open source:

  • temporal-cortex-core — Truth Engine (temporal resolution, RRULE expansion, availability merging, timezone conversion) + TOON (token compression)

  • Available on crates.io, npm, and PyPI

  • 510+ Rust tests, 42 JS tests, 30 Python tests, ~9,000 property-based tests

Contributing

Bug reports and feature requests are welcome. See CONTRIBUTING.md.

License

MIT

Available Tools

18 tools
adjust_timestampA
Read-onlyIdempotent

Adjust a timestamp by adding or subtracting a duration. DST-aware: '+1d' preserves wall-clock time across daylight saving transitions.

ParametersJSON Schema
NameRequiredDescriptionDefault
datetimeYesRFC 3339 datetime to adjust.
adjustmentYesDuration adjustment (e.g., "+2h", "-30m", "+1d2h").
timezoneNoIANA timezone for day-level adjustments. Omit to use configured timezone.

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds the critical behavioral nuance of DST-awareness beyond the annotations (which indicate read-only and idempotent). This is a significant trait that helps the agent understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each essential: first states purpose, second adds key behavioral detail. No waste, front-loaded with action verb.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple operation and rich annotations, the description is nearly complete. It could specify the return format (e.g., RFC 3339 datetime), but the schema and annotations cover safety and parameters adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear parameter descriptions. The tool description adds extra context on the adjustment parameter's DST effect, enhancing understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (adjust), the resource (timestamp), and the method (adding/subtracting duration). It also highlights DST-awareness, distinguishing it from sibling tools like convert_timezone and resolve_datetime.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit context on DST-aware behavior, guiding when to use this tool for wall-clock preservation. However, it lacks explicit 'when-not-to-use' or alternatives, though the context is clear given the sibling list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

book_slotB

Book a calendar slot using Two-Phase Commit for safe, conflict-free booking.

ParametersJSON Schema
NameRequiredDescriptionDefault
calendar_idYesCalendar ID to book in (UUID string).
startYesStart time for the booking (RFC 3339 datetime string).
endYesEnd time for the booking (RFC 3339 datetime string).
summaryYesEvent summary/title.
descriptionNoOptional event description.
locationNoOptional meeting location (e.g., "Conference Room A", "https://zoom.us/j/123").
attendeesNoOptional list of attendee email addresses.

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate mutation (readOnlyHint=false) and no idempotency. Description adds 'Two-Phase Commit' context but doesn't fully disclose side effects or permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with verb and noun. No unnecessary words; efficient and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a booking tool with 7 parameters and no output schema, the description lacks details on return values, prerequisites, and explanation of two-phase commit. Incomplete given complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are already well-defined. The tool description adds no extra semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it books a calendar slot with two-phase commit, but does not differentiate from sibling tools like 'request_booking' which may serve a similar purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this vs alternatives (e.g., request_booking, check_availability). The description only hints at safety but lacks explicit usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_availabilityA
Read-onlyIdempotent

Check if a calendar time slot is available (not held by another booking).

ParametersJSON Schema
NameRequiredDescriptionDefault
calendar_idYesCalendar ID to check (UUID string).
startYesStart of the time slot (RFC 3339 datetime string).
endYesEnd of the time slot (RFC 3339 datetime string).

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the insight that availability means 'not held by another booking', but does not describe other behavioral traits (e.g., whether it checks conflicts or just free status).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with zero waste. Every word contributes to the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple boolean-check tool with 3 well-documented parameters and strong annotations, the description is nearly complete. It could hint at the return format (e.g., 'returns a boolean'), but the purpose is clear enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with each parameter having a clear description (UUID, RFC 3339 datetime). The description adds no new meaning beyond the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb-resource pair ('Check if a calendar time slot is available') and clarifies the scope ('not held by another booking'). It clearly distinguishes from sibling tools like 'book_slot' (which books) and 'get_availability' (which likely returns a list of slots).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for checking a specific slot before booking, but does not explicitly state when to use this tool vs. alternatives like 'get_availability' or 'find_free_slots'. No exclusions or alternative names are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compose_proposalA
Read-onlyIdempotent

Compose a scheduling proposal message with proposed time slots. Formats times in the specified timezone for email, Slack, or SMS. Does NOT send the message — returns formatted text for the agent to send via its channel MCP (Gmail, Slack, etc.).

ParametersJSON Schema
NameRequiredDescriptionDefault
contact_nameYesName of the person to schedule with.
contact_emailYesEmail address of the contact.
duration_minutesYesMeeting duration in minutes.
proposed_slotsYesProposed time slots (from find_free_slots).
timezoneYesDisplay timezone for the message (IANA, e.g., "America/New_York").
meeting_titleNoOptional meeting title.
meeting_descriptionNoOptional meeting description.
temporal_link_slugNoTemporal Link slug if the recipient has Open Scheduling.
formatNoOutput format: "email" (default), "slack", or "sms".

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and idempotentHint=true, and the description confirms it does not send messages, only returns formatted text. No contradictions; behavioral traits are fully disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at two sentences, front-loads the main purpose, and each sentence adds essential information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity and full schema coverage, the description is nearly complete. It could mention that the output is a plain text string, but the return format is implied by 'formatted text'. Annotations support completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameters with descriptions. The description provides no additional parameter details beyond what the schema already offers, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool composes a scheduling proposal message with time slots, formatting for email, Slack, or SMS. It distinguishes from sending by explicitly stating it does NOT send the message, leaving that to channel MCPs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool (to compose a proposal message) and clarifies it does not send, implying the agent must use another tool for sending. However, it does not explicitly compare to sibling tools like book_slot or request_booking.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compute_durationA
Read-onlyIdempotent

Compute the duration between two timestamps. Returns days, hours, minutes, seconds, and a human-readable string.

ParametersJSON Schema
NameRequiredDescriptionDefault
startYesFirst timestamp (RFC 3339).
endYesSecond timestamp (RFC 3339).

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds detail on the return format (days, hours, minutes, seconds, human-readable string), which is useful beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, immediately conveys the purpose and output, and contains no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple input schema (2 required parameters, no enums or nested objects) and no output schema, the description adequately explains the return structure. It is complete enough for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with parameter descriptions, so the baseline is 3. The description does not add semantic meaning beyond what the schema already provides (e.g., both mention RFC 3339 timestamps).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool computes the duration between two timestamps, using a specific verb ('compute') and resource ('duration'). It distinguishes itself from sibling tools like adjust_timestamp and convert_timezone, which handle different temporal operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for computing duration between timestamps but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_timezoneB
Read-onlyIdempotent

Convert a datetime to a different timezone.

ParametersJSON Schema
NameRequiredDescriptionDefault
datetimeYesRFC 3339 datetime string to convert.
target_timezoneYesTarget IANA timezone.

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, indicating the tool is a safe, idempotent read operation. The description adds no further behavioral traits beyond confirming it is a conversion. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (one sentence, 8 words). It gets straight to the point without any fluff. However, it could benefit from a slightly more structured explanation, such as mentioning the output format.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (two parameters, no output schema) and the presence of annotations, the description is minimally complete. It lacks information about the return value or how the converted datetime is represented, which could be important for downstream usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides descriptions for both parameters with 100% coverage. The description adds no additional meaning or context about the parameters, such as format constraints or example values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action of converting a datetime to a different timezone. It specifies the verb 'convert' and the resource 'datetime'. However, it does not differentiate from sibling tools like 'adjust_timestamp' or 'resolve_datetime', which could also handle time conversions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or how it compares to siblings such as 'adjust_timestamp' or 'compute_duration'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

expand_rruleA
Read-onlyIdempotent

Expand a recurrence rule (RRULE) into concrete event instances.

ParametersJSON Schema
NameRequiredDescriptionDefault
rruleYesRFC 5545 RRULE string (e.g., "FREQ=DAILY;COUNT=5").
dtstartYesLocal datetime string for the start (e.g., "2026-03-01T09:00:00").
duration_minutesNoDuration of each event instance in minutes (default: 60).
timezoneYesIANA timezone (e.g., "America/New_York").
countNoOptional maximum number of instances to return.
formatNoOutput format: "toon" (default, token-efficient) or "json".

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description aligns with annotations (readOnlyHint, idempotentHint) but adds no additional behavioral context beyond what is already implied. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence (9 words) that front-loads the core action and result. No unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, read-only expansion tool with full schema coverage and annotations indicating safety, the description provides sufficient context. However, it could mention output format behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds no extra meaning about parameters beyond the schema's details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'expand' and the resource 'recurrence rule', specifying the output as 'concrete event instances'. This distinguishes it from sibling tools like 'adjust_timestamp' or 'compute_duration' which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or constraints. It lacks context for proper selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_free_slotsA
Read-onlyIdempotent

Find available free time slots in a calendar within a time window.

ParametersJSON Schema
NameRequiredDescriptionDefault
calendar_idYesCalendar ID to check for free slots.
startYesStart of the search window (RFC 3339 datetime string).
endYesEnd of the search window (RFC 3339 datetime string).
min_duration_minutesNoMinimum duration of free slots in minutes (default: 30).
formatNoOutput format: "toon" (default, token-efficient) or "json".

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it finds 'free time slots' which is consistent. However, no additional behavioral context (e.g., what happens if no slots, performance characteristics) is provided beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no redundancy. Every word contributes to the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description does not explain what the tool returns (e.g., list of time slots, format). With 5 parameters and required ones, more context about expected results would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already describes all 5 parameters. The description does not add any extra meaning beyond what is in the input schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Find' and resource 'free time slots' with scope 'in a calendar within a time window', which is specific and distinguishes it from sibling tools like 'get_availability'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool vs alternatives, nor any when-not-to-use conditions. Sibling tools like 'book_slot' and 'get_availability' exist but no differentiation is offered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_availabilityA
Read-onlyIdempotent

Get unified availability across multiple calendars. Merges events from all specified calendars into a single busy/free view with privacy controls.

ParametersJSON Schema
NameRequiredDescriptionDefault
startYesStart of the availability window (RFC 3339 datetime string).
endYesEnd of the availability window (RFC 3339 datetime string).
privacyNoPrivacy mode: "opaque" (default) hides source counts, "full" shows them.
min_free_slot_minutesNoMinimum free slot duration in minutes (default: 30).
calendar_idsNoCalendar IDs to query. If omitted, queries "primary".
formatNoOutput format: "toon" (default, token-efficient) or "json".
working_hours_onlyNoIf true, only return free slots within configured working hours (default: false). Uses the tenant's configured working hours (default 09:00–17:00) and timezone.

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable context about merging behavior and privacy controls, which aligns with and extends the annotations. No contradictions, and the description contributes meaningful behavioral details beyond the structured hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the core function. It front-loads the key action ('Get unified availability') and adds essential context. While it could be more structured, it is sufficiently concise and informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the full schema documentation and rich annotations, the description covers the main purpose and key behaviors (merging and privacy). While it does not explain return values (no output schema) or list all parameters, the schema fills most gaps. The description adds sufficient context for a read-only aggregation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents each parameter. The description only mentions 'privacy controls' which repeats the privacy parameter. No additional parameter semantics beyond the schema are provided, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves unified availability across multiple calendars, merging events into a busy/free view. It distinguishes from siblings like check_availability by mentioning merging and privacy controls, making the purpose specific and actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as find_free_slots or check_availability. No when-not-to-use or context exclusions are provided, leaving the agent without decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_temporal_contextA
Read-onlyIdempotent

Get the current temporal context — time, timezone, calendar metadata. Call this first to orient yourself in time before making calendar queries.

ParametersJSON Schema
NameRequiredDescriptionDefault
timezoneNoIANA timezone (e.g., "America/New_York"). Omit to use configured timezone.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint. Description adds that it returns 'time, timezone, calendar metadata,' which aligns with and enriches annotation info.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with action and purpose. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional param and no output schema, the description covers purpose, usage, and return info completely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a thorough parameter description. The tool description adds no additional parameter detail beyond 'current temporal context,' so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get the current temporal context' with a specific verb and resource. It distinguishes itself from sibling time-related tools by focusing on current context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises 'Call this first to orient yourself in time before making calendar queries,' providing clear context for use, though it doesn't list alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_calendarsA
Read-onlyIdempotent

List all connected calendars across providers. Returns calendar IDs, names, labels, and metadata. Call this first to discover what calendars are available before using other calendar tools.

ParametersJSON Schema
NameRequiredDescriptionDefault
providerNoFilter to a specific provider ("google", "outlook", "caldav"). Omit for all providers.
formatNoOutput format: "toon" (default) or "json".

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so safety is well-covered. The description adds that it returns metadata, but doesn't disclose additional behavioral traits beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: first covers purpose and output, second provides usage guidance. No wasted words, front-loaded information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with two optional parameters and no output schema, the description fully covers purpose, output, and usage context. Annotations handle safety, making additional details unnecessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. The description does not add new semantic information beyond what is in the schema, meeting the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all connected calendars across providers and returns specific fields (IDs, names, labels, metadata). It distinguishes itself from siblings by recommending it as a first step before using other calendar tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises calling this first to discover available calendars. While it doesn't list when not to use, the positive guidance is clear and contextually sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_eventsA
Read-onlyIdempotent

List calendar events in a time range. Returns events in TOON or JSON format.

ParametersJSON Schema
NameRequiredDescriptionDefault
calendar_idYesCalendar ID to list events from.
startYesStart of the time range (RFC 3339 datetime string).
endYesEnd of the time range (RFC 3339 datetime string).
queryNoOptional search query to filter events by summary or description keyword (case-insensitive).
formatNoOutput format: "toon" or "json" (default: "json").

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already convey read-only, non-destructive, idempotent behavior. The description adds that results return in two formats but lacks details on pagination, ordering, or edge cases like empty results. Some value beyond annotations but limited.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, no redundant information, and front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description lacks details about the return structure of events, but it covers the essential functionality. Annotations provide safety context. Mostly complete for a list tool with moderate complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with clear parameter descriptions (e.g., RFC 3339 format, optional query/format). The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'list calendar events' with a specific constraint 'in a time range' and mentions output formats, distinguishing it from sibling tools like book_slot or find_free_slots.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, no explicit context or exclusions, and no mention of alternatives even though siblings exist.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_public_availabilityA
Read-onlyIdempotent

Query another user's public availability by their Temporal Link slug. Returns available time slots for a given date. Use after resolve_identity to find the slug. Requires Platform Mode.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYesTemporal Link slug (e.g., "jane-doe").
dateYesDate to query in YYYY-MM-DD format.
duration_minutesNoMinimum slot length in minutes (default: 30).
timezoneNoIANA timezone for response times (e.g., "America/New_York").

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint; description adds behavioral detail on returning time slots and requiring Platform Mode, adding value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load purpose and provide usage guidance with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, description adequately explains return type (time slots) and prerequisites, covering essential context for a read-only query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% description coverage for all 4 parameters, so the description adds minimal additional parameter meaning beyond what is already provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool queries another user's public availability using a Temporal Link slug and returns time slots, distinguishing it from siblings like check_availability.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises using after resolve_identity to find the slug and notes requirement for Platform Mode, providing clear usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

request_bookingA

Book a meeting on another user's public calendar by their Temporal Link slug. Requires attendee_email. Content sanitization and Two-Phase Commit happen server-side. If the slot is taken, returns a 409 Conflict error — query availability again. Requires Platform Mode.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYesTemporal Link slug (e.g., "jane-doe").
startYesStart time for the booking (RFC 3339 datetime string).
endYesEnd time for the booking (RFC 3339 datetime string).
titleYesMeeting title.
attendee_emailYesYour email address (required for the calendar invitation).
attendee_nameNoYour display name (optional).
descriptionNoOptional meeting description.

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses content sanitization, two-phase commit, and 409 error behavior. This adds significant behavioral context not captured in annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two substantive sentences, front-loading the core purpose. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, requirements, error handling, and server-side processes. However, it omits the response format (e.g., success indicators) and does not clarify the distinction from the sibling 'book_slot', leaving some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds no per-parameter details beyond what the schema already provides, but does not detract from it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool books a meeting using a Temporal Link slug, with the verb 'Book' and resource clearly identified. However, it does not differentiate from the sibling tool 'book_slot', limiting its distinctiveness.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions 'Requires Platform Mode' and advises querying availability on 409 conflict, providing some usage context. However, it lacks explicit guidance on when to use this tool versus alternatives like 'book_slot' or 'check_availability'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_contactA
Read-onlyIdempotent

Resolve a contact's email to available scheduling paths. Returns the best way to schedule with them: Open Scheduling (instant booking), email, or phone. Call after search_contacts to determine the scheduling method.

ParametersJSON Schema
NameRequiredDescriptionDefault
emailYesEmail address of the contact to resolve scheduling paths for.
phoneNoOptional phone number (used as a fallback scheduling channel).

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds no additional behavioral details beyond the return types (Open Scheduling, email, phone). For a safe, read-only tool, this is sufficient but not exceptional.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, to the point, with no unnecessary words. The description is front-loaded with the primary purpose and efficiently conveys usage guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with no output schema, the description fully explains what it does, what it returns, and its relationship to siblings. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage with descriptions for both parameters. The tool description does not add meaning beyond the schema; it mentions resolving the email but does not describe the parameters further. Baseline 3 is appropriate given schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool resolves a contact's email to available scheduling paths, returning the best scheduling method. It distinguishes itself from siblings by specifying it should be called after search_contacts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to call after search_contacts, which is a sibling tool, providing clear contextual usage. This tells the agent when to use this tool and its place in a workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_datetimeA
Read-onlyIdempotent

Resolve a human-readable time expression to an absolute datetime. Supports: 'next Tuesday at 2pm', 'tomorrow morning', '+3h', 'in 2 hours', 'start of next week', RFC 3339 passthrough, and more.

ParametersJSON Schema
NameRequiredDescriptionDefault
expressionYesTime expression (e.g., "next Tuesday at 2pm", "tomorrow", "+3h", or RFC 3339).
timezoneNoIANA timezone. Omit to use configured timezone.

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds that it supports various expression types and RFC 3339 passthrough, but does not disclose additional behaviors like error handling or output format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first states the core purpose, the second lists supported expression types. It is front-loaded, concise, and contains no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 2 parameters and no output schema. The description covers input expression types well but omits return format, error handling, or any constraints. For a complex parsing tool, more detail would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for both parameters. The description provides examples but adds limited semantic value beyond the schema; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Resolve a human-readable time expression to an absolute datetime.' It provides specific examples and mentions RFC 3339 passthrough, making the purpose unambiguous and distinct from sibling tools like compute_duration or convert_timezone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for natural language time expressions but does not explicitly state when to use this tool versus alternatives like compute_duration or convert_timezone. No when-to-use or when-not-to-use guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_identityA
Read-onlyIdempotent

Resolve an email, phone, or agent ID to a Temporal Cortex slug (DNS for Human Time). Use this to find someone's Open Scheduling profile before querying their availability or booking a meeting. Requires Platform Mode.

ParametersJSON Schema
NameRequiredDescriptionDefault
identityYesEmail address, phone number, or agent ID to resolve to a Temporal Link slug.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by stating the requirement of Platform Mode and the output type (slug). No contradictions; behavioral traits are sufficiently disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. The purpose is front-loaded, and the usage context is provided succinctly. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema) and rich annotations, the description fully covers what an agent needs: input types, output concept, usage context, and a prerequisite. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has full coverage (100%) with a clear description for the single parameter. The description adds extra meaning by specifying the types (email, phone, or agent ID) and the resolution result (slug), going beyond the schema's generic description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the action ('Resolve'), the inputs ('email, phone, or agent ID'), and the output ('Temporal Cortex slug'). It also provides context for usage ('find someone's Open Scheduling profile'), clearly distinguishing it from siblings like 'resolve_contact' or 'resolve_datetime'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear use case ('before querying their availability or booking a meeting') and mentions a prerequisite ('Requires Platform Mode'). While it doesn't explicitly list exclusions or when not to use, the guidance is adequate for a simple tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_contactsA
Read-onlyIdempotent

Search your contacts by name. Returns matching contacts with emails, phone numbers, organization, and job title. Requires contacts permission to be configured.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesName to search for (e.g., "Jane", "John Smith"). Fuzzy matching.
max_resultsNoMaximum number of results (default: 10, max: 30).

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. Description adds that it uses fuzzy matching and returns specific fields, but does not significantly expand on behavioral traits beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The first sentence states purpose, the second adds return fields and permission requirement. Efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description provides key return fields and permission requirement. With 2 params and clear annotations, this is nearly complete, though it could mention result limits or ordering.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% description coverage, so baseline is 3. Description does not add additional meaning beyond the schema; it only states 'Search your contacts by name' without elaborating on parameter usage or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool searches contacts by name and returns specific fields (emails, phone numbers, organization, job title). Distinguishes from sibling 'resolve_contact' by focusing on search rather than resolution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Mentions required permission ('contacts permission to be configured'), but does not specify when to use this over alternatives like 'resolve_contact' or under what conditions to choose this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 18 tool updatesv0.7.7
    • Addedadjust_timestamp
    • Addedbook_slot
    • Addedcheck_availability
    • Addedcompose_proposal
    • Addedcompute_duration
    • Addedconvert_timezone
    • Addedexpand_rrule
    • Addedfind_free_slots
    • Addedget_availability
    • Addedget_temporal_context
    • Addedlist_calendars
    • Addedlist_events
    • Addedquery_public_availability
    • Addedrequest_booking
    • Addedresolve_contact
    • Addedresolve_datetime
    • Addedresolve_identity
    • Addedsearch_contacts
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 18 tools

Disambiguation5/5

Each tool has a clearly distinct purpose. While some tools like check_availability, find_free_slots, and get_availability relate to availability, they differ in granularity (specific slot vs. range vs. unified view). book_slot and request_booking are distinguished by context (own vs. public calendar). No two tools could be easily confused.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case (e.g., adjust_timestamp, compute_duration, resolve_datetime). No mixing of conventions or vague verbs. The pattern is predictable and aids agent selection.

Tool Count4/5

18 tools is slightly above the typical 3-15 range, but each tool addresses a specific need in the scheduling domain (time manipulation, calendar query, booking, identity resolution). The count is justified by the comprehensive scope, though some consolidation could be possible.

Completeness3/5

The tool surface covers creation (book_slot, request_booking) and reading (list_events, check_availability) of bookings, but lacks update or delete tools for bookings. This is a notable gap in lifecycle coverage. Time manipulation and contact resolution are well-covered.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Google Calendar

    GongRzhe
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    Google Calendar integration in Cursor IDE. This server enables AI assistants to manage Google Calendar events through natural language interactions.
    14 npm
    5
    ISC

  • calendar-mcp

    deciduus
    A
    license
    A
    quality
    A
    maintenance
    This project implements a Python-based MCP (Model Context Protocol) server that acts as an interface between Large Language Models (LLMs) and the Google Calendar API. It enables LLMs to perform calendar operations via natural language requests.
    23
    166 PyPI
    26
    AGPL 3.0