Multi Calendar

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

The annotations say this is a non-read-only, open-world, non-destructive creation tool, and the description adds substantial context beyond that: the link expires after 14 days, the guest has no account, times are rechecked against calendars and working hours, fallback hours are Monday-Friday 09:00-17:00, and event busy/free semantics differ by provider. These details materially help an agent understand the tool's side effects and edge cases.

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?

The purpose is front-loaded, but the description is a dense, run-on block with long sentences covering calendar-provider semantics and guest-page behavior. Much of this is useful but not concise, and it would be difficult to scan quickly.

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 creation tool with no output schema, the description covers the important return information (the link id and its 14-day closing time), the guest experience, revalidation behavior, and calendar hold semantics. It is substantially complete, though error cases and permission requirements 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 description coverage is 100%, so the schema already documents all four parameters well. The description reinforces that times come from free_times_find and that subject is the only meeting name a guest sees, but it adds little beyond the schema's own parameter descriptions.

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 states a specific verb and resource: making a booking link that offers times found by free_times_find for a named meeting, sent to one guest. It clearly identifies the sibling free_times_find as the source of times, though it does not explicitly contrast with other creation siblings such as polls_create or booking_page_set.

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 provides clear context for use: after free_times_find has produced times, for a single guest, with the guest picking in their own time zone. It does not explicitly state when not to use it or name alternative tools, but the intended workflow is clear.

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?

Beyond the annotations, the description adds valuable behavioral context: renaming moves the page and leaves the old address answering nothing, a new page needs subject, and updates affect only the fields given. It also explains guest-facing booking behavior and calendar free/busy interpretation, though it does not clarify permissions or precisely what destructiveHint means here.

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?

The description is a dense, run-on construction that mixes the tool's invocation semantics with extensive background about guest booking, working hours, time zones, and provider free/busy rules. The purpose is front-loaded, but the text is far longer and harder to parse than necessary for calling this four-parameter tool.

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 complex mutation tool with no output schema, the description covers the important create/update distinction, rename side effect, subject requirement, and guest-visible behavior. It omits permission/auth details and some sibling-routing guidance, but it provides enough context to invoke the tool correctly.

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 already 100%, so the baseline is 3, but the description adds meaning for name, newName, and subject beyond the schema, especially that newName moves the address and that subject is the only identifying text a guest reads. It does not add similar meaning for minutes, which the schema explains adequately.

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 states a specific action and resource: setting one of the person's permanent booking pages, including creating or modifying a page by name. It also makes the update-versus-create distinction clear through the existing-name and new-name cases, though the phrasing is tangled enough that it does not cleanly separate itself from sibling tools such as booking_links_create.

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 behavioral conditions, such as a held name modifying an existing page and an unused name adding a page, but it does not say when an agent should use this tool instead of alternatives like booking_links_create or polls_create. There is no explicit usage guidance or exclusion criteria against siblings.

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?

Beyond the annotations, it discloses that blocks appear within seconds for the coming 60 days, are private, move with their events, disappear when events end or the pair is removed, and are recreated if manually deleted. It also explains provider-specific behavior, scope limits, and how events_list exposes blocks under busyCopies.

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?

The description is a dense, run-on construction with multiple em-dash-separated clauses that make it hard to scan. It is not front-loaded beyond the opening clause and repeats scope constraints in a way that slows comprehension.

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 complex, destructive, idempotent mutation with no output schema, the description covers the important effects, edge cases, and relevant sibling references. It does not describe the immediate return value of this tool, but it explains enough about resulting state and related listings to support correct invocation.

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 the schema already explains every parameter, including the provider fields and the boolean on/off switch. The description confirms the conceptual pairing of account, calendarId, and into, but adds little parameter-level syntax or format detail beyond the schema.

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 states a specific verb and resource: it shows one of an account's calendars as busy in another named connected account, or stops that pairing. The core action is distinguishable from sibling tools, though the purpose is buried inside a long, clause-heavy sentence.

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 explains the toggle behavior and the effect of naming a pair, and it points to calendars_list for account/calendar identifiers. However, it does not explicitly state when to use this tool versus alternatives or give clear prerequisites beyond the schema.

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?

Despite annotations already marking this as read-only and non-destructive, the description adds substantial behavioral context: it explains access modes, default/owned/shared status, hidden calendars, time zone limitations, and what happens with unread accounts and cutShort results. It also discloses the reconnection workflow, which is important operational behavior.

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?

