Multi Calendar

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

Annotations only declare the generic write/non-destructive profile, and the description goes well beyond that: 14-day expiry and refusal of later times, re-validation against calendars, working hours, buffers, notice and daily maximum, the fallback Mon-Fri 09:00-17:00 hours, and the Google vs Outlook free/busy semantics. This is exactly the operational context an agent cannot get from structured fields.

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 block with spliced clauses and dashes, so it is hard to scan and front-load. Much of the behavior is worth stating, but the run-on prose and lack of any structure make the useful parts costly to extract.

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 the return burden and does state that the answer gives the link id and close time. It also covers expiry and booking behavior, though it never mentions the actual link/URL the guest receives, leaving one small return-value 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?

Schema coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema: it tells the agent to embed the host's name in subject ("Intro call with Sam Lee") and clarifies that times are re-checked and guestZone surfaces each time in the guest's zone, neither of which the schema states.

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 concrete verb and resource ("Make a link") with the artifact's shape: times from free_times_find, a named meeting, one guest. It is distinguishable from sibling tools like polls_create or booking_page_set in intent, but it never names or contrasts those siblings directly.

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 a prerequisite chain ("times free_times_find found") and describes the downstream guest flow, so usage is inferable. However there is no explicit when-to-use / when-not guidance versus the poll and booking-page siblings, leaving the agent to infer selection.

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 destructiveHint=true and idempotentHint=true, and the description substantiates these: newName moves the page to a new address while 'its old one answers nothing', fields not given are left alone (idempotent partial update), and a page persists 'until the account goes'. It also discloses substantial downstream behavior (booked-once-per-time, provider free/busy rules). It stops short of stating permissions or rate limits, so not a 5.

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

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

The description is one long, clause-dense run-on mixing upsert rules, guest booking behavior, timezone handling, and provider free/busy semantics. Key operational facts are not front-loaded and the archaic style ('answers nothing', 'where they stored none') impedes parsing rather than aiding it.

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?

Given a mutation tool with 4 params and no output schema, the description does cover creation vs. update, guest booking constraints, and free/busy rules reasonably thoroughly. It omits return values and permission requirements, and its density means an agent may miss details it does contain.

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, but the description adds real meaning beyond the schema: newName relocates the address and deactivates the old one, and subject should carry the person's own name (e.g. 'Intro call with Sam Lee') because the public page names nobody. That is genuine semantic guidance not present in the field 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 verb 'Set' and resource 'booking page' are present, and the description does convey upsert semantics (update by existing name, add otherwise). However, the purpose is buried in indirect phrasing like 'named by the name it answers at on this site', which forces the agent to decode the sentence to learn it creates OR modifies a page. It is distinguishable from siblings only after effort.

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 tool versus alternatives such as booking_links_create or polls_create. The description describes effects and guest-facing behavior but never says under which circumstances an agent should choose this tool over a sibling, nor any prerequisites or exclusions.

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 (destructiveHint, idempotentHint, readOnly false), the description discloses a great deal of runtime behavior: blocks appear within minutes, cover the coming 60 days, are private and titled with a specific format, are placed only in the main calendar of the named account, are deduplicated across multiple calendars, follow their event, and are re-placed if removed by hand. 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 description is a single sprawling, em-dash-laden run-on that is hard to parse and not front-loaded around the primary action. While most clauses carry real information, the structure undermines readability and forces re-reading to extract the core behavior.

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, cross-account, destructive write tool with no output schema, the description covers the effect, lifecycle, scoping, and read-path (busyCopies) well. It omits only secondary details such as permission/auth requirements and any rate-limit behavior.

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 every parameter including the boolean on, the into/account addresses, and the provider disambiguators. The description adds little parameter-specific meaning beyond the schema, 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?

