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

Annotations already mark this as a non-read, non-idempotent write, and the description goes well beyond them: it discloses no conflict checking, the pending Meet link behavior, notification defaults, and duplicate-creation risk. These are critical behavioral traits the agent would otherwise only discover at runtime.

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?

Every sentence carries high-value information and there is no filler, but the description is a single dense paragraph that could be easier to scan with structured bullets. It is appropriately sized for a 21-parameter creation tool, just not optimally organized.

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 the complexity, the absence of an output schema, and the minimal annotations, the description is exceptionally complete: it explains return values, time semantics, recurrence requirements, attendee notifications, the pending Meet state, conflict checking, and idempotency risks. An agent has enough to call it correctly and even to avoid common failures.

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?

Even though schema coverage is 100%, the description adds essential semantic rules the schema does not convey: the EITHER/OR time-mode pairing, end_date exclusivity, time_zone being required for recurring events, recurrence requiring the timed pair, and send_updates defaulting to no notifications. This meaningfully exceeds the structured 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?

States a specific verb and resource: 'Creates an event' and immediately lists what is returned. It distinguishes itself from siblings like update_event and get_event by making it a creation operation with a clear output contract.

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

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

Provides explicit when-to-use guidance and alternatives: call query_free_busy first to find a free slot, and check list_events before re-sending after timeouts to avoid duplicates. It also warns about send_updates defaults, which directly affects whether invitations are sent.

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 annotations note readOnlyHint=false and destructiveHint=false, and the description adds rich behavioral context: the tool can auto-decline invitations, affect Chat presence, is always timed, rejects consumer Gmail, and is not retried after ambiguous failures. This goes well beyond the annotations and helps an agent anticipate side effects and error modes.

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 but every sentence earns its place: it covers creation behavior, hard constraints, lifecycle management, and failure handling. Key constraints like primary-calendar-only and always-timed are front-loaded, and there is no filler or repetition of schema boilerplate.

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?

Despite having no output schema, the description tells the agent everything needed to call the tool correctly: what it does, where it works, what can be configured, how to manage/find the created blocks afterward, and how to handle ambiguous failures. This is complete for a tool of this complexity.

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 mentions auto_decline, decline_message, and chat_status in a behavioral context, but the schema already documents each parameter clearly. No substantial new parameter-level meaning is added 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 uses a specific verb and resource: "Creates a Focus Time event" and immediately distinguishes it from ordinary event creation by naming unique behaviors like auto-declining conflicting invitations and flipping Chat to Do Not Disturb. It clearly identifies the primary-calendar-only scope, making the tool's purpose unmistakable.

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 explicitly states when not to use the tool: it only works on the primary calendar of a Google Workspace account, and consumer Gmail or secondary calendars return HTTP 400. It also names the follow-up tools and pattern for verification: update_event, delete_event, and list_events with event_types=["focus_time"]. This gives an agent clear routing and alternative actions.

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 (not read-only, not idempotent), the description discloses concrete side effects: auto-decline applies to 'all overlapping meetings, or only new invitations', send_updates defaults to no notifications, and ambiguous failures are not retried — advising list_events verification. This gives an agent a realistic model of the call's effects and failure semantics.

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?

Five tightly written sentences, each carrying distinct operational value: behavior, compatibility constraint, scheduling format, management pattern, and retry policy. No filler or repetition of schema text.

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 create operation with no output schema, it covers all non-obvious aspects: auto-decline modes, decline message, calendar restriction, always-timed constraint, post-creation management via sibling tools, and handling of ambiguous failures. An agent has enough to invoke 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?

Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds crucial clarification that calendar_id effectively only supports the primary calendar in practice, contradicting the schema's hint that any calendar_id from list_calendars works, and reinforces that start/end_date_time must be timed. This extra meaning pushes it above 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?

The description states a specific action and resource: 'Creates an Out of Office event' with a distinguishing behavior, auto-declining meeting invitations. This clearly separates it from sibling tools like create_event and create_focus_time even before reading parameters.

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 clear usage context: only for primary Google Workspace calendars, always timed, and how to manage the block afterward via update_event, delete_event, and list_events. It does not explicitly contrast with create_event for non-OOO events, but the limitation and management guidance effectively scope when this tool is appropriate.

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 destructiveHint annotation, the description reveals the permanence (no undelete), the side effect on all guests, the conditional email behavior, and the return payload {deleted:true}. It fully discloses what happens at the domain level.

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 dense sentences front-load the most important warning (no undelete) and then cover series semantics, guest impact, email behavior, and return value without any filler. Every sentence 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, non-idempotent operation with no output schema, the description covers the outcome, return value, recurrence nuances, and email side-effect. The schema covers the remaining parameter details, so nothing essential 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?