The description is dense and run-on, packing many output-field caveats into two long sentences without paragraphing or list formatting. The details are useful given the lack of an output schema, but the structure is not concise or easy to scan.

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 and no parameters, the description carries the full burden of explaining return values and edge cases. It does so thoroughly, covering account/provider naming, ownership, access, time zones, busyShownIn, unread accounts, cutShort, and reconnectAt.

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 has zero parameters, so there is no parameter semantics to explain. The baseline score of 4 applies because the schema is empty and does not need description-level compensation.

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: 'List every calendar of every connected Outlook.com, Microsoft 365, Google, iCloud and calendar server account.' It clearly scopes the operation to calendars rather than events, making it distinguishable from siblings such as events_list and circles_list.

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?

Usage is implied by the listing operation and the detailed account/calendar context, but there is no explicit guidance on when to call this versus events_list, free_times_find, or other siblings. No exclusions or prerequisites are stated.

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 readOnlyHint=true and destructiveHint=false already covering safety, the description adds extensive behavioral context beyond annotations: provider-specific free/busy interpretation, all-day event handling, working-hours exclusion, 365-day search limit, unknown/readInPart/noCalendar/notJoined statuses, poll-based counting, reconnect requirements, and output member annotations.

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?

The description is a very long, dense, run-on block with minimal structure. While many details are useful, it is not appropriately sized or easy to parse, and much of the provider-specific detail could be organized more concisely.

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?

Even without an output schema, the description thoroughly covers return semantics: busy times, owner naming, member time zones, unusual markers, unknown/readInPart/noCalendar/notJoined/tickedNothing/unread statuses, and reconnectAt details. This is sufficient for an agent to understand the response structure.

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 the schema already documents all eight parameters. The description adds some context such as the 365-day window limit and provider free/busy rules, but it does not substantially deepen per-parameter meaning beyond what the schema provides.

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 states a specific verb and resource: find when everyone in one of the person's circles is free or available, with defined window, duration, and zone semantics. It does not explicitly distinguish this tool from the sibling free_times_find, so sibling differentiation is missing.

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 description explains behavior in depth but gives no explicit guidance on when to use this tool versus alternatives such as free_times_find. It references circles_list for ids and polls_create for poll-based members, but those are supporting actions rather than routing guidance.

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?

Goes well beyond the annotations: it discloses that real emails are sent under the person's address with replies routed to them, that only an account signed in at that address can join, that prompt-attack-screened circle names send nothing, and that a 20-letters-per-24h cap causes the whole call to invite nobody with a wait message. This is exactly the side-effect and failure context a destructive, open-world tool needs.

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?

Purpose is front-loaded and nearly every clause carries information, but the description is a dense wall of run-on clauses ('made where the person has none by it', 'replies going to them') that is harder to parse than it needs to be. Splitting the side effects, response shape, and rate limit into separate sentences would preserve content and improve scanning.

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 fully specifies the return shape (circle id, whether created, and the invited/kept/unsent buckets) plus the rate-limit failure mode. For a 3-parameter mutation tool with open-world side effects, nothing an agent needs before calling 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 100% so the baseline is 3, but the description adds semantics the schema does not: case-insensitive name matching, create-on-miss behavior, and the case-collision refusal. It also maps the addresses array to per-address outcomes (invited/kept/unsent) rather than leaving the array opaque.

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 — inviting addresses into one of the person's own circles — and explicitly defines the two circle-resolution modes (existing id 'as circles_list names it', or a name created on demand). An agent can distinguish this from circles_list and the other circle siblings without opening the 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?

Explains the selection logic between id and name (name is used where no id is passed, created if none exists, refused on case-only collisions naming both ids) and points to circles_list as the source of ids. It lacks explicit 'do not use this when…' exclusions or routing to alternatives for the other invite-like flows, so it stops short of a 5.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: it enumerates the returned fields and clarifies that invited-but-not-joined addresses appear as 'invited' only on the person's own circles.

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?

