calchat/apps/server/src/ai/utils/toolDefinitions.ts

/**
 * Parameter definition for tool parameters.
 */
export interface ParameterDef {
  type: "string" | "number" | "boolean" | "object" | "array";
  description?: string;
  enum?: string[];
}

/**
 * Provider-agnostic tool definition format.
 * Can be converted to OpenAI, Claude, or other provider formats.
 */
export interface ToolDefinition {
  name: string;
  description: string;
  parameters: {
    type: "object";
    properties: Record<string, ParameterDef>;
    required: string[];
  };
}

/**
 * All available tools for the calendar assistant.
 */
export const TOOL_DEFINITIONS: ToolDefinition[] = [
  {
    name: "getDay",
    description:
      "Get a date for a specific weekday relative to today. Returns an ISO date string.",
    parameters: {
      type: "object",
      properties: {
        day: {
          type: "string",
          enum: [
            "Monday",
            "Tuesday",
            "Wednesday",
            "Thursday",
            "Friday",
            "Saturday",
            "Sunday",
          ],
          description: "The target weekday",
        },
        offset: {
          type: "number",
          description:
            "1 = next occurrence, 2 = the one after, -1 = last occurrence, etc.",
        },
        hour: {
          type: "number",
          description: "Hour of day (0-23)",
        },
        minute: {
          type: "number",
          description: "Minute (0-59)",
        },
      },
      required: ["day", "offset", "hour", "minute"],
    },
  },
  {
    name: "getCurrentDateTime",
    description: "Get the current date and time as an ISO string",
    parameters: {
      type: "object",
      properties: {},
      required: [],
    },
  },
  {
    name: "proposeCreateEvent",
    description:
      "Propose creating a new calendar event. The user must confirm before it's saved. Call this when the user wants to create a new appointment.",
    parameters: {
      type: "object",
      properties: {
        title: {
          type: "string",
          description: "Event title",
        },
        startTime: {
          type: "string",
          description: "Start time as ISO date string",
        },
        endTime: {
          type: "string",
          description: "End time as ISO date string",
        },
        description: {
          type: "string",
          description: "Optional event description",
        },
        recurrenceRule: {
          type: "string",
          description: "RRULE format string for recurring events",
        },
      },
      required: ["title", "startTime", "endTime"],
    },
  },
  {
    name: "proposeUpdateEvent",
    description:
      "Propose updating an existing event. The user must confirm. Use this when the user wants to modify an appointment.",
    parameters: {
      type: "object",
      properties: {
        eventId: {
          type: "string",
          description: "ID of the event to update",
        },
        title: {
          type: "string",
          description: "New title (optional)",
        },
        startTime: {
          type: "string",
          description: "New start time as ISO date string (optional)",
        },
        endTime: {
          type: "string",
          description: "New end time as ISO date string (optional)",
        },
        description: {
          type: "string",
          description: "New description (optional). NEVER put RRULE here!",
        },
        recurrenceRule: {
          type: "string",
          description:
            "RRULE format string (optional). Use to add UNTIL or modify recurrence. Format: FREQ=DAILY;UNTIL=20260310T000000Z",
        },
      },
      required: ["eventId"],
    },
  },
  {
    name: "proposeDeleteEvent",
    description:
      "Propose deleting an event. The user must confirm. Use this when the user wants to remove an appointment. For recurring events, specify deleteMode to control which occurrences to delete.",
    parameters: {
      type: "object",
      properties: {
        eventId: {
          type: "string",
          description: "ID of the event to delete",
        },
        deleteMode: {
          type: "string",
          enum: ["single", "future", "all"],
          description:
            "For recurring events: 'single' = only this occurrence, 'future' = this and all future, 'all' = entire recurring event. Defaults to 'all' for non-recurring events.",
        },
        occurrenceDate: {
          type: "string",
          description:
            "ISO date string (YYYY-MM-DD) of the specific occurrence to delete. Required for 'single' and 'future' modes.",
        },
      },
      required: ["eventId"],
    },
  },
  {
    name: "searchEvents",
    description:
      "Search for events by title in the user's calendar. Returns matching events.",
    parameters: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Search query to match against event titles",
        },
      },
      required: ["query"],
    },
  },
];