Even though the schema already documents all parameters, the description adds critical meaning: it explains which event_id form affects the whole series versus one occurrence, and it emphasizes that attendees are not notified unless send_updates=all, reinforcing the default. This materially helps an agent choose the right parameter values.

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 precise verb and resource — "Deletes (cancels) an event" — and immediately distinguishes recurring-series deletion from single-instance deletion by naming list_event_instances. This clearly separates it from siblings like update_event, move_event, and create_event.

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

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

The description gives concrete selection guidance: pass the series master id to cancel the entire series, or an instance id from list_event_instances to cancel only one occurrence. It also clarifies the send_updates option's effect on notification emails, though it does not explicitly contrast delete with non-destructive alternatives.

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 that the operation is read-only and idempotent. The description adds useful behavioral context beyond those hints, particularly the constraint that it only works for calendars already on the user's list and the guidance to interpret event times using the returned timeZone. No contradictions with 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 compact: one sentence enumerates the returned fields and one sentence covers the limitation and fallback. Every clause earns its place, and important constraints are front-loaded.

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 simple read-only tool with one required parameter, the description covers the return fields, the key caveat about calendar-list membership, and the recommended alternative for out-of-scope calendars. There is no output schema, so enumerating fields is valuable and sufficient.

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 single parameter calendar_id is already fully documented in the schema (100% coverage), including the 'primary' special value. The description reinforces the 'user's list' context but does not add substantial parameter-level meaning 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 uses a specific verb ('Fetches') and identifies the resource as 'one calendar-list entry', followed by an explicit list of returned fields (summary, description, timeZone, accessRole, defaultReminders, primary). This clearly distinguishes it from list_calendars and other siblings.

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 states the tool's scope ('Works only for calendars on the user's list') and provides a precise alternative for a known edge case: use raw_request with path calendar/v3/calendars/<id> for a shared calendar never added to the list. This tells the agent exactly when to choose this tool versus another.

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, idempotent, openWorld, and non-destructive behavior, so the bar is lowered. The description adds valuable behavioral context by listing the response contents, covering recurrence-related behavior, and noting that instance ids are accepted. No contradictions with 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 single well-structured sentence that front-loads the core action and then lists relevant response fields. It is somewhat long, but the field enumeration is justified because there is no output schema to carry that 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?

With no output schema, the description compensates by detailing the return fields and addressing series/instance behavior. It does not mention not-found or error behavior, but for a simple read operation covered by strong annotations and complete parameter schemas, this is reasonably 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. The description does not explain the parameters beyond what the schema already covers, but it does add context about instance id handling that aligns with the schema's event_id documentation. No significant additional semantic value beyond structured 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?

The description states a specific verb ('Fetches'), a specific resource ('one event by id'), and enumerates the exact fields returned. This clearly distinguishes it from list_events and list_event_instances, and the additional note about series masters vs instances removes ambiguity.

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 makes clear this is for fetching a single event by id and explicitly says it works for both series masters and individual instance ids. It does not name sibling alternatives or give exclusion criteria, but the single-event-by-id framing gives strong contextual 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?

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds meaningful behavior beyond those: pagination via nextPageToken, hidden/selected flags, accessRole semantics for write permissions, and the important limitation that shared-but-unadded calendars are not returned. No annotation contradiction exists.

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 compact yet information-dense. It front-loads the core purpose and return fields, then adds the primary-id shortcut, pagination, and edge-case behavior in logical order. Every sentence earns its place; there is no filler or repetition of schema details.

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 there is no output schema, the description fully compensates by enumerating the returned fields, explaining role semantics, pagination, and the special 'primary' id. It also covers the key edge case of shared calendars not appearing in the list. An agent has enough context to invoke the tool correctly and interpret its results.

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 all four parameters. The description adds extra value by linking accessRole values to write permissions ('writes need writer or owner'), which clarifies the intent of min_access_role, and by explaining how page_token connects to nextPageToken. This goes slightly beyond a baseline schema-only understanding.

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: 'Lists the calendars on the user's calendar list' and enumerates the exact fields returned. It further distinguishes this tool from get_calendar by explaining what is absent (shared calendars never added to the list) and how to address them.

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

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

