pim-mcp

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

With no annotations, the description carries the full burden and does disclose important behavioral rules: a bare date on `start` creates an all-day event, and omitted `end` yields a 1-hour timed event or 1-day all-day event. It omits other side effects such as whether invitations are sent or whether recurrence changes propagate, so it falls short of full disclosure.

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?

Two short sentences, front-loaded with the action, then the two highest-value edge-case rules. No filler.

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?

For a 10-parameter mutation tool with no annotations and no output schema, the description covers the two behaviors most likely to cause a wrong call (all-day inference and implicit duration). The remaining parameters are well documented in the schema, so the gap is small but present — side effects like invitation emails and recurrence interaction are not addressed.

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 coverage is 70%, and the description adds meaning the schema does not: the type of `start` changes the event kind, and the default duration depends on that kind. It says nothing about `busy`, `rrule`, `attendees`, or `alarm_minutes` beyond what the schema already documents.

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?

The opening 'Create an event' states a specific verb and resource, and the following sentences clarify the scope of the operation via date-type semantics. It is clearly distinguishable from siblings like update_event and delete_event by verb alone, though it never names them.

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?

There is no explicit when-to-use / when-not-to-use statement and no reference to alternatives such as update_event for modifying an existing event. Usage is implied by the verb 'create' and the defaults it describes.

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

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

With destructiveHint=true already declaring the mutation, the description adds the most important missing detail: the blast radius, i.e. that "series" removes every occurrence while "instance" removes only one. What it does not disclose is irreversibility/undo, or what happens when `scope` is omitted on a recurring event — a real ambiguity since scope is not in the required list.

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?

Two short sentences with zero filler; the destructive action is stated first and the conditional scope rule follows immediately. Every clause carries information the agent needs.

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?

For a destructive two-parameter tool with no output schema, the definition covers the recurring-event case but leaves gaps: what `id` refers to, whether deletion is permanent, and the default behavior when `scope` is omitted for a recurring event (the schema does not mark it required, creating a contradiction with "for recurring events pass scope").

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 coverage is 50%: `scope` is fully documented in the schema and the description largely restates it (instance = one occurrence, series = all), which is mildly helpful but not additive. The `id` parameter has no schema description and is never mentioned in the description, so the agent must infer what identifier is expected (event ID vs. calendar+event pair).

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?

The description opens with a specific verb and resource ("Delete an event"), which cleanly separates it from the create_event/update_event siblings. It stops short of explicitly contrasting itself with those siblings, but the destructive verb makes the intent unambiguous.

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?

It gives one conditional usage rule — pass `scope` for recurring events — but that is parameter guidance rather than when-to-use-this-tool guidance. There is no statement about when deletion is appropriate versus updating, nor any preconditions such as required permissions or ownership.

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

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

readOnlyHint already tells the agent this is a safe read, and the description adds real behavioral content beyond that: free/transparent events and cancelled events do not block time. Still silent on whether free windows are split per day, whether working_hours defaults apply, and timezone resolution beyond what the schema says.

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?

Two sentences, zero filler, with the core capability front-loaded and the blocking rule immediately after. Nothing could be cut without losing information.

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?

For a read-only availability query with well-documented date inputs, the definition covers purpose, the key constraint, and the blocking semantics. No output schema exists, but the natural return (windows of >= duration_minutes) is self-evident from the description. Minor gaps around per-day splitting don't make it incomplete for a 6-param query tool.

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?

At 50% schema coverage, the description must compensate. It explains duration_minutes (minimum window length) and hints at calendars ('all (or selected)'), but the 'accounts' parameter and 'working_hours' object are untouched by the description, leaving two parameters documented only thinly or not at all.

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?

States a specific verb+resource ('Free time windows ... across all (or selected) calendars') with a quantified constraint. Among siblings, which are all event CRUD/listing tools, this is unmistakably the availability-computation tool, so no confusion is possible 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.

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

The parenthetical '(or selected) calendars' and the mention of duration_minutes imply the intended scenario (find a slot of a given length), but there is no explicit when-to-use, no prerequisite statement (e.g. calendars must be connected), and no comparison to list_events/search_events.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is reduced. It usefully discloses the shape of the payload (description, attendees, organizer, recurrence rule) in the absence of an output schema, but says nothing about behavior when the id is unknown or about permissions/visibility limits.

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?

A single front-loaded sentence that leads with the retrieval scope and then enumerates the payload; every clause earns its place and nothing is padded.

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?

For a one-parameter read tool with annotation coverage and no output schema, the description adequately conveys both purpose and return fields. The only real omission is the meaning/format of 'id' and any error or visibility caveat.

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 0% and the sole 'id' parameter is undocumented in both schema and description; it is not stated whether this is an event id, a recurring-instance id, or a calendar-scoped id. Since only one self-evidently named parameter exists, this is a modest gap rather than a severe one.

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?

