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",
        },
        isRecurring: {
          type: "boolean",
          description: "Whether this is a recurring event",
        },
        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)",
        },
      },
      required: ["eventId"],
    },
  },
  {
    name: "proposeDeleteEvent",
    description:
      "Propose deleting an event. The user must confirm. Use this when the user wants to remove an appointment.",
    parameters: {
      type: "object",
      properties: {
        eventId: {
          type: "string",
          description: "ID of the event to delete",
        },
      },
      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"],
    },
  },
];