Appointment changes

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

The description usefully discloses non-obvious behavior: a baseline is stored on first call and subsequent calls diff against a local snapshot of ids, times and status. But that is directly at odds with the idempotentHint=true annotation — repeated calls with identical arguments return different results (first call = full baseline, later calls = deltas only), so the declared idempotency is misleading. The readOnlyHint also understates the persistent local snapshot write.

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

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

Three short sentences, front-loaded with the return content and followed by the stateful mechanics. 'Small local snapshot of ids, times and status' is a borderline implementation detail but it earns its place by explaining why repeats differ.

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

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

With no output schema, the description must explain return shape, and it only names categories of change — it does not say how a change is represented, whether the first call returns all current appointments as 'new', or what an empty result means. For a stateful delta feed with no output schema, that gap matters.

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

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

Schema description coverage is 100% and both parameters carry their own bounds and defaults, so the schema carries the semantics. The description adds no guidance on how days_back/days_ahead interact with the snapshot window (e.g. whether widening the window produces a larger diff), so it neither helps nor hurts.

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

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

Specific verb-and-resource framing: it enumerates what counts as a change (new, moved, cancelled, otherwise changed) so the agent knows this is a calendar delta feed rather than a listing. It does not distinguish itself from the closely named sibling calendar_changed_dates, leaving that boundary to inference.

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

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

Implied usage is conveyed by 'since the last call' and 'the first call stores a baseline', which tells the agent this is a polling/delta tool. However there is no explicit guidance on when to prefer this over calendar_agenda or calendar_changed_dates, nor any warning about the statefulness affecting repeat invocation strategy.

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