The description gives concrete when-to-use and when-not-to-use guidance: the 'primary' special id removes the need to call this tool for the main calendar, and calendars not on the user's list must be addressed by explicit id instead. This helps the agent choose list_calendars versus get_calendar without ambiguity.

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, idempotentHint, and non-destructive behavior, so the description adds complementary behavioral detail rather than repeating it. It discloses that exceptions already made to the series show changed times, that show_deleted includes cancelled occurrences, and that unbounded infinite series require pagination via page_token — all useful traits beyond the structured 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 dense but efficient: purpose first, then instance-id usage, exception behavior, deleted handling, and pagination. Every sentence contributes distinct information and no content is wasted or redundant with the schema.

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

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

Given no output schema, the description still conveys the key return concept (individual ids plus concrete start/end) and covers the operational requirements: correct master id, optional window, deleted-instance flag, and page_token for unbounded series. An agent has enough to call this tool correctly and understand its pagination and filtering 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 coverage is 100%, so the baseline is 3, but the description raises the value by linking event_id to the recurring series master, explaining the instance id convention, and clarifying how time_min/time_max bound the expansion window. It adds meaning beyond the raw parameter descriptions without needing to restate every field.

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 ('Expands') and a precise resource: one recurring event series master turned into individual instances with unique ids and concrete start/end times. This clearly separates it from list_events and get_event, and the example id format removes ambiguity about what an 'instance' is.

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 gives practical guidance: use an instance id with update_event or delete_event for single-occurrence changes, include show_deleted for cancelled instances, and bound the window with time_min/time_max. It does not explicitly state when to prefer this over list_events, but the 'series master id' framing and cross-tool usage instructions make the intended context 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 readOnly/idempotent annotations, it reveals important runtime behavior: all-day ends are exclusive, overlapping events are included, recurring masters appear once without single_events, time_zone never changes stored events, and cancellations surface as status=cancelled. This is exactly the non-obvious context annotations cannot express.

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 long but compressed: every sentence covers a distinct semantic point and none restate the schema verbatim. Front-loading the output fields and the core list operation keeps the most important facts first.

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 12-parameter read tool with no output schema, it explains the result fields, windowing, recurrence expansion, timezone rendering, search, incremental polling, and pagination. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, but the description adds relational meaning: time_min/time_max define an inclusive-overlap window, single_events interacts with order_by, updated_min/show_deleted form a polling pair, and page_token comes from nextPageToken. These cross-parameter insights go well beyond 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?

The lead sentence 'Lists events on a calendar: id, summary, start/end...' names a specific verb, resource, and return fields, making it clear this is a bulk-read tool rather than single-event access. It does not explicitly name sibling tools like get_event or list_event_instances, so sibling differentiation is only implicit.

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 gives concrete usage context: single_events=true is 'required for order_by=start_time and the right choice' for calendar-week questions, time_zone is only render-level, and updated_min+show_deleted enable incremental polling. It doesn't explicitly tell the agent when to pick list_events over list_event_instances or get_event, so it stops short of a full 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 indicate mutation and destructiveness, but the description adds valuable behavioral context: it changes the organizer calendar, preserves the event id, requires writer access to both calendars, restricts which event types can be moved, and notes that send_updates=all notifies guests. This goes well beyond what the annotations alone convey, with no contradiction.

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 four sentences with no filler. It front-loads the core action, immediately clarifies the relationship to update_event, and then packs restrictions, permissions, and side effects into the remaining sentences. Every sentence 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 mutating tool with four parameters and no output schema, the description is complete: it defines the operation, states constraints on eligible events, names the required permissions, explains the attendee-notification side effect, and routes to the correct sibling tool. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description reinforces the meaning of destination_calendar_id and send_updates, but does not add new parameter-level information beyond what the schema provides. A 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 uses a specific verb-resource pair ('Moves an event to a different calendar') and clarifies the key semantic that the organizer calendar changes while the event id stays the same. It also explicitly distinguishes itself from update_event, so an agent can reliably tell this tool apart from its closest sibling.

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 gives explicit when-to-use guidance and names the alternative: rescheduling to another time is update_event, not this. It also states hard constraints (no Out of Office, Focus Time, working-location, or birthday events; only organizers can move events with attendees), which lets the agent decide whether this tool is appropriate before calling 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description adds important behavioral details: 'This is a pure read despite being an HTTP POST', the response maps each calendar id to busy ranges, 'Only busy blocks come back – never event titles or details', transparent events are excluded, and inaccessible calendars appear under errors. These disclosures go well beyond what annotations and schema provide.

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 structured and front-loaded: it starts with the primary output, then explains usage, response behavior, and the read-only nature. Every sentence contributes value with no fluff or repetition. Although it is relatively long, each part is necessary for correct use.

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 the tool's complexity and the absence of an output schema, the description fully covers input requirements, output format, error handling, and the distinction from other operations. An agent has everything needed to call it correctly and interpret results.

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 schema covers all parameters with descriptions, so the baseline is 3. The description adds extra meaning for calendar_ids: 'Input calendar ids (or attendee email addresses, which double as their primary-calendar ids – subject to their sharing settings)', which is not in the schema. This additional semantic context justifies a 4.

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: 'Returns the busy intervals of up to 50 calendars in one time window'. It differentiates itself from sibling tools like create_event by explicitly framing itself as 'the way to find a common free slot before create_event', making its purpose unmistakable.

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 provides clear context for when to use the tool ('the way to find a common free slot before create_event') and input guidance (calendar ids or attendee emails). However, it does not explicitly state alternatives or when not to use it, so it falls 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?