The description states a specific action — mirroring one account's calendar as busy blocks into another named account, or removing that mirroring. It distinguishes itself from siblings by noting that events_list surfaces blocks under busyCopies and that no tool counts, moves, or cancels a block. The unusual 'Show ... or stop' framing is a bit indirect but the resource and effect are clear.

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 context (make an account's busy time visible in another connected account) and points to calendars_list for the identifiers and events_list for reading blocks. However it never explicitly frames when to choose this over alternatives like free_times_find or circles_free_times_find, so the when-to-use guidance is only implied.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description still adds substantial behavior: it discloses ownership vs. mere sharing, Google-specific access modes (edit/read/freeBusy), hidden calendars, per-calendar time zones only where the provider keeps them, the busyShownIn cross-account view, and the unread/cutShort failure and truncation cases. This is genuinely useful context beyond the annotations, though it documents the response rather than any call-time 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?

It is front-loaded with the operation and every clause carries return-field information rather than padding, but the entire description is a single sprawling run-on sentence built from comma-separated clauses and em-dash asides. It front-loads well but is hard to parse and would benefit from being broken into structured sentences.

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 what comes back, and it does so in detail, including the unread (unreadable accounts / restricted events) and cutShort (more calendars than one answer carries) edge cases. The main omission is any explicit statement of how to page past the described cutShort truncation.

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 empty with additionalProperties=false, so there are no parameter semantics to explain; the baseline for a 0-parameter tool is 4. Nothing in the description conflicts with 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 opens with a specific verb and resource ('List every calendar of every connected Outlook.com, Microsoft 365 and Google account') and scopes the breadth across all accounts, which cleanly separates it from siblings like events_list or free_times_find. An agent can identify the operation and its scope 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?

Usage is only implied: the tool lists calendars, so an agent infers it should be called for calendar discovery, but no alternative is named and no precondition or 'use this instead of X' guidance is given. Given the 0-parameter, list-everything nature of the tool the implied usage is fairly unambiguous, but it stops short of explicit routing.

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 supply readOnly/openWorld/destructive hints; the description goes far beyond them, disclosing which calendars are read and through whose connection, Google vs Outlook busy semantics (tentative/cancelled/all-day events), the 365-day search cap, and the unknown/readInPart/noCalendar/notJoined/tickedNothing member states. This is unusually deep behavioral disclosure for a read-only 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?

The core purpose is front-loaded in the first clause, but the remainder is a single dense block of run-on clauses with coined terms (tickedNothing, readInPart) that force re-reading. Nearly every sentence carries genuine semantics, so it is information-dense rather than padded, but the structure is poor and the length approaches the limit of usability.

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 carries the return-value burden itself and does so thoroughly, naming every status bucket (busy, unknown, readInPart, noCalendar, notJoined, tickedNothing), the per-stretch members list, and the unusual marker. For an algorithmically complex tool this leaves little an agent needs to know unstated.

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 beyond the schema: timeZone falls back to the stored zone, limit keeps the earliest stretches, hours/weekdays restrict what the search considers, and the window is capped at its first 365 days. These are semantics the schema text alone does not convey.

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+scope: "Find when everyone in one of the person's circles is free," which clearly separates it from the sibling free_times_find (single-person) and from circles_list. It never names those siblings explicitly, so the differentiation is inferable 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?

Usage is implied by the scope (mutual availability inside a circle), and the closing line "circles_list names each circle's id" usefully points at the prerequisite for the circle parameter. There is no explicit when-to-use-this-vs-free_times_find guidance and no exclusions or failure 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?

Goes well past the annotations: it discloses case-insensitive name matching with ambiguity refusal that names both ids, per-address link issuance, the 'kept' vs reissued link distinction, that reissue stops the old link (consistent with destructiveHint=true), and the critical fact that no mail is sent by the system. These are exactly the operational traits an agent cannot infer from the 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?

Front-loads purpose and circle selection, and every sentence carries information rather than filler. The dense, idiosyncratic phrasing ('made where the person has none by it', 'Lumman sends invitees nothing') costs some readability, but nothing is 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 compensates by naming the response fields (circle id, whether it was made, kept vs new links) and the no-email side effect. It leaves out authorization requirements and rate limits, but for a 4-parameter mutation tool this is close to complete.

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: name-vs-id precedence, case-insensitive matching semantics for name, and that a new address gets its own link while an existing one keeps its link unless reissue is set. Only the addresses/reissue mechanics largely duplicate the schema wording.

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 (invite people by address into a circle) and immediately scopes it to 'one of the person's own circles', naming circles_list as the authority for circle ids. An agent can distinguish this from circles_list or circles_free_times_find without opening any 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?

Clear about the id-vs-name selection rule ('an existing one by its id... or one by its name, matched whatever its case') and explicit about what to do afterwards ('hand the links to the person to share, or send each from the person's own mailbox'). It stops short of stating when-not to use it or naming an alternative tool for a different invite path.

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?

Annotations already declare destructive=true and idempotent=true, so the safety profile is covered; the description goes beyond them by disclosing that the provider sends the cancellation from the account's own address, that Outlook alone sends the message, and that copyOnly sends nothing while leaving Google showing the account as declined. It stops short of stating irreversibility or auth requirements, but the side-effect disclosure is genuinely useful.

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+resource is front-loaded, and nearly every clause carries real information (no filler). However, it is compressed into a single sprawling paragraph with tangled clauses such as 'as notify chooses, and Outlook sends message with it', which makes it harder to parse than the content warrants.

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 eight parameters, open-world external effects, and no output schema, the description covers ownership, notification behavior, provider differences, and the copyOnly edge case including its Google-side aftermath. An agent has enough to call it correctly; only the absence of any pagination/return or error-behavior note keeps it from being fully complete.

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 schema, including the provider quirks for notify and message. The prose restates some of that (copyOnly, notify) rather than adding syntax or format detail beyond the schema, 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?

The opening clause 'Cancel an event the account organises' gives a specific verb and resource plus an ownership scope, and the description explicitly contrasts itself with events_respond for events the account does not own. The purpose is identifiable, though the delivery is buried in a dense run-on sentence rather than stated crisply.

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 names the alternative path explicitly ('Someone else's event is not cancelled here: declining it with events_respond') and explains the calendar-dependent consequences of that alternative. It also gives the condition for copyOnly (someone else's event, own copy only). It stops short of a clean when-not list, but the routing guidance is concrete.

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?

Far exceeds what annotations provide: the idempotency rule is spelled out precisely (same arguments find the event the first made rather than a second, for the rest of that day UTC, Outlook only while Microsoft recognises the repeat) which is far richer than idempotentHint=true. It also discloses which inputs are refused and why, the unusual-hours send block, and the default meeting-link 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?

Information density is high and the calendar rule is front-loaded, but the archaic, clause-heavy prose is hard to parse and there is no structure (no grouping of ids, guests, recurrence, sending). Much of the content earns its place given 18 parameters, but the packaging makes it harder 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 does carry return-shape context (the answer's times in its timeZone, guestTimes, joinUrl) and covers invitation, notification, recurrence and refusal branches. It is close to complete for a tool this complex, though a few enum params (kind, showAs) get less prose than their provider caveats deserve.

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 72%, above baseline, yet the description still adds semantics the schema lacks: the Outlook 255-character subject cap, the instant-vs-date difference between start and end, and that each recurrence keeps the start's own hour across clock changes. These are genuine additions, not restatements.

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 in one of a connected account's own calendars') and immediately scopes it: own calendars only, a shared-with calendar is refused. That scope cleanly separates it from events_edit, events_list and polls_create in the sibling 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 concrete selection rules (which calendar via calendarId from calendars_list, else default), the refusal condition for shared calendars, the provider caveats, and the exact gate for unusualHoursAgreed. It never names an alternative sibling ('use events_edit to...'), 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true): it explains preservation behaviour (id, other guests' answers, join link kept; a lone start keeps duration, a lone end keeps the start), provider-side refusals with reasons, the Outlook online-meeting body refusal, and notification fan-out ('from the account's own address, as notify chooses'). This is exactly the mutation context a destructiveHint flag alone 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?

Front-loaded with the core action and nearly every sentence carries distinct information, but it is one very long, densely packed paragraph with idiosyncratic phrasing that makes it hard to scan. The size is justified by the complexity, yet the structure costs readability.

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 mutation tool with no output schema, it covers what an agent needs: patch semantics, recurring-series scope and refusals, provider limitations, notification behaviour, and the shape of the response (provider, calendarId where applicable, webLink). Remaining gaps (e.g. reminders format) are handled by schema descriptions.

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 only 68%, and the description compensates: it clarifies that start/end are named as events_create names them and that naming both in the other form flips timed/all-day, that times are in the person's own time zone, and that addGuests/removeGuests take guests on and off. The guestZones/'own hours' sentence also explains cross-field timing behaviour. It adds real meaning where the schema is silent.

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 precise verb+resource ('Change an event the account organises, in place and in one call') and then enumerates exactly which fields the update can touch (subject, body, location, start/end, showAs, privacy, reminders, video, guests). An agent can distinguish it from events_create and events_cancel from the description alone.

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 clear operating conditions: partial-patch semantics ('Only what is named changes'), the occurrence-vs-series choice and the rule that a whole series with separately-changed occurrences is refused, and the precondition that changing guests requires inviting to be allowed on the account. It does not explicitly route to sibling tools (e.g. use events_create to make a new event), 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 readOnly/destructive/openWorld, and the description adds substantial behavior beyond them: events whose text screens as a prompt attack are withheld, Lumman's own busy copies are answered under busyCopy with about/switched-off fields, and reminders are reported as minutes or an empty list. These are real edge-case behaviors an agent cannot get from the 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 purpose is front-loaded, and given the absence of an output schema, the enumeration of returned fields earns its place. However, it is delivered as one extremely dense run-on sentence with heavy nesting, which hurts parseability rather than being genuinely concise.

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 the full return-value burden and does so thoroughly: join links, organizer/guest roles and answers, kind, privacy, visibility, reminders, web link, timeZone handling, recurrence fields (seriesId, originalStart), the prompt-attack withholding rule, and the busyCopy variant. Nothing material 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 100%, so the schema already documents account, eventId, provider, timeZone and calendarId, including when provider and calendarId are needed. The description reinforces that output times follow the timeZone parameter, but adds little new meaning about the parameters themselves; 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 establishes a specific verb and resource ('Read one event whole') and immediately scopes it as 'by the account, calendarId and id events_list names,' which cleanly separates it from the list-oriented sibling events_list. An agent can distinguish it from events_edit and events_list without opening any 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?

Usage is implied through repeated references to sibling conventions ('as events_list names them', 'which events_edit writes as an empty list'), but there is no explicit when-to-use statement or exclusion such as 'use events_list to discover ids first' or 'use busyCopy for a busy view only.' The agent must infer the call context.

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 safe, read-only, closed-world read, and the description adds substantial context beyond them: 50-events-per-calendar cap with cutShort/readTo/continueAt resumption, unread reasons (needs_reconnection, not_allowed, refused, gone, rate_limited, unavailable), withheld prompt-attack events, malformed counts, busy-copy exclusion, and 255-char description truncation.

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 front-loaded with the core purpose, and most sentences carry needed return-value information since there is no output schema. But it is a single massive run-on paragraph with no grouping, making it hard to scan for the operational details an agent needs (pagination, unread, withheld).

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 9 parameters, the description carries the full burden and delivers: it documents event fields, copies, occurrence/originalStart, timeZone handling, answer statuses, join links, pagination, and all error/omission cases. Nothing essential to calling or interpreting the tool correctly 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 the baseline is 3, but the description adds real meaning: query semantics differ per provider (Google searches all fields, Outlook searches titles alone and is read across the period then matched), provider is 'needed only where two connected accounts share an address,' and continueAt must be paired with the cutShort account and calendarId.

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+scope: 'Read the events of a period across every connected calendar, earliest first, or latest first with newestFirst.' It also distinguishes itself from the sibling events_get by noting events_get reads a description whole, and from calendars_list by defining account/calendarId in terms of it.

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 conditional guidance: narrowing with account/provider/calendarId, resuming with continueAt after cutShort, and handling busy copies ('asked about one, say it is a busy copy of that account... or take that pair away with busy_everywhere_set'). However it never contrasts itself against other listing/availability siblings such as free_times_find or circles_free_times_find, so the when-not framing 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?

Annotations already declare this as a non-read-only, destructive, open-world mutation. The description adds real value beyond that: it explains that the provider sends the answer from the account's own address, that notify=none suppresses notifying the organiser, and that answering a series cascades to other occurrences and reports a replaced count. The Google message-visibility caveat, however, lives only in the schema, not the description.

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 action is front-loaded, which is good, but the second sentence ('Answering a whole series answers each occurrence answered apart from it too, and says under replaced how many of their answers it replaced') is a convoluted run-on that is hard to parse, hurting readability more than length does.

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 with no output schema, the description covers the important behavioral edges: cascading series answers and the returned 'replaced' count. Combined with the 88%-covered schema, an agent has enough to invoke this correctly, though provider-specific fallbacks (calendarId, provider) are left entirely to the schema.

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 88%, so the schema already documents nearly every parameter including notify, scope, and message semantics. The description largely restates the notify and series behavior rather than extending it, so it does not meaningfully exceed the schema baseline.

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 set (accept, tentatively accept, decline) against a specific resource (an invitation), and the response enum mirrors this exactly. It is clearly distinguishable from siblings like events_edit, events_cancel, or events_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?

Usage is implied by the nature of the tool rather than stated. There is no explicit guidance on when to choose this over events_edit for changing a reply, and no prerequisites are given, though the scope/series and notify clauses give partial context for deciding how to invoke it.

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 this as a safe read (readOnlyHint=true, destructiveHint=false), and the description goes far beyond them: provider-specific free/busy interpretation (Google vs Outlook tense answers, cancelled events, all-day events), buffer padding semantics, the narrowedBy reasons (notice, horizon, yearCap, readLimit, daysOff, fullDays), and warnings that unread/cutShort calendars may still hold busy time. It even supplies a reconnection URL for accounts needing reauth.

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 first sentence is well front-loaded and most content is substantive rather than filler, which earns credit. But the body is an extremely dense, run-on block of semicolon-chained clauses and nested qualifiers that is hard to parse, and it is very large for an agent to consume before acting.

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 carries the return-value burden and does: 'Each stretch answers once, in time order, with its parts inside the preferred times under preferred,' plus a full inventory of narrowedBy reasons and the searched window. Nothing needed to interpret the result 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 the baseline is 3. The description mostly restates schema content (limit = earliest stretches, hours = only these hours) but does add the zone-resolution rule (times/hours/weekdays use the named zone, stored working hours and preferred times use the person's own). Net value over the structured fields is marginal.

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 with scope: 'Find when the person is free in every connected calendar: each stretch of a window that no busy time touches and that is at least as long as the meeting.' An agent can tell this computes free slots rather than listing events. However, it never differentiates itself from the obvious sibling circles_free_times_find, so the 'every connected calendar' framing is the only (implicit) distinguishing signal.

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 usage constraints: the search never starts before now, honors preferences_get, is capped at the window's first 365 days, and narrows by hours/weekdays. It does not, however, explicitly state when to prefer it over circles_free_times_find, so routing between the two free-times tools is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. Beyond that the description adds real value: it specifies the downstream effect (page answers closed from then on), that a poll's addresses and answers are deleted, and that a provider-created meeting survives with events_list as the way to check. That is concrete mutation detail the 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?

Three sentences, purpose front-loaded, no filler. The middle sentence about the surviving meeting is slightly tangled in construction but carries non-obvious information that earns its place.

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 mutation with no output schema, the description covers what is destroyed, what persists, and how to verify via events_list, plus where ids come from. Only the kind enum semantics and any permission requirements remain unstated.

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 50% schema coverage, the 'id' parameter is described in the schema, but the 'kind' enum has no schema description. The description only indirectly covers it via 'booking links or group polls', and it helpfully links the id to links_polls_list as the naming source. Marginal added meaning over the schema, so the baseline 3 fits.

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 ('Close') applied to a specific resource ('booking links or group polls') and scopes it to those 'still open or being booked'. An agent can tell this is the closing counterpart to booking_links_create / polls_create. The phrasing is somewhat convoluted, but the operation is 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?

The scope constraint ('still open or being booked') implies when the tool applies, and it points at links_polls_list for identifying targets. However, it never names an alternative for related outcomes (e.g. events_cancel for the meeting that survives) or states explicit preconditions like permissions. Usage is implied rather than spelled out.

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 the read-only, non-destructive, closed-world profile. The description adds genuinely useful behavior beyond that: a privacy boundary ('never who booked it'), a 30-day cutoff for returned bookings, and stuck-state semantics tying into links_polls_close.

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?

Front-loaded with the purpose and every clause carries information (field lists, ordering, cutoff, privacy). It is one very long run-on sentence, which hurts scannability, keeping it short of a 5.

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 the full burden of describing return shape and does so field-by-field for links, polls, pages, and bookings. Nothing an agent needs to invoke and interpret this correctly 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?

Zero parameters and 100% schema coverage, so the baseline is 4 per the rubric. There is no parameter surface for the description to add value to, and nothing is misdescribed.

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

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

Specific verb+resource+scope: 'List the person's booking links and group polls still open or being booked', with ordering and per-entity field enumeration. It cleanly separates itself from siblings by naming links_polls_close for closing and polls_results for reading answers.

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 states the condition that selects this tool ('still open or being booked') and routes to two alternatives (links_polls_close, polls_results). It lacks an explicit 'use this instead of X list' comparison, but the routing 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?

Annotations already declare destructiveHint=true and openWorldHint=true, yet the description still adds real substance: the time is re-validated against every calendar, invitations are sent by Microsoft or Google from the host account's own address, the meeting is written in the host's time zone, and the poll is closed as a side effect. It also explains the provider-specific free/busy rules that determine whether a slot still 'holds' its time. The value is genuine, though the run-on phrasing blurs which details are guarantees versus conflict-detection heuristics.

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 action is front-loaded and there is little pure filler, but the description is a dense sequence of nested clauses ('exactly the people the poll is for are invited by Microsoft or Google from that account's own address') that is hard to parse on first read. Information density is high; readability and structure are poor.

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 the return-value burden and does not say what comes back on success or what happens when the re-check shows the time no longer holds. It does, however, cover the major side effects, time-zone handling, and conflict semantics, which is substantial for a 4-parameter tool whose schema is fully documented.

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 'poll', 'start', 'guestZones' and 'unusualHoursAgreed' are already documented in the schema, including the explicit warning that a guest's zone is never inferred. The description adds nothing parameter-specific beyond the events_create analogy, 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?

The first sentence names a specific verb and resource: booking one of a poll's times into the calendar of the person who receives bookings, and it distinguishes the action from polls_create/polls_results/links_polls_close by describing the invite-and-close outcome. The archaic phrasing ('the person named to receive bookings') makes the actor harder to identify than it should be, but the core action is 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?

Usage is only implied: the description references polls_results as the source of the 'start' value and compares invitee-hour handling to events_create, which hints at the post-poll-confirmation workflow. There is no explicit statement of when to call this versus polls_results (view times) or links_polls_close (close without booking), and no stated prerequisites such as the poll needing to be open.

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 readOnly=false declared, the description adds unusually rich behavior beyond annotations: each address gets its own link, a lost link requires a new poll, the app sends nothing (caller must distribute), guests answer without an account, re-answering replaces the prior answer, answers are private, and the poll closes on booking or after 14 days, after which it retains no address or answer. It also states bookings need a calendar that poll creation does not require.

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?

Front-loaded with the core purpose, but the body is a dense run-on of long clauses (link lifecycle, circles, guest pages, time zones) that resists parsing. Much of it earns its place as behavior, yet it could be broken into shorter sentences or a lifecycle list 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?

No output schema exists, and the description partly covers returns ('handed back in this answer alone'). For a mutation tool with six parameters it adequately covers lifecycle, closure rules, privacy, distribution responsibility, and the calendar dependency. It leaves the exact response shape vague, so not 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 the baseline is 3, but the description adds real meaning beyond the schema: subject should carry the host's own name ('Intro call with Sam Lee') because the guest page names nobody but the meeting, and guestZones is tied to a known time zone as events_create knows one. These are substantive usage notes not present in the schema 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?

Opens with a specific verb+resource: 'Make a poll of times free_times_find found for a named meeting, for the people it is for.' It clearly distinguishes itself from siblings by naming polls_results (ranks), polls_book (books), and circles_free_times_find as the intended upstream source. The phrasing is convoluted, but an agent can identify the operation 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?

Gives clear context for use: times come from free_times_find, invitees are 'the people it is for,' and the circle variant is spelled out ('Naming a circle makes a poll for members of it or ... addresses invited that have not joined'). It routes downstream work to polls_results and polls_book. It stops short of explicit when-not/alternative selection, so not 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 establish the read-only, non-destructive, closed-world profile, so the bar is lower. The description still adds genuinely non-obvious behavior: that answers originate from the respondent's own link, and that booked or closed polls return no answers at all with 'booked' naming the booking time. That edge-case disclosure is real value beyond the structured fields.

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 front-loaded sentence of moderate length, so it is not bloated. But the dense, archaic phrasing ('most first, then each address it is for') forces re-reading, and the closing clause about 'booked' is awkwardly appended rather than structured, so the words do not fully earn their place.

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 carries the burden of explaining the return shape; it makes a genuine attempt (upcoming times with eligible addresses, then per-address response status, plus the empty result for booked/closed polls). But the opaque wording leaves the exact structure and ordering only partially recoverable for a read tool an agent must parse.

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 one parameter at 100% schema description coverage, the schema already explains that 'poll' is the poll's id. The description only obliquely implies a poll input ('a poll's answers') and adds no format, naming, or sourcing detail beyond the schema's own 'as polls_create names 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?

It opens with a clear verb+resource, 'Read a poll's answers', which distinguishes it from write siblings like polls_book or polls_create. However, the rest of the sentence is written in a convoluted, almost archaic register ('times still to come', 'most first', 'each address it is for') that makes the actual returned content hard to parse on first read.

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 only usage-adjacent information is the conditional 'A booked or closed poll holds none', which hints at when results will be empty but never states when to reach for this tool versus links_polls_list, polls_book, or links_polls_close. No alternatives or prerequisites are named, leaving the agent to infer routing from 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 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?

Annotations already declare idempotent=true, destructive=true and readOnly=false, so the safety profile is covered. The description adds genuinely non-structured behavior: unspecified fields are left untouched, null clears a field, null does NOT clear receiving, and time_zone only takes effect with zoneConfirmed true. It does not mention permission requirements 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 general partial-update rule is correctly front-loaded, and each clause covers a distinct behavior that earns its place. However, the two comma-spliced run-on sentences are dense and force the agent to re-parse to separate the rules for calendar, receiving and time_zone.

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, zero-required, no-output-schema mutation tool, the description covers the highest-risk semantics (partial update, null clearing, the receiving exception, the time_zone gate). The remaining hours/horizon/buffer fields are adequately handled by the 89%-covered schema, so nothing critical 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 89%, so baseline is 3, but the description meaningfully exceeds the schema for calendar ('marks one calendar ... as counting as busy or not'), receiving (the calendar bookings are made in, and exempt from null-clearing) and time_zone (gated on zoneConfirmed). Those are cross-field semantics the schema does not express, since most schema descriptions are only form examples.

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 any of the person's scheduling preferences', and cross-references preferences_get as the source of field names, which implicitly separates it from the read sibling. It does not explicitly name other write siblings such as busy_everywhere_set or booking_page_set, so routing is inferred 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?

Usage is implied by 'Change any of the person's scheduling preferences ... the rest left as they stand', which tells the agent this is a partial-update path and that calling preferences_get first is how field names are learned. There is no explicit when-not guidance or comparison against alternative write tools like busy_everywhere_set.

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