update_preferences

Overview

The update_preferences tool updates a user’s scheduling preferences, which directly influence how the AI ranks and selects meeting times. This is powerful for:

Customizing work hours
Setting energy patterns (morning person, etc.)
Configuring buffer time between meetings
Defining focus blocks for deep work

Updated preferences take effect immediately for all future scheduling.

Tool Schema

{
  "name": "update_preferences",
  "description": "Update a user's scheduling preferences including work hours, buffer time, energy patterns, and focus blocks. These preferences influence how meeting times are scored and selected.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "email": {
        "type": "string",
        "format": "email",
        "description": "Email address of the user"
      },
      "preferences": {
        "type": "object",
        "description": "Scheduling preferences to update",
        "properties": {
          "work_hours": {
            "type": "object",
            "description": "Work hours for each day of the week",
            "properties": {
              "monday": { "$ref": "#/definitions/DaySchedule" },
              "tuesday": { "$ref": "#/definitions/DaySchedule" },
              "wednesday": { "$ref": "#/definitions/DaySchedule" },
              "thursday": { "$ref": "#/definitions/DaySchedule" },
              "friday": { "$ref": "#/definitions/DaySchedule" },
              "saturday": { "$ref": "#/definitions/DaySchedule" },
              "sunday": { "$ref": "#/definitions/DaySchedule" }
            }
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone (e.g., 'America/New_York')",
            "examples": ["America/New_York", "Europe/London", "Asia/Tokyo"]
          },
          "buffer_minutes": {
            "type": "integer",
            "description": "Minutes of buffer time between meetings",
            "enum": [0, 15, 30],
            "default": 15
          },
          "availability_window_days": {
            "type": "integer",
            "description": "How many days ahead to search for availability",
            "minimum": 7,
            "maximum": 90,
            "default": 14
          },
          "max_meetings_per_day": {
            "type": "integer",
            "description": "Maximum meetings allowed per day",
            "minimum": 1,
            "maximum": 10,
            "default": 5
          },
          "energy_pattern": {
            "type": "string",
            "description": "When user is most productive",
            "enum": ["flexible", "morning_person", "afternoon_person", "evening_person"],
            "default": "flexible"
          },
          "scheduling_context": {
            "type": "string",
            "description": "Free-form text about scheduling preferences for AI to learn from",
            "maxLength": 1000
          },
          "focus_blocks": {
            "type": "array",
            "description": "Protected time blocks for deep work",
            "items": {
              "type": "object",
              "properties": {
                "day": {
                  "type": "string",
                  "enum": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"]
                },
                "start": {
                  "type": "string",
                  "description": "Start time in HH:MM format (e.g., '09:00')"
                },
                "end": {
                  "type": "string",
                  "description": "End time in HH:MM format (e.g., '12:00')"
                },
                "reason": {
                  "type": "string",
                  "description": "Why this time is protected (e.g., 'Deep work')"
                }
              },
              "required": ["day", "start", "end"]
            }
          }
        }
      }
    },
    "required": ["email", "preferences"]
  },
  "definitions": {
    "DaySchedule": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether this day is a work day"
        },
        "start": {
          "type": "string",
          "description": "Start time in HH:MM format (e.g., '09:00')"
        },
        "end": {
          "type": "string",
          "description": "End time in HH:MM format (e.g., '17:00')"
        }
      },
      "required": ["enabled", "start", "end"]
    }
  }
}

Usage in Claude Desktop

User: “I want to keep Fridays meeting-free for deep work” Claude will:

{
  "email": "alice@example.com",
  "preferences": {
    "work_hours": {
      "friday": {
        "enabled": false,
        "start": "09:00",
        "end": "17:00"
      }
    },
    "scheduling_context": "Keep Fridays meeting-free for deep work and focus time"
  }
}

Response Format

Success Response

