calendar-mcp

Overview Schema Source Related Servers Discussions Admin

Find focus time

find_focus_time

Read-onlyIdempotent

Find uninterrupted focus blocks in your working hours by removing meetings, lunch, and buffers. Reports longest available deep work periods first.

Instructions

Find the uninterrupted blocks in a window that could be used for deep work.

Searches inside the user's working hours (get_preferences), removes lunch, everything already booked on their calendars, and the buffer they like around meetings, then reports what is left -- longest block first, because that is the one worth protecting. Blocks shorter than min_focus_block_minutes are not reported at all.

Availability must be readable for every requested calendar; otherwise this returns an error rather than unverified free time. Read-only: use block_focus_time to actually defend the time.

Args: time_min: Start of the window to search, ISO 8601. Without a UTC offset it is read in the calendar's own timezone. time_max: End of the window to search, ISO 8601. hours_needed: How many focus hours the user is trying to find. Used to report whether the window can supply them; pass 0 to just look. calendar_ids: Calendars whose events count as busy. Omit for every calendar the account has selected. account: Account name from 'calendar-mcp accounts'; omit for the default.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`account`	No
`time_max`	Yes
`time_min`	Yes
`calendar_ids`	No
`hours_needed`	Yes

Output Schema

TableJSON Schema

Name	Required	Description
`count`	No	Number of blocks returned.
`blocks`	No	Usable blocks, longest first, then earliest.
`message`	No	One-line human-readable summary.
`time_max`	Yes	End of the searched window, ISO 8601.
`time_min`	Yes	Start of the searched window, ISO 8601.
`timezone`	Yes	Timezone the blocks are expressed in.
`satisfiable`	No	True when total_free_hours covers hours_needed.
`calendar_ids`	No	Calendars whose busy time was subtracted.
`hours_needed`	No	Focus hours the caller asked for.
`buffer_minutes`	No	Gap left around each meeting, from preferences.buffer_minutes.
`total_free_hours`	No	Total focus hours available in the window.
`min_block_minutes`	No	Shortest stretch counted, from preferences.min_focus_block_minutes.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.1.0Sep 7, 2026

TDQS

A4.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, so the bar is lower, but the description adds real behavioral detail: the subtraction algorithm (lunch, booked events, meeting buffers), the min_focus_block_minutes cutoff, longest-first ordering, and failure semantics ('returns an error rather than unverified free time'). 'Read-only' partly restates the annotation, keeping this just shy of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose sentence, then algorithm, error behavior, sibling routing, and a clean Args block. Each sentence carries information; the only slight indulgences ('because that is the one worth protecting') serve to explain why the ordering matters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the description covers everything else an agent needs: purpose, preprocessing behavior, filtering threshold, error case, and call-time parameter semantics for a 5-param, 0%-documented schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden and does so for all five params: timezone interpretation for time_min ('Without a UTC offset it is read in the calendar's own timezone'), the purpose of hours_needed plus the 'pass 0 to just look' escape hatch, and the default meaning of omitting calendar_ids and account.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Find the uninterrupted blocks in a window that could be used for deep work') and goes further to name the sibling it is not: 'Read-only: use block_focus_time to actually defend the time.' An agent can distinguish this from block_focus_time and query_free_busy without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: this tool is the read-only finder, `block_focus_time` is for defending the time, and `get_preferences` supplies the working hours used internally. It also states a precondition ('Availability must be readable for every requested calendar; otherwise this returns an error'). Nothing about when to pick it is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.