It is a single sentence front-loaded with the verb and resource, and every clause carries information. The clause about invited addresses is grammatically convoluted ('on the person's own, of each address invited...') and slightly slows parsing, but nothing is wasted.

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 carry the return-value burden, and it does by naming the fields returned. Nothing needs to be said about parameters or safety beyond the annotations, so the definition is essentially complete for a zero-param read 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?

The tool takes zero parameters and the schema is an empty object with additionalProperties=false, so there is nothing for the description to disambiguate. No parameter semantics are needed.

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 (circles) with an explicit scope: every circle the person owns or has joined. It also names the sibling circles_free_times_find and its different job, so an agent can separate the two without opening either 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 closing pointer to circles_free_times_find implies the boundary between browsing circles and finding a meeting time, but there is no explicit statement of when to call this tool versus circles_invite or the free-times tool. Usage is only implied, not stated.

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?

Beyond the annotations, the description explains that cancellations notify attendees from the account's own address, that Outlook sends the optional message, and that copyOnly sends nothing. These are meaningful behavioral disclosures for a destructive mutation tool. The provider-specific wording is convoluted and leaves some edge cases hard to parse, so it is not fully transparent.

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?

The description is a single sprawling run-on sentence with nested clauses and semicolons, making it difficult to scan. While many details are relevant, they are not front-loaded or organized into digestible statements. This is a structural weakness, not merely a length issue.

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 complex destructive tool with eight parameters and no output schema, the description covers the key semantic branches: normal cancellation, events_respond for someone else's event, and copyOnly for local removal. Annotations already cover safety and idempotency. The missing return-value detail is minor for a cancel operation, though the confusing wording slightly reduces completeness.

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 eight parameters are already documented in the input schema. The description reinforces notify, message, and copyOnly behavior, but adds little syntax or meaning beyond the schema's existing descriptions. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 states a specific verb and resource: 'Cancel or call off an event the account organises.' It also distinguishes the tool from events_respond by explaining that someone else's event is not cancelled here. However, the purpose is buried inside a long run-on sentence with provider-specific details, which reduces immediate clarity.

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 explicitly says when not to use this tool: 'Someone else's event is not cancelled here: declining it with events_respond takes it off an Outlook calendar and leaves it on a Google one.' It also names copyOnly as the alternative path for removing only the account's own copy of someone else's event, giving clear routing guidance.

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?

Goes far beyond the destructive/openWorld annotations: it discloses provider-specific invitation behavior (Microsoft/Google/Apple/CalDAV), idempotency semantics for retried creates (same-argument repeat finds the first event, for the rest of the UTC day, Microsoft-dependent), silent non-send on unusual-hours violations, and per-feature refusals with reasons. This is exactly the behavioral load the annotations alone cannot carry.

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?

Purpose is front-loaded and nearly every clause encodes a distinct rule, but the single dense paragraph of semicolon-chained clauses is hard to scan and parse. For an 18-parameter tool some length is warranted, yet it could be broken into labeled sections without losing content.

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?

No output schema exists, and the description compensates by describing what comes back (times under timeZone, guestTimes/guestZones, joinUrl). Combined with provider gaps, idempotency, and refusal paths, an agent has what it needs to call this correctly across providers.

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 72% schema coverage the description still meaningfully extends the schema: it explains the dual date vs date-time semantics of start/end and the 'end day after last' all-day rule, repeating-series behavior across clock changes, guestZones precedence, and how notify maps to 'who hears of it.' It adds real meaning rather than restating fields.

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?

Opens with a specific verb+resource ('Create an event') immediately narrowed to 'one of a connected account's own calendars,' and explicitly excludes shared-only calendars. The agent can tell this apart from events_edit/events_get 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?

Gives concrete applicability conditions: calendarId from calendars_list else default, shared calendars refused, guests must resolve to a provider that sends invitations, and unusual-hours sends require unusualHoursAgreed=true. It routes to calendars_list for IDs but never names sibling mutation alternatives like events_edit, so the when-not-what-else picture is incomplete.

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 annotations already covering safety (readOnly=false, destructive=true, openWorld=true), the description adds substantial non-obvious behavior: only named fields change, id and other guests' answers are preserved, start-alone/end-alone inheritance, timed↔all-day conversion, provider-specific refusals (Outlook online-meeting body, unsupported provider features), the 'inviting allowed' account requirement, series-divergence refusal semantics, and per-provider notification behavior. It even discloses the return payload shape despite no output schema.

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?

The purpose is correctly front-loaded, but the body is a dense multi-clause paragraph built from em-dashes and semicolons that is hard to parse on first read. Nearly every sentence carries real information, yet a bullets/short-sentence restructure would deliver the same content with far less parsing cost.

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 19-parameter destructive write with no output schema, the description covers everything an agent needs: mutation semantics, refusal cases and their reasons, permission prerequisites, notification side effects, timezone rules, series constraints, and the shape of the answer (provider, calendarId, webLink). Nothing material 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 68% with hand-written descriptions on the tricky fields (scope, notify, showAs, video, reminders, guestZones, calendarId). The description compensates further by explaining the interaction the schema cannot: start named alone keeps its length, end alone keeps its start, and naming both in the other form flips timed/all-day. Minor fields (subject, body, location, privacy) get no extra semantics, but they are self-evident.

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 ('Change, move or reschedule an event the account organises, in place and in one call') and enumerates exactly which fields are editable, including guest add/remove. This is clearly the in-place mutation tool, distinguishable from events_create (referenced for naming conventions) and from events_cancel/events_get by the listed field set.

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?

Gives a strong operating context: what counts as a change, how single-occurrence vs whole-series edits behave, and that a series with diverging occurrences is refused. It does not explicitly route the agent away from this tool to events_cancel for cancellation or events_create for new events, so the alternative-choice guidance is implied rather than stated.

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 a safe read-only operation, and the description adds substantial behavior beyond them: prompt-attack screening withholds events, long descriptions are truncated with omittedCharacters, attendee lists are truncated with omittedAttendees, busy copies are returned under busyCopy, and recurring occurrences carry seriesId and originalStart. This is unusually rich behavioral 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?

The description is a single enormous run-on sentence held together by dashes and semicolons, making it difficult to scan. The first clause is front-loaded, but the remainder is structurally poor despite containing useful 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?

There is no output schema, so the description must carry the return-value burden, and it does so comprehensively by enumerating event fields, truncation behavior, recurring-instance metadata, reminders, and busy-copy handling. It omits error behavior for missing events or permission failures, which keeps it from 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 100%, so all five parameters are already documented in the schema. The description reinforces that account, calendarId, and eventId follow events_list naming and that timeZone controls the zone of returned times, but it adds no syntax or constraint beyond what the schema provides.

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 clause gives a specific verb and resource: 'Read one event whole, by the account, calendarId and id.' It clearly reads a single event rather than a list, but the purpose is buried in a long run-on sentence and references to events_list are about naming conventions, not sibling routing.

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?

'Read one event' implies this is the single-event lookup counterpart to events_list, but the description never explicitly says when to use this instead of events_list or other siblings. No prerequisites, exclusions, or error conditions are stated.

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 only declare readOnly/non-destructive/openWorld=false; the description goes far beyond by disclosing the 50-event-per-calendar cap, cutShort/readTo/continueAt pagination, leftOut and omittedAttendees truncation, unread reasons (needs_reconnection, rate_limited, etc.), withheld prompt-attack filtering, malformed counts, and how Lumman's busy copies are separated into busyCopies. This is unusually rich behavioral disclosure for a read 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?

Purpose is front-loaded, and most sentences carry non-redundant information, but the entire body is one dense paragraph with no structure, mixing return-value details, pagination rules, busy-copy explanation, and error semantics. It is readable only with effort and could be segmented or trimmed.

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, so the description must carry the entire return contract — and it does: event fields, per-copy metadata, timeZone/offset handling, all-day date semantics, response statuses, privacy/kind fields, join links, and every truncation/error bucket. An agent has what it needs to call and interpret this 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?

Schema description coverage is 100%, so the baseline is 3; the description still adds meaningful semantics, notably that query matches every word across title/description/place/organizer/guests, that Outlook is searched by title alone while Google searches its own index, and the exact continuation protocol for continueAt with account+calendarId. These go beyond the schema's per-parameter blurbs.

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 states a specific verb and resource — reading meetings, appointments and other events of a period across every connected calendar — and distinguishes the result ordering (earliest first, or newestFirst). An agent can immediately tell this is a multi-calendar event listing, distinct from events_get, events_create or free_times_find.

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 description explains when to narrow with query, account, provider, calendarId, or continueAt, and points to events_get when the full description is needed. It stops short of an explicit when-not-to-use or a named alternative for other listing needs (e.g. calendars_list), but the routing context is strong.

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 only declare destructive/open-world/not-read-only, but the description adds substantial behavior: the answer is sent from the account's own address, message visibility on Google, notify semantics, replacement counts for series, server-side answering for password-connected calendars, and the refusal conditions. This is exactly the kind of context annotations cannot convey.

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?

The purpose is front-loaded, but the rest is a single densely nested sentence with convoluted phrasing such as 'the answer is refused where it says no such thing.' The information earns its place, but the structure makes it harder to parse than necessary.

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 8-parameter mutation tool with no output schema, the description covers provider-specific refusals, series replacement reporting, and iCloud exclusion. It leaves some edge cases implicit, such as what happens when answering a non-invitation event, but is otherwise rich enough to call the tool correctly.

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 already 88%, so the baseline is 3. The description goes beyond it by explaining cross-parameter interactions: 'notify is none' suppresses sending the message, and on server-side calendars 'naming a message or notify other than all is refused.'

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 clause gives a precise verb set and resource: 'Accept, tentatively accept or decline an invitation - an RSVP of yes, maybe or no.' That is clearly distinct from events_create, events_edit or events_cancel, though no sibling is named explicitly.

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 explicit when-not guidance ('An invitation in an iCloud calendar is answered from its invitation letter or in Apple's own Calendar app, never here') and scope-selection rules for series versus occurrences. It stops short of naming sibling tools as alternatives for unsupported cases.

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 cover only safety (readOnly, non-destructive, closed-world), yet the description discloses substantial behavior beyond that: provider-specific free/busy semantics on Google/iCloud/Outlook, tentative/cancelled event handling, all-day event handling, the 365-day cap, buffer padding, and precedence between hours/weekdays/preferences. This is exactly the kind of context annotations cannot carry.

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?

The opening clause is front-loaded and useful, but the remainder is several hundred words of chained clauses in a single dense block, mixing provider semantics, return-field explanations, and reconnection flows. It is under-structured rather than concise; an agent must parse run-ons to extract callable facts.

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 usefully explains return concepts (searched, narrowedBy, preferred, unread, cutShort, reconnectAt) and the edge cases that make results possibly incomplete. It is substantively complete for a complex calendar tool, though its packaging makes the information harder to use than it should be.

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 100%, so baseline is 3. The description still adds meaning: limit keeps the earliest stretches, timeZone governs times/hours/weekdays while stored working hours and preferred times stay in the person's zone, and hours and weekdays narrow on top of stored preferences. It loses a point for discussing buffers and other stored settings that are not parameters of this call, which could confuse parameter mapping.

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 free/available stretches across every connected calendar, long enough for the meeting. It is clear what the tool returns, but it never names or contrasts with the obvious sibling circles_free_times_find (or busy_everywhere_set), so sibling differentiation is left 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?

Usage is implied ('an open slot for a meeting, a call or an appointment') and several constraints on the search are given (never starts before now, honors preferences_get, 365-day cap). But there is no explicit when-to-use-this-vs-alternative guidance and no exclusions, so an agent still has to infer when to pick this over circles_free_times_find.

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 destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description still specifies exactly what is destroyed ('a poll's addresses and answers are deleted') and what survives ('a meeting the provider made for one being booked stays'). This destruction/preservation split is precisely the behavioral context annotations cannot convey.

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?

The verb is front-loaded, but the content is packed into one convoluted sentence with ambiguous referents ('events_list shows whether it was', 'for one being booked stays') that require re-reading. Compact, but structure and clarity suffer.

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, annotation-covered tool with no output schema, it covers the key gaps: destruction scope, preserved state, id lookup source, and a follow-up check (events_list). It omits error conditions and required permissions, but nothing essential for 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 coverage is 50% and the description compensates by tying 'id' to its source ('as links_polls_list names it') and by implying the two 'kind' values through 'booking links or group polls.' It adds real semantic meaning, though the kind parameter itself is never described explicitly.

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 states a specific verb ('Close') and two concrete resources ('booking links or group polls') and narrows scope to those 'still open or being booked.' It is clearly distinguishable from sibling write tools like booking_links_create, polls_create, or events_cancel.

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 implies the precondition ('still open or being booked') and routes the agent to links_polls_list for the id, which is useful selection context. However, it never states when NOT to use it or names an alternative for adjacent cases (e.g., cancelling a single meeting via events_cancel), leaving the when-not to inference.

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 readOnly/non-destructive/closed-world, and the description still adds real context beyond them: it excludes booker identity ('never who booked it'), defines what 'stuck' means and which tool fixes it, limits bookings to 30 days ago or later, and notes that times are in the zone captured at creation.

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?

The purpose is front-loaded and nearly every clause carries new information, so little is wasted. However, the whole thing is a single comma-spliced run-on that mixes per-link fields, per-poll fields, booking-page fields, and booking history in one breath, making it harder to parse than it needs to be.

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 carry the return-shape burden and it does: it enumerates link, poll, booking-page, and booking fields, explains sort orders (oldest first for links, most answers first for polls), and covers the stuck-state edge case and timezone semantics.

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 there is nothing for the description to disambiguate; baseline 4 applies. The description's field enumeration describes output, not inputs, which is appropriate here.

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?

Opens with a specific verb plus both resources and a scope filter ('booking links and group polls still open or being booked'), then enumerates the exact fields returned for each. It also names the neighboring tools (links_polls_close, polls_results) so an agent can distinguish this from them without opening schemas.

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?

Usage is clearly implied by the 'still open or being booked' filter and reinforced by routing to alternatives: links_polls_close for stuck entries and polls_results for answers. It does not state explicit exclusions (e.g., closed links or past bookings are out of scope), which keeps it short of a 5.

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 declare a destructive, open-world write, and the description earns its keep beyond that: it discloses that the time is re-verified against every calendar, who is invited and from which provider address, that the meeting is written in the booker's own time zone, and that the poll closes irreversibly. The per-provider free/busy semantics explain how conflict detection actually decides an event's status.

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?

The description is a single sprawling, clause-chained sentence followed by another dense block; key facts (poll closes, invites sent) are buried mid-stream rather than front-loaded. Much of the provider-by-provider free/busy taxonomy reads as reference material rather than something an agent needs to select or invoke this tool.

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, multi-parameter, open-world operation with no output schema, the description covers scheduling, invitation, timezone and conflict-resolution behavior thoroughly. The main gap is that it never says what the call returns (an event id? confirmation?), which an agent would want after a write.

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 the schema already documents poll, start, guestZones and unusualHoursAgreed, including the 'never inferred' constraint on guestZones. The description reinforces meaning contextually ("chosen on their own clock," "the hours an answer named as unusual") but adds no syntax or format detail beyond the schema, so 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?

The opening clause states a specific verb and resource: "Book one of a poll's times in the calendar the person named to receive bookings," and adds the consequential effect that "the poll closes." That is distinguishable from events_create and links_polls_close, though the differentiation is left implicit amid very dense prose.

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 statement of when to use this versus events_create or links_polls_close, nor any stated precondition (e.g. run polls_results first). The references "as polls_results names it" and "as they hold events_create" only imply workflow order through parameter provenance, not guidance.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), it discloses substantial traits: each address gets its own link, Lumman sends no emails, guests vote without an account and can't see others' answers, re-answering replaces, and the poll closes on booking or after 14 days and then retains no address or answer. These are meaningful behavioral and data-retention facts the annotations do not convey.

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?

The content is delivered as a single dense run-on paragraph full of comma-chained clauses, mixing core usage with circle/calendar edge cases. The first sentence is front-loaded, but overall it is overlong and hard to parse, with important facts (link loss, closing/retention) diffused rather than structured.

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 6-parameter mutation tool with no output schema, the description covers link distribution, guest experience, circle semantics, time-zone handling, and lifecycle/retention, which is close to complete. It stops short of a clean return-value or error picture, but the depth of behavioral context largely compensates.

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 100%, so the baseline is 3, but the description adds real meaning: subject is the only thing a guest reads (with an example), guestZones reflect a zone 'known as events_create knows a guest's,' and circle naming changes what the poll is for. This goes beyond the schema's own text, though some details (minutes, times) merely restate it.

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 sentence gives a specific verb and resource (make a group poll) and ties the input times to free_times_find, so an agent can tell what the tool does and roughly where the times come from. It later names polls_results and polls_book, aiding sibling differentiation, but the purpose statement is buried under a large amount of tangential behavior rather than cleanly front-loaded.

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 description explains downstream siblings (polls_results ranks, polls_book books) and notes that making a poll 'does not need' the booking calendar, which implies usage boundaries. However, it never gives an explicit 'use this when / not when' rule or a clean alternative-selection statement; usage must be inferred from the dense prose.

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 this as a read-only, non-destructive, non-open-world operation, so the description gets credit for adding substantial behavioral context beyond that. It explains what a booked or closed poll returns, what the booked field means, and that times use the poll's stored timezone. The only gap is that it does not mention permission or error behavior.

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?

The description is front-loaded with its main purpose and every sentence carries information about behavior or output shape. It is somewhat dense and cryptically phrased in places, but it is not padded or redundant.

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 carries responsibility for explaining return values, and it does so by describing upcoming times, respondent addresses, answer status, ordering, and booking behavior. Some phrases such as "most first" and "each address it is for" remain slightly ambiguous, but the overall context is sufficient for a simple read 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?

Schema description coverage is 100%, so the schema already documents the single poll UUID parameter, including that it matches the id from polls_create. The description does not add syntax or formatting detail beyond that, so the baseline of 3 is appropriate.

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: "Read a poll's answers." It also previews the returned structure (upcoming times, addresses, answer status), making the purpose clear. It does not explicitly contrast itself with siblings such as polls_book or links_polls_close, 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?

There is no explicit guidance on when to use this tool versus alternatives such as polls_book, polls_create, or links_polls_list. The note that a booked or closed poll holds no answers is useful behavioral context, but it is not framed as a selection rule or exclusion condition.

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 and destructiveHint=false, so safety is covered. The description adds real domain semantics the annotations cannot: unset values come back null, a day with no hours is off once any day is set, and the 'receiving' field names the booking calendar. That is genuinely useful behavioral context, short only of pagination/error behavior.

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?

The core action is front-loaded in the first clause and nothing is wasted. The back half is a dense semicolon chain covering three separate rules, which is compact but slightly harder to parse than it needs to be.

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, so the description correctly carries the burden of explaining return semantics, and it does so for the tricky cases (null vs. off, receiving calendar). It falls just short of a complete picture of what a 'scheduling preference' record contains, deferring that to preferences_set.

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 instead spends its words on return-value semantics (null when unset, day-means-off rule), which is the right trade-off for a no-arg reader, though it does not enumerate the full set of returned preference fields.

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 ('Read') and resource ('the person's scheduling preferences') and explicitly positions itself against siblings: preferences_set is the writer whose fields this mirrors, and calendars_list supplies the busy-calendar definition. An agent can distinguish read-preferences from set-preferences 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 cross-references to preferences_set and calendars_list make the read-vs-write split clear by implication, and the mention of 'receiving names the calendar bookings are made in' tells the agent when this data is relevant. However, it never explicitly states 'use this when you need current preferences; use preferences_set to change them', leaving the routing to inference.

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?

The description adds real behavior beyond the annotations: partial update by default, 'null clears one', the exception that receiving's null does not clear, and the confirmation gate on time_zone. Against an annotation set that already declares destructive/idempotent/readOnly, this is meaningful added context. It leaves unstated whether changes are reversible or whether the caller must obtain user confirmation for destructive overrides.

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?

It is compact for a 19-parameter mutation and the core semantics are front-loaded in the first clause. But it is written as a dense run-on of comma-and-semicolon clauses, so a reader must untangle quoted-sounding names like 'receiving, which null does not clear' from the grammar of the sentence. Structure costs more than it should for the length.

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 19-param, nested-object mutation with no output schema, the description covers the decision-relevant edges: partial update, null clearing with one exception, calendar busy flagging, receiving-calendar restrictions, and the time_zone confirmation gate. Gaps remain around whether an empty call is a no-op and what errors to expect, but the agent has enough to call it correctly.

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?

With 19 parameters and 89% schema description coverage, the schema carries most semantics, so the baseline is 3. The description does add genuinely non-obvious semantics for the two nested objects (calendar = busy/counting flag; receiving = the booking calendar, and only a server that sends invitations itself) and the zoneConfirmed linkage, which pushes toward a 4. However, the many scalar preferences (hours, buffers, limits) are not addressed at all beyond 'the rest left as they stand'.

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 ('Change any of the person's scheduling preferences') and adds partial-update semantics ('the rest left as they stand') that distinguish it from a full replace. It also anchors to the read sibling preferences_get, so the agent knows which tool it is paired with. It loses a point because the phrasing 'as preferences_get names them' is dense and forces a second read to parse.

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?

Usage is implied rather than stated: referencing preferences_get hints the read should come first, and the time_zone rule ('changes only with zoneConfirmed true, once the person has confirmed it as theirs') is an explicit conditional. But there is no explicit when-to-use/when-not, no statement about what happens for preferences not listed, and no guidance on confirming changes with the person despite destructiveHint=true.

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