{
  "success": true,
  "email": "alice@example.com",
  "preferences": {
    "work_hours": {
      "monday": { "enabled": true, "start": "09:00", "end": "17:00" },
      "tuesday": { "enabled": true, "start": "09:00", "end": "17:00" },
      "wednesday": { "enabled": true, "start": "09:00", "end": "17:00" },
      "thursday": { "enabled": true, "start": "09:00", "end": "17:00" },
      "friday": { "enabled": false, "start": "09:00", "end": "17:00" },
      "saturday": { "enabled": false, "start": "09:00", "end": "17:00" },
      "sunday": { "enabled": false, "start": "09:00", "end": "17:00" }
    },
    "timezone": "America/Los_Angeles",
    "buffer_minutes": 15,
    "availability_window_days": 14,
    "max_meetings_per_day": 5,
    "energy_pattern": "morning_person",
    "scheduling_context": "Keep Fridays meeting-free for deep work and focus time",
    "focus_blocks": []
  }
}

Example Workflows

Workflow 1: Setting Work Hours

// User: "I work 10am to 6pm on weekdays"

await mcpClient.callTool('update_preferences', {
  email: 'alice@example.com',
  preferences: {
    work_hours: {
      monday: { enabled: true, start: '10:00', end: '18:00' },
      tuesday: { enabled: true, start: '10:00', end: '18:00' },
      wednesday: { enabled: true, start: '10:00', end: '18:00' },
      thursday: { enabled: true, start: '10:00', end: '18:00' },
      friday: { enabled: true, start: '10:00', end: '18:00' },
      saturday: { enabled: false, start: '09:00', end: '17:00' },
      sunday: { enabled: false, start: '09:00', end: '17:00' }
    }
  }
});

// Future meetings will only be scheduled 10am-6pm on weekdays

Workflow 2: Energy Pattern Optimization

// User: "I'm most productive in the mornings"

await mcpClient.callTool('update_preferences', {
  email: 'alice@example.com',
  preferences: {
    energy_pattern: 'morning_person',
    scheduling_context: 'Most productive before noon. Prefer important meetings in the morning, lighter syncs in the afternoon.'
  }
});

// Future scheduling will prioritize morning slots

Workflow 3: Focus Blocks

// User: "I need Tuesday and Thursday mornings for deep work"

await mcpClient.callTool('update_preferences', {
  email: 'alice@example.com',
  preferences: {
    focus_blocks: [
      {
        day: 'tuesday',
        start: '09:00',
        end: '12:00',
        reason: 'Deep work - coding'
      },
      {
        day: 'thursday',
        start: '09:00',
        end: '12:00',
        reason: 'Deep work - writing'
      }
    ]
  }
});

// AI will avoid scheduling meetings during these times

Workflow 4: Buffer Time Management

// User: "I need 30 minutes between meetings to decompress"

await mcpClient.callTool('update_preferences', {
  email: 'alice@example.com',
  preferences: {
    buffer_minutes: 30,
    scheduling_context: 'Need time between meetings to prepare, decompress, and transition. 30 minutes helps me stay focused and energized.'
  }
});

// Meetings will have 30-minute gaps

Workflow 5: Natural Language Processing

// User: "Avoid scheduling during lunch from 12-1pm. I prefer afternoon for technical discussions and mornings for creative work."

await mcpClient.callTool('update_preferences', {
  email: 'alice@example.com',
  preferences: {
    scheduling_context: 'Avoid 12-1pm for lunch. Prefer afternoon (2-5pm) for technical discussions. Morning (9-11am) best for creative/strategic work.',
    focus_blocks: [
      {
        day: 'monday',
        start: '12:00',
        end: '13:00',
        reason: 'Lunch break'
      },
      {
        day: 'tuesday',
        start: '12:00',
        end: '13:00',
        reason: 'Lunch break'
      },
      {
        day: 'wednesday',
        start: '12:00',
        end: '13:00',
        reason: 'Lunch break'
      },
      {
        day: 'thursday',
        start: '12:00',
        end: '13:00',
        reason: 'Lunch break'
      },
      {
        day: 'friday',
        start: '12:00',
        end: '13:00',
        reason: 'Lunch break'
      }
    ]
  }
});

// AI processes the scheduling_context and generates SmartWeights

Preference Fields Explained

work_hours

Defines when you’re available each day:

enabled: Whether you work this day
start: Work start time (24-hour format)
end: Work end time (24-hour format)

Meetings will only be scheduled during these hours.

buffer_minutes

Gap between consecutive meetings:

0: Back-to-back meetings allowed
15: 15-minute buffer (recommended)
30: 30-minute buffer (for busy executives)

availability_window_days

How far ahead the AI searches:

