calendar-mcp

by deciduus

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Audit where time went

time_audit

Read-onlyIdempotent

Report where your time went by analyzing calendar events for meeting hours, attendees, and remaining focus time.

Instructions

Report where the user's time went: meeting hours, who with, and what focus time is left.

Answers "how much of my week is meetings?", "who am I spending my time with?" and "where did my focus time go?" in one pass. Working hours, lunch, buffer and the minimum focus block come from the saved preferences (see get_preferences), so the percentages reflect this user's actual day.

Declined meetings, events marked 'free', and all-day entries are excluded by default; the 'excluded' field says how many were skipped.

Args: time_min: Start of the window to audit, ISO 8601. time_max: End of the window to audit, ISO 8601. calendar_ids: Calendars to include. Defaults to ['primary']. group_by: Break the window down by 'day' or by ISO 'week'. include_all_day: Count all-day events as meeting time. include_declined: Count meetings the user declined. account: Account name from 'calendar-mcp accounts'; omit for the default.

Input Schema

TableJSON Schema

Name	Required	Default
`account`	No
`group_by`	No	week
`time_max`	Yes
`time_min`	Yes
`calendar_ids`	No
`include_all_day`	No
`include_declined`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`by_size`	No	Meeting time by headcount: 'solo', '1:1', 'small' (<=4), 'large'.
`periods`	No	Per-day or per-week breakdown, earliest first.
`excluded`	No	What was skipped and why.
`group_by`	No	Period grouping used: 'day' or 'week'.	week
`insights`	No	Three to five plain-English takeaways.
`time_max`	Yes	Exclusive end of the audited window, ISO 8601.
`time_min`	Yes	Inclusive start of the audited window, ISO 8601.
`timezone`	Yes	Timezone the days, weeks and working hours are expressed in.
`by_domain`	No	Meeting time by attendee email domain. A meeting with two domains counts in both.
`top_people`	No	People the user shared the most meeting hours with, most first.
`calendar_ids`	No	Calendars the events came from.
`by_recurrence`	No	Meeting time split into 'recurring' and 'one-off'.
`busiest_period`	No	The heaviest entry of 'periods'. None when nothing was booked.
`focus_block_count`	No	Number of such blocks.
`back_to_back_count`	No	Runs of three or more meetings with no usable gap.
`back_to_back_hours`	No	Total wall-clock hours those runs cover.
`longest_meeting_day`	No	The single heaviest day, regardless of group_by. None when nothing was booked.
`total_meeting_count`	No	Meetings counted.
`total_meeting_hours`	No	Total meeting hours in the window; overlaps counted twice.
`largest_focus_blocks`	No	The five longest free blocks, longest first.
`focus_hours_available`	No	Unbooked working hours in blocks at least min_focus_block_minutes long.
`back_to_back_stretches`	No	The individual back-to-back runs, earliest first.
`share_of_working_hours`	No	Fraction of the working hours spent in meetings, 0..1.
`working_hours_available`	No	Working hours in the window, lunch removed.
`meeting_hours_in_working_hours`	No	Meeting hours inside the working hours, overlaps merged.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.1.0Sep 7, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already mark this as read-only, idempotent, and open-world, and the description adds useful behavior beyond that: declined meetings, 'free' events, and all-day entries are excluded by default, with an 'excluded' field reporting skipped counts. It also discloses that results depend on saved working hours, lunch, buffer, and focus-block preferences, which is meaningful context an agent could not infer from the schema or annotations.

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?

The purpose is front-loaded in the first sentence, followed by concrete example questions, preference context, exclusion behavior, and a complete Args list with no filler. Each sentence contributes necessary information for selecting and invoking the tool correctly.

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?

The description is complete for a read-only audit tool with an output schema: it covers the full parameter surface, defaults, exclusions, preference dependencies, and the questions the tool answers. Return-value details are already handled by the output schema, so nothing essential is missing.

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 it succeeds: every parameter has a plain-language explanation, including ISO 8601 format, the ['primary'] default for calendar_ids, group_by semantics ('day' or ISO 'week'), and the meaning of the two include flags plus account. This is exactly what an agent needs to construct a correct call.

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?

The description opens with a specific verb and resource ('Report where the user's time went') and spells out the exact questions the tool answers, so an agent immediately knows what it does. It also sets this apart from sibling reporting tools by emphasizing the 'one pass' aggregation of meetings, attendees, and focus time.

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

Usage Guidelines4/5

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

The description clearly identifies the use case ('how much of my week is meetings?', 'who am I spending time with?', 'where did my focus time go?') and explains how preferences affect results, referencing get_preferences. However, it does not explicitly mention alternative tools like analyze_busyness, query_free_busy, or find_focus_time or state when not to use this tool, so it falls just short of full guidance.

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