ChronoShield for AI Agents

ChronoShield is a preflight check for time-based AI agent actions. Use it before an agent schedules a meeting, books an appointment, sets a reminder, creates a cron job, calculates a billing date, or converts user-entered local time to UTC.

AI agents shouldn't blindly act on user-entered local datetimes. Some local times don't exist (DST spring-forward gaps). Others occur twice (DST fall-back overlaps). ChronoShield validates these inputs against the IANA timezone database so agents detect the problem and ask the user, instead of silently storing the wrong moment.

When to call ChronoShield

Call validate_local_datetime when an AI agent is about to:

When NOT to call ChronoShield

You usually don't need ChronoShield when:

• ×The datetime is already stored as UTC and you only need to render it in a user's timezone — use a local date library.
• ×You're formatting an already-resolved timestamp for display.
• ×The action doesn't depend on local civil time (e.g., logging a UTC timestamp).
• ×The user-supplied datetime already includes a UTC offset (e.g., 2026-03-08T07:00:00Z) — the offset removes the ambiguity.

Recommended agent behavior

Wire your agent's decision logic to these results:

MCP server (Claude Desktop, Cursor, Windsurf)

For MCP-compatible clients, install the ChronoShield MCP server and the four tools become available natively — no integration code.

Install

npm install -g chronoshield-mcp

Claude Desktop config

Add this to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "chronoshield": {
      "command": "npx",
      "args": ["-y", "chronoshield-mcp"],
      "env": {
        "CHRONOSHIELD_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop. You should see the ChronoShield tools appear in the tool picker. Try: "Schedule a reminder for 2:30 AM on March 8, 2026 in New York."

OpenAI tool calling

Drop the canonical tool schema directly into your tools array. The full set is at /agent-tools.json.

{
  type: "function",
  function: {
    name: "validate_local_datetime",
    description:
      "Preflight check for a user-entered local datetime. Call this BEFORE an agent schedules a meeting, books an appointment, sets a reminder, creates a cron job, calculates a billing date, or converts local time to UTC. Detects DST gaps, DST overlaps, and invalid IANA timezone IDs.",
    parameters: {
      type: "object",
      properties: {
        local_datetime: {
          type: "string",
          description: "Local datetime without offset, e.g. 2026-03-08T02:30:00"
        },
        time_zone: {
          type: "string",
          description: "IANA timezone, e.g. America/New_York"
        }
      },
      required: ["local_datetime", "time_zone"]
    }
  }
}

async function validateLocalDatetime(args) {
  const res = await fetch("https://chronoshieldapi.com/v1/datetime/validate", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.CHRONOSHIELD_API_KEY
    },
    body: JSON.stringify(args)
  });
  return res.json();
}

Claude tool use

Pass the tool definition in your tools parameter to messages.create.

{
  name: "validate_local_datetime",
  description:
    "Preflight check for a user-entered local datetime. Call this BEFORE an agent schedules, books, bills, reminds, converts, or executes a time-based action. Detects DST gaps, DST overlaps, and invalid IANA timezone IDs.",
  input_schema: {
    type: "object",
    properties: {
      local_datetime: { type: "string", description: "Local datetime without offset, e.g. 2026-03-08T02:30:00" },
      time_zone:      { type: "string", description: "IANA timezone, e.g. America/New_York" }
    },
    required: ["local_datetime", "time_zone"]
  }
}

Add to your system prompt: "Use validate_local_datetime before acting on any user-entered local datetime that will create, modify, schedule, book, bill, remind, convert, or execute something."

LangChain

TypeScript example using DynamicStructuredTool:

import { DynamicStructuredTool } from "@langchain/core/tools";
import { z } from "zod";

export const validateLocalDatetime = new DynamicStructuredTool({
  name: "validate_local_datetime",
  description:
    "Preflight check for a user-entered local datetime. Call BEFORE scheduling, booking, billing, reminders, cron jobs, or workflow automation. Detects DST gaps, overlaps, invalid IANA timezone IDs.",
  schema: z.object({
    local_datetime: z.string().describe("Local datetime, e.g. 2026-03-08T02:30:00"),
    time_zone:      z.string().describe("IANA timezone, e.g. America/New_York")
  }),
  func: async ({ local_datetime, time_zone }) => {
    const res = await fetch("https://chronoshieldapi.com/v1/datetime/validate", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.CHRONOSHIELD_API_KEY!
      },
      body: JSON.stringify({ local_datetime, time_zone })
    });
    return JSON.stringify(await res.json());
  }
});

Vercel AI SDK

Using tool() from ai:

import { tool } from "ai";
import { z } from "zod";

export const validateLocalDatetime = tool({
  description:
    "Preflight check for a user-entered local datetime. Call BEFORE an agent schedules, books, bills, reminds, converts, or executes a time-based action.",
  parameters: z.object({
    local_datetime: z.string().describe("Local datetime without offset, e.g. 2026-03-08T02:30:00"),
    time_zone:      z.string().describe("IANA timezone, e.g. America/New_York")
  }),
  execute: async ({ local_datetime, time_zone }) => {
    const res = await fetch("https://chronoshieldapi.com/v1/datetime/validate", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.CHRONOSHIELD_API_KEY!
      },
      body: JSON.stringify({ local_datetime, time_zone })
    });
    return res.json();
  }
});

Plain REST (any framework)

If your agent framework isn't listed above, just call the REST endpoint:

curl -X POST https://chronoshieldapi.com/v1/datetime/validate \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "local_datetime": "2026-03-08T02:30:00",
    "time_zone": "America/New_York"
  }'

Tool catalog

Four tools, in order of how often you'll use them. Full schemas: /agent-tools.json.

End-to-end example: DST gap

1. 1 Agent extracts local_datetime: "2026-03-08T02:30:00", time_zone: "America/New_York"
2. 2 Agent calls validate_local_datetime → receives:

{
  "status": "invalid",
  "reason_code": "DST_GAP",
  "message": "This time does not exist due to DST transition.",
  "suggested_fixes": [
    { "strategy": "next_valid_time", "local_datetime": "2026-03-08T03:00:00" },
    { "strategy": "previous_valid_time", "local_datetime": "2026-03-08T01:59:59" }
  ]
}

3. 3 Agent does NOT schedule silently. Replies: "That time doesn't exist on March 8 — clocks jump from 2:00 AM to 3:00 AM for daylight saving. Want me to schedule it for 3:00 AM instead?"
4. 4 User confirms. Agent calls resolve_datetime with invalid_policy: "next_valid_time" → gets { instant_utc: "2026-03-08T07:00:00.000Z" }
5. 5 Agent stores the UTC instant. No silent misconversion. No 4 AM phone call.

Resources