7: Next week only (urgent scheduling)
14: Two weeks (default, recommended)
30: Next month (flexible scheduling)
90: Three months (long-term planning)

max_meetings_per_day

Daily meeting limit to prevent burnout:

1-3: Light meeting load
4-6: Moderate meeting load (default: 5)
7-10: Heavy meeting load

AI will avoid scheduling beyond this limit.

energy_pattern

When you’re most productive:

flexible: No preference (default)
morning_person: Best before noon
afternoon_person: Peak 12-5pm
evening_person: Best after 5pm

Affects time slot scoring significantly (±20% score adjustment).

scheduling_context

Free-form text that the AI processes to understand your preferences: Good examples:

“I prefer to keep Fridays light for planning and reflection”
“Morning meetings work best for strategic discussions. Save afternoons for execution.”
“Avoid back-to-back meetings - I need transition time”
“No meetings before 10am - I have family commitments”

The AI uses Claude LLM to extract insights and generate SmartWeights.

focus_blocks

Protected time for deep work:

{
  "day": "tuesday",
  "start": "09:00",
  "end": "12:00",
  "reason": "Engineering focus time"
}

AI will strongly avoid scheduling during these blocks.

How Preferences Affect Scoring

Preferences directly influence the 0.0-1.0 quality score for each time slot:

Work Hours (Required)

Inside work hours: No penalty
Outside work hours: Slot excluded entirely

Buffer Minutes

Buffer met: +10% to score
No buffer (back-to-back): -15% to score

Daily Meeting Limit

Under limit: No penalty
At limit: -20% to score
Over limit: Slot excluded

Energy Pattern

Morning person + morning slot: +20% to score
Morning person + evening slot: -20% to score
(Similar for other patterns)

Focus Blocks

Overlaps focus block: -50% to score (strong avoidance)

Scheduling Context

Processed by AI into SmartWeights
Can adjust any factor: time of day, day of week, meeting density, etc.
Example: “Avoid Fridays” → Friday slots get -30% penalty

Real-World Examples

Startup Founder

await mcpClient.callTool('update_preferences', {
  email: 'founder@startup.com',
  preferences: {
    work_hours: {
      // Available 7 days/week but with limits
      monday: { enabled: true, start: '08:00', end: '20:00' },
      tuesday: { enabled: true, start: '08:00', end: '20:00' },
      wednesday: { enabled: true, start: '08:00', end: '20:00' },
      thursday: { enabled: true, start: '08:00', end: '20:00' },
      friday: { enabled: true, start: '08:00', end: '18:00' }, // Earlier end
      saturday: { enabled: false, start: '09:00', end: '17:00' },
      sunday: { enabled: false, start: '09:00', end: '17:00' }
    },
    max_meetings_per_day: 8, // High tolerance
    buffer_minutes: 15,
    energy_pattern: 'morning_person',
    scheduling_context: 'Prioritize investor calls and customer meetings. Internal syncs can be flexible. Protect Friday afternoons for planning.'
  }
});

Software Engineer

await mcpClient.callTool('update_preferences', {
  email: 'engineer@tech.com',
  preferences: {
    work_hours: {
      monday: { enabled: true, start: '10:00', end: '18:00' },
      tuesday: { enabled: true, start: '10:00', end: '18:00' },
      wednesday: { enabled: true, start: '10:00', end: '18:00' },
      thursday: { enabled: true, start: '10:00', end: '18:00' },
      friday: { enabled: false, start: '10:00', end: '18:00' }, // No-meeting Fridays
      saturday: { enabled: false, start: '09:00', end: '17:00' },
      sunday: { enabled: false, start: '09:00', end: '17:00' }
    },
    max_meetings_per_day: 3, // Low tolerance for meetings
    buffer_minutes: 30, // Need transition time
    focus_blocks: [
      { day: 'tuesday', start: '10:00', end: '13:00', reason: 'Deep work - coding' },
      { day: 'thursday', start: '10:00', end: '13:00', reason: 'Deep work - code review' }
    ],
    scheduling_context: 'Minimize meetings to maximize coding time. Batch meetings on Monday and Wednesday afternoons. Never schedule before 10am.'
  }
});

Executive Assistant

