Skip to content

AGENT_TOOLING.md

Latest commit

 

History

History
104 lines (88 loc) · 3.49 KB

AGENT_TOOLING.md

File metadata and controls

104 lines (88 loc) · 3.49 KB

Agent Tooling Interface (Optional Appendix)

This document provides an optional reference interface (Protocol) for agent systems that want structured tooling around Calendar.md.

Note on "Skills": This document describes the interface. The implementation of this interface (including scripts and configuration) is provided in the separate calendar-skills project.

Why Tooling?

  1. Safety: Prevents agents from corrupting the file format.
  2. Precision: Ensures fields like ISO dates and UUIDs are generated correctly.
  3. Ease of Use: Agents are trained to use tools (Function Calling) more reliably than raw text editing.

Tool Definitions (JSON Schema)

Below are the recommended tool definitions for any Agent System (e.g., OpenAI, Claude, LangChain) integrating with Calendar.md.

1. calendar_add_event

Use this tool to add a new event to the calendar.

{
  "name": "calendar_add_event",
  "description": "Adds a new event to the calendar. This appends a log entry to the monthly log file.",
  "parameters": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "description": "Date of the event in YYYY-MM-DD format",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
      },
      "title": {
        "type": "string",
        "description": "Short title of the event"
      },
      "description": {
        "type": "string",
        "description": "Detailed description or notes"
      },
      "tags": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Tags for categorization (e.g., 'Holiday', 'Work', 'Release')"
      }
    },
    "required": ["date", "title"]
  }
}

2. calendar_update_event

Use this tool to modify an existing event.

{
  "name": "calendar_update_event",
  "description": "Updates an existing event by ID.",
  "parameters": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "The UUID of the event to update"
      },
      "changes": {
        "type": "object",
        "description": "Fields to update",
        "properties": {
          "date": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } }
        }
      },
      "reason": {
        "type": "string",
        "description": "Reason for the update (optional, for audit log)"
      }
    },
    "required": ["id", "changes"]
  }
}

How Agents Use It

  1. Discovery: The system prompt tells the Agent: "You have tools to manage the calendar. Do not edit files directly."
  2. Intent: The user says "Schedule a meeting next Friday."
  3. Call: The Agent calculates the date and calls calendar_add_event({ date: "2023-11-10", title: "Meeting" }).
  4. Execution:
    • The Agent Platform (Runtime) receives the tool call.
    • It generates a new UUID.
    • It creates a log line: 2023... | @agent | ADD | { ... }.
    • It appends this line to .calendar/logs/YYYY/MM.log.
    • It triggers the generate.ts script to update the view.
  5. Response: The system tells the Agent "Event added successfully with ID 123." The Agent tells the user "I've scheduled the meeting."

Operational Constraints

  • Agents must not edit generated view files directly.
  • Agents must append to .calendar/logs/YYYY/MM.log and then regenerate views.
  • Log timestamps must use config.yaml timezone without Z suffix.