How skdul scores 100+ time slots in under a second

When an AI agent asks "what's the best time for a 30-minute call next week?", the naive answer is a flat list of available slots. Tuesday 9:00 AM, Tuesday 9:30 AM, Tuesday 10:00 AM... here are 47 options, good luck.

That's not helpful. Agents don't browse — they need a recommendation. So we built a scoring algorithm that evaluates every available slot against five factors and returns a ranked list with composite scores.

The five factors

1. Time-of-day preference (0–25 points)

Users can indicate whether they prefer mornings, afternoons, or have no preference. The scoring function maps each slot's start time onto a preference curve.

For a morning preference, 9:00 AM scores 25/25. Noon scores 12/25. 4:00 PM scores 3/25. The curve is smooth — not a hard cutoff — so a 10:30 AM slot still scores well.

If no preference is set, all times-of-day score equally: 15/25.

2. Gap efficiency (0–25 points)

This is the most important factor for calendar health. A "gap" is the time between two adjacent calendar events. Small gaps (5–15 minutes) are useless — too short to start anything meaningful, too long to ignore.

The algorithm penalizes slots that would create gaps under 20 minutes. It rewards slots that either stack adjacent to existing meetings (zero gap = maximum efficiency) or leave at least 45 minutes of breathing room.

The math: for each neighboring event, calculate the gap. If gap < 20 min, subtract up to 15 points. If gap > 45 min or gap = 0, add up to 10 points. Normalize to 0–25.

3. Day spread (0–20 points)

Humans don't like having seven meetings on Monday and zero on Wednesday. The day-spread factor counts existing bookings per day and penalizes days that are already heavy.

A day with zero existing meetings scores 20/20. A day with three scores 12/20. A day with six or more scores 2/20. This naturally distributes new bookings across the week.

4. Buffer comfort (0–15 points)

Even if a gap is technically large enough, people feel cramped when meetings are clustered. Buffer comfort measures the total free time surrounding the proposed slot in a 2-hour window.

If you have 90+ minutes of free time in the surrounding window, full points. If you have less than 30 minutes, almost zero. This factor catches scenarios where the slot is technically available but the day already feels packed.

5. Booking density (0–15 points)

A global check on the total number of bookings that day. Unlike day spread, which compares against other days, booking density has absolute thresholds.

0–2 bookings: 15/15. 3–4 bookings: 10/15. 5–6 bookings: 5/15. 7+: 1/15.

Composite scoring

The five factors sum to a maximum of 100 points. In practice, the best slots score between 55 and 80. A "perfect" score would require a morning slot on an empty day with ideal gap spacing — which is possible early in the week but rare by Thursday.

The algorithm returns the top N slots (default 5) sorted by score, with ties broken by chronological order (earlier slots win).

Performance

For a typical one-week window with 40+ available slots, the entire scoring pipeline runs in under 100ms. The bottleneck isn't the math — it's fetching the user's existing calendar events from the database. We cache busy times aggressively and compute availability as a set-difference operation against the cached data.

The scoring itself is O(n × m) where n = available slots and m = existing events. With typical values of n=50 and m=20, we're talking about 1,000 lightweight comparisons. Not exactly computationally expensive.

Why this matters for agents

A flat list of 47 slots forces the agent to either pick randomly or ask the user for guidance. A scored list lets the agent book confidently: "I found the best slot — Tuesday at 10:00 AM, score 67.3. Shall I book it?"

The user glances at the recommendation, says "yes," and the meeting exists. That's the experience we're optimizing for: humans approve, agents execute. This scoring engine is exposed through our MCP server so any AI agent can use it to book the best time automatically.