Beyond the annotations, the description discloses that the Bearer token is injected automatically, GET is the default method, non-calendar/v3 paths are rejected before sending, and PUT replaces unspecified fields with defaults. These are exactly the behavioral traits an agent needs before invoking an escape hatch.

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 includes a long example list, but every sentence contributes safety or routing information. The purpose is front-loaded and the dangerous PUT caveat is saved for the end, where it can be read as a warning.

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, open-world raw API tool with no output schema, the description covers URL construction, authorization, method behavior, path validation, and when to prefer a typed tool. It does not explicitly describe the raw response format or error behavior, but those are strongly implied by the tool's purpose.

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 schema already documents all three parameters, so the baseline is 3. The description adds operational semantics the schema lacks: query strings are allowed, paths are relative to https://www.googleapis.com and must remain under calendar/v3, and method defaults to GET.

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 by defining the tool as an 'Escape hatch' for directly calling any Google Calendar API v3 path, with concrete examples such as events.quickAdd and colors. This distinguishes it from the typed sibling tools rather than restating the name.

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 states this tool is for 'requests the typed tools don't cover' and directs users to prefer 'update_event' for PATCH semantics when possible. The namespace restriction also tells the agent which calls will be rejected, reinforcing when the tool is appropriate.

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 goes well beyond the annotations by disclosing the wholesale-replacement semantics for attendees and reminders, the necessity of sending both start and end for time changes, the master-vs-instance recurrence behavior, and the notification default (send_updates defaults to none). These are behavioral traits the annotations (readOnly=false, destructiveHint=true, idempotentHint=true, openWorldHint=true) do not convey, and they do not contradict any of them.

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?

Every sentence carries a distinct operational warning: PATCH semantics, replacement behavior, time pairing, recurrence addressing, notification defaults, applicability, and return value. The most critical constraint is front-loaded in the first sentence, and there is no filler or repetition of schema 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?

For a 22-parameter mutation tool with no output schema, the description covers all major failure modes: lost guest lists, broken time updates, accidental series-wide changes, silent notifications, and OOO/focus-time applicability. It also states the return value ("Returns the updated event"). Remaining details like the exclusive end_date are already in the 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 coverage is 100%, so each parameter is already documented. The description adds update-specific meta-semantics the schema cannot express uniformly: PATCH merge behavior, "a provided nested object REPLACES its predecessor wholesale", the requirement to pair start/end, and the send_updates default. It does not restate individual parameter formats, which the schema already covers.

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 phrase "Partially updates an event (PATCH): only the provided fields change" names a specific verb, resource, and method in one breath. It further distinguishes itself from siblings by spelling out the recurrence nuance (instance id vs series master id) and noting it "Also works to update Out of Office / Focus Time blocks," so an agent can separate it from create_event, delete_event, and move_event 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?

Provides strong conditional routing: "get_event first, send the complete new list" for attendees, "pass that instance's id (from list_event_instances)" for rescheduling one recurrence, and "Guests hear about the change only with send_updates=all". It references sibling tools as preconditions. It does not explicitly contrast against move_event (for a pure time shift) or delete_event, so exclusions are 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.