gcal

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), description discloses key behaviors: all-day events only need dates, timed events require both start and end times, attendee invitations possible, and sendUpdates controls notifications. 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?

Description is a single paragraph with clear front-loading of purpose. It is well-organized but slightly lengthy; still every sentence adds value, so minor deduction for potential slight wordiness.

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 11 parameters, 100% schema coverage, and an output schema, the description covers all essential aspects: purpose, use-case differentiation, parameter behavior, edge cases, and inter-tool dependencies. No gaps.

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 100% schema coverage, description adds critical semantics: clarifies that endDate for all-day is exclusive ('use '2024-01-16' for a single day on Jan 15'), explains that startTime is omitted for all-day events, and specifies that calendarId comes from list_calendars. This goes 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?

Description explicitly states 'Create a new calendar event' and lists specific use cases (meetings, appointments, all-day events). It clearly distinguishes from sibling tools like update_event and delete_event by mentioning the returned event ID for future updates/deletions.

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 detailed usage guidance: when to use all-day vs timed events, required fields for each case, and the exclusive end date nuance. Also links to list_calendars for obtaining calendarId and notes that created ID enables future operations.

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 indicate destructiveHint=true and readOnlyHint=false, which the description aligns with by stating 'permanently delete' and 'no undo'. It adds valuable context beyond annotations: default behavior of sending cancellation notifications and the ability to control it via sendUpdates, though it doesn't mention rate limits or auth needs.

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

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

The description is front-loaded with the core action and key details ('permanently delete', 'no undo', notifications), followed by return value info. Every sentence adds value without redundancy, making it efficient and well-structured.

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

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

Given the presence of annotations (destructiveHint, readOnlyHint), a rich input schema with 100% coverage, and an output schema (implied by return value description), the description is complete. It covers the tool's behavior, key parameters, and output, leaving no significant gaps for a deletion 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?

With 100% schema description coverage, the schema fully documents parameters like eventId, calendarId, and sendUpdates with enum details. The description adds minimal semantics by mentioning eventId and sendUpdates control, but doesn't provide extra meaning beyond the schema's thorough descriptions.

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

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

The description clearly states the specific action ('permanently delete') and resource ('an event by eventId'), distinguishing it from siblings like update_event or create_event. It explicitly mentions the irreversible nature ('no undo'), which further clarifies its purpose.

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 implies usage for deleting events, with context from siblings suggesting alternatives like update_event for modifications or get_calendar_events for viewing. However, it lacks explicit guidance on when to use this tool versus others (e.g., no mention of prerequisites like needing eventId from list operations).

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 mark the tool as read-only and non-destructive. The description adds behavioral details: timezone interpretation, default behavior without dateMax (returns all future events), and pagination via pageToken. 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 concise (5 sentences) and front-loaded with purpose. Every sentence adds value, including the note about event IDs. Slight improvement could be to remove redundancy with schema, but overall efficient.

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 has an output schema, return value explanation is not needed. The description covers usage, parameters, timezone handling, pagination, and the important single-day event tip. Lacks mention of rate limits or error conditions, but these are not critical for a read-only tool.

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

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

Schema coverage is 100%; all parameters have descriptions. The description adds value by explaining calendarId source (list_calendars) and providing a usage note for dateMax. It also reinforces that timeMin and dateMin are required.

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 ('Retrieve events') and clearly identifies the resource ('from a specific calendar within a time range'). It distinguishes from sibling tools by stating it is for viewing, not creating/deleting/updating events.

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 on when to use: 'view scheduled events, check availability, or find specific appointments'. It also includes an important note about single-day events and links event IDs to update/delete operations. Lacks explicit exclusion of alternatives like get_next_availability.

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, establishing safety. The description adds valuable behavioral context beyond annotations: the 30-day search limit, pagination mechanism using searchedUntil, slot alignment to startTimeIncrement boundaries, and the ability to restrict to specific hours/days. This significantly enhances understanding of the tool's operational behavior.

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

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