The description gives a specific verb and resource ('Full details of one event') and enumerates what detail is returned (description, attendees, organizer, recurrence rule), which distinguishes it from list_events and search_events. It stops short of naming those siblings explicitly, so 4 rather than 5.

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?

There is no statement of when to use this tool over search_events or list_events, and no prerequisites (e.g., that the id must come from a prior list/search call). An agent must infer the usage pattern from the single required 'id' parameter.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value by disclosing the multi-account aggregation scope (Nextcloud, iCloud, Google, …) — something the annotations do not say. It does not address what happens if a backend account is unreachable or credentials are missing, which matters for an aggregating tool.

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?

One sentence, front-loaded with the verb and resource, with the cross-account scope and the downstream-use hint packed in without waste.

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?

There is no output schema, and the description compensates by stating the key return property — calendar ids usable in other tools. It stops short of saying what other fields (name, color, provider) come back, which would fully close the gap.

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?

The tool takes zero parameters, so the baseline is 4. The description correctly signals that no arguments are needed to scope the listing.

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?

States a specific verb (List) and resource (every calendar) and adds the scope 'across all configured accounts', with provider examples. The resource noun 'calendar' vs. the sibling tools' 'events' makes the distinction immediately obvious.

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?

The phrase 'with ids usable in other tools' implies the intended workflow: call this first to obtain calendar ids for the event tools. It gives clear context but names no explicit alternatives or when-not conditions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds genuinely non-obvious behavior: results are merged across all calendars, sorted by start, and recurring events are expanded into occurrences. It stops short of describing pagination, result limits, or return shape.

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 core scope and behavior, and each sentence contributes distinct information (scope, recurrence expansion, defaults). No filler.

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?

A read-only list tool with full schema coverage and a clear behavioral summary; there is no output schema, and the description doesn't explain result shape or limits, but nothing critical to forming a correct call is missing.

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%, so all four parameters (start, end, accounts, calendars) are already documented with formats and defaults. The description only reinforces the default time window and adds nothing about the accounts/calendars filters, so the baseline 3 applies.

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?

States a specific resource (events) and scope (time range, merged across all calendars, sorted by start) plus the recurrence-expansion behavior, so an agent knows exactly what it gets back. It does not explicitly contrast itself with the sibling search_events, so it falls short of a 5.

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?

The stated default window (today through the next 7 days) implies when this is the convenient call, but there is no explicit when-to-use/when-not guidance and no pointer to search_events or find_free_time as alternatives. Usage must be inferred from the sibling names.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavior beyond annotations: case-insensitive matching across specific fields and a default date window. It omits result limits/pagination and how the calendars filter interacts with the search.

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?

Two tight sentences with no filler; the search scope is front-loaded and the default range follows immediately.

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?

For a read-only search tool with no output schema, the description gives the essentials: matching semantics and default time bounds. It could be more complete by explaining the calendars filter and any result-size limits, but nothing critical to invocation is missing.

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 coverage is 50%: start/end are documented, while query and calendars are not. The description compensates well for the central query parameter by explaining which fields are searched and case-insensitivity, and it clarifies the default time range tied to start/end. The calendars array remains unexplained.

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?

States a specific verb and resource ('Find events') and specifies the matching fields (title, location, description) and case-insensitivity. This clearly distinguishes text search from list_events and get_event.

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?

Provides clear context for use via the query-based search and the default time window (90 days back to 365 days ahead). It does not explicitly name alternatives such as list_events or state when not to use it, but the purpose implies the right usage.

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

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

With no annotations, the description carries the full burden and does deliver genuinely non-obvious behavior: partial updates, and that moving `start` alone preserves duration rather than shifting the whole event. It omits permissions/error behavior and, more importantly, does not warn that `scope: series` mutates every occurrence of a recurring event — a destructive consequence the agent should know about.

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 core action, then the two constraints that matter most. No filler and nothing repeated from the schema.

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?

For an 11-parameter mutation tool with no annotations and no output schema, the description covers the two areas most likely to cause wrong calls: duration drift and recurrence scoping. Gaps remain around `id` validity, failure modes, and the blast radius of series updates, preventing a 5.

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 coverage is 64%, and the description reinforces the two trickiest parameters: `start` (duration preserved when moved alone) and `scope` (required for recurring events). However, the only required parameter `id` is undocumented in both schema and description, and it doesn't clarify edge cases like whether changing `rrule` on a recurring event requires a particular scope.

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?

"Change an event" is a specific verb plus resource, and the partial-update framing distinguishes it in practice from create_event and delete_event. It never names a sibling explicitly, so differentiation is implied rather than stated.

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?

Clear operating context: patch semantics ("only the fields you pass change") tells the agent to use this rather than delete-and-recreate, and "For recurring events pass `scope`" is a concrete conditional instruction. It stops short of stating exclusions or naming alternatives such as create_event/delete_event for the cases this tool shouldn't handle.

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