// Updating preferences for the executive you support
await mcpClient.callTool('update_preferences', {
  email: 'ceo@company.com',
  preferences: {
    work_hours: {
      monday: { enabled: true, start: '07:00', end: '19:00' },
      tuesday: { enabled: true, start: '07:00', end: '19:00' },
      wednesday: { enabled: true, start: '07:00', end: '19:00' },
      thursday: { enabled: true, start: '07:00', end: '19:00' },
      friday: { enabled: true, start: '07:00', end: '17:00' },
      saturday: { enabled: false, start: '09:00', end: '17:00' },
      sunday: { enabled: false, start: '09:00', end: '17:00' }
    },
    max_meetings_per_day: 10,
    buffer_minutes: 15,
    energy_pattern: 'morning_person',
    focus_blocks: [
      { day: 'monday', start: '07:00', end: '08:00', reason: 'Planning time' },
      { day: 'friday', start: '16:00', end: '17:00', reason: 'Weekly review' }
    ],
    scheduling_context: 'Prioritize board meetings and investor calls in morning. Customer meetings anytime. Internal syncs afternoon only. Keep 7-8am Monday for planning.'
  }
});

Error Handling

Invalid Time Format

{
  "error": "invalid time format for work_hours.monday.start: expected HH:MM",
  "code": "INVALID_TIME_FORMAT"
}

Solution: Use 24-hour format like “09:00” or “17:00”

Invalid Timezone

{
  "error": "invalid timezone: America/Los_Angele",
  "code": "INVALID_TIMEZONE"
}

Solution: Use IANA timezone database names like “America/Los_Angeles”

Conflicting Preferences

{
  "error": "focus_block conflicts with work_hours: cannot have focus time outside work hours",
  "code": "INVALID_PREFERENCES"
}

Solution: Ensure focus blocks are within work hours

Best Practices

1. Update Incrementally

// Don't need to send all preferences every time
// Just update what changed

await mcpClient.callTool('update_preferences', {
  email: 'alice@example.com',
  preferences: {
    buffer_minutes: 30 // Only updating buffer, rest stays the same
  }
});

2. Use Descriptive Scheduling Context

// Good: Specific and actionable
scheduling_context: 'Prefer afternoons (2-5pm) for technical deep dives. Morning (9-11am) best for strategic planning and creative work. Avoid scheduling back-to-back - need 15min between meetings to reset. Keep Friday afternoons light for reflection and planning next week.'

// Bad: Too vague
scheduling_context: 'Flexible'

3. Set Realistic Limits

// Good: Sustainable meeting load
max_meetings_per_day: 5

// Bad: Burnout territory
max_meetings_per_day: 12

4. Align Focus Blocks with Energy

// Good: Morning person with morning focus blocks
{
  energy_pattern: 'morning_person',
  focus_blocks: [
    { day: 'tuesday', start: '09:00', end: '11:00', reason: 'Peak creativity' }
  ]
}

// Misaligned: Morning person with evening focus blocks
{
  energy_pattern: 'morning_person',
  focus_blocks: [
    { day: 'tuesday', start: '16:00', end: '18:00', reason: 'Focus time' }
  ]
}

find_mutual_availability

See how preferences affect availability

check_availability

View current preferences

schedule_meeting

Schedule with updated preferences

Get Started

Core Concepts

Scheduling API

Calendar Management

Platform Management

User API

Webhooks

MCP Server

Examples

​Overview

​Tool Schema

​Usage in Claude Desktop

​Response Format

​Success Response

​Example Workflows

​Workflow 1: Setting Work Hours

​Workflow 2: Energy Pattern Optimization

​Workflow 3: Focus Blocks

​Workflow 4: Buffer Time Management

​Workflow 5: Natural Language Processing

​Preference Fields Explained

​work_hours

​buffer_minutes

​availability_window_days

​max_meetings_per_day

​energy_pattern

​scheduling_context

​focus_blocks

​How Preferences Affect Scoring

​Work Hours (Required)

​Buffer Minutes

​Daily Meeting Limit

​Energy Pattern

​Focus Blocks

​Scheduling Context

​Real-World Examples

​Startup Founder

​Software Engineer

​Executive Assistant

​Error Handling

​Invalid Time Format

​Invalid Timezone

​Conflicting Preferences

​Best Practices

​1. Update Incrementally

​2. Use Descriptive Scheduling Context

​3. Set Realistic Limits

​4. Align Focus Blocks with Energy

​Related Tools