The description is efficiently structured in four sentences with zero waste: first states core purpose, second defines search scope and output format, third explains pagination, fourth adds filtering and alignment details. Every sentence contributes essential information without redundancy.

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 moderate complexity (9 parameters, read-only operation), the description is complete: it explains what the tool does, its constraints (30-day limit), output format, pagination mechanism, and key behavioral details. With annotations covering safety and an output schema presumably documenting the return structure, no critical gaps remain.

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 100% schema description coverage, the input schema already documents all 9 parameters thoroughly. The description adds minimal parameter semantics beyond the schema, mentioning timezone specification and startTimeIncrement alignment, but doesn't provide additional syntax or format details. This meets the baseline expectation when schema coverage is complete.

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 clearly states the specific action ('Find next 10 available time slots in a calendar') and resource ('calendar'), distinguishing it from siblings like get_calendar_events (which retrieves existing events) or create_event (which creates events). The verb 'find' with the quantitative '10 available time slots' provides precise scope.

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 this tool ('Find next 10 available time slots') and implies pagination guidance ('Use searchedUntil with new startFromDate/Time to paginate'), but doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools (e.g., get_calendar_events for viewing existing events).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds useful context beyond annotations by explaining the types of calendars (primary, shared, subscribed, secondary) and the importance of calendar IDs for other operations. However, it does not disclose behavioral traits like pagination details or rate limits, which are partially covered by the input schema but could be elaborated.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by usage guidance and additional context. Each sentence earns its place by providing value, such as explaining calendar types and ID requirements, without unnecessary repetition or fluff. It is appropriately sized for the tool's complexity.

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 low complexity (list operation), rich annotations (read-only, non-destructive), and the presence of an output schema, the description is complete enough. It covers the purpose, usage context, and key behavioral insights (e.g., calendar types and ID importance), without needing to explain return values or detailed parameters, which are handled by structured data.

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%, with clear descriptions for both parameters (pageToken and maxResults). The description does not add any parameter-specific semantics beyond what the schema provides, such as explaining how pagination works in practice or default behaviors. Since the schema does the heavy lifting, a baseline score 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 clearly states the specific action ('List all calendars') and resource ('calendars the user has access to'), distinguishing it from sibling tools like create_event or get_calendar_events. It explicitly mentions the purpose is to 'discover available calendars before performing calendar operations,' which is distinct from operations that manipulate events or check availability.

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 explicit guidance on when to use this tool ('to discover available calendars before performing calendar operations') and implies when not to use it (e.g., for event-related operations handled by siblings). It also notes that 'The calendar ID is required for all other calendar operations,' reinforcing its role as a prerequisite step.

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 provide readOnlyHint=false and destructiveHint=false, which indicate mutability but not behavior. The description adds critical details: timezone interpretation, clearing fields with empty values, inability to move between calendars, and return format. No contradiction 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 concise with four sentences, each serving a purpose: main purpose, timezone handling, field update patterns, warning about clearing fields, and limitation. No unnecessary 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?

Given the complexity (12 parameters, 100% schema coverage, output schema present), the description covers key usage nuances (time update rules, clearing behavior, calendar restriction). It omits mention of the sendUpdates parameter but that is detailed in the schema. Overall, it is sufficiently complete for an agent to use effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by clarifying the relationship between parameters for time updates (must provide all startDate, endDate, and optionally startTime, endTime) and the timezone context. This aids in correct parameter usage.

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 clearly states 'Update an existing event by eventId', specifying the verb and resource. It distinguishes from sibling tools like create_event, delete_event, and get_calendar_events.

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

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

The description explains when to use this tool (to update an event) and provides specific guidance on updating fields vs times. It warns about empty strings clearing fields and notes limitations like 'Cannot move between calendars', though it does not explicitly list alternative tools for specific cases.

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