gcal

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

Annotations indicate this is a non-readonly, non-destructive operation (create). The description adds valuable context beyond annotations: it explains the exclusive end date behavior for all-day events, mentions email notifications for attendees, and notes that the created event ID can be used for future updates/deletion. It doesn't cover rate limits or auth needs, but adds useful behavioral details.

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 well-structured and front-loaded with the core purpose. Every sentence adds value: distinguishing event types, explaining date handling, noting optional attendees, and mentioning ID reuse. No wasted words.

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 (11 parameters, mutation operation), the description provides excellent context. With annotations covering safety, a rich input schema, and an output schema (implied by 'Has output schema: true'), the description focuses on usage nuances and behavioral details, making it complete for agent understanding.

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 parameters are fully documented in the schema. The description adds some semantic context (e.g., 'end date is EXCLUSIVE' clarifies a nuance, and it mentions optional attendees with notifications), but most parameter meaning comes from the schema. Baseline 3 is appropriate given high schema coverage.

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 verb 'Create' and resource 'calendar event', with specific examples (meetings, appointments, all-day events). It distinguishes from siblings like 'update_event' and 'delete_event' by focusing on creation.

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 it (for scheduling events) and distinguishes between all-day vs. timed events. However, it doesn't explicitly mention when NOT to use it (e.g., vs. 'update_event' for modifications) or name specific alternatives among siblings.

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

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

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?

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds valuable behavioral context beyond annotations: it explains timezone interpretation, the default behavior when dateMax is omitted (returns all future events from dateMin), the single-day dateMax workaround, and that event IDs from this tool are prerequisites for update/delete operations. No contradictions with annotations exist.

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 appropriately sized and front-loaded with the core purpose. Each sentence adds value: purpose, usage examples, timezone behavior, dateMax default behavior, single-day workaround, and event ID importance. While efficient, the final sentence about event IDs could be more integrated with the preceding content rather than standing as a separate IMPORTANT note.

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 (readOnlyHint, destructiveHint), 100% schema description coverage, and an output schema (implied by context signals), the description provides excellent contextual completeness. It covers purpose, usage guidelines, key behavioral nuances, and connects to sibling tools, making it fully adequate for an agent to understand and use this tool correctly.

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

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

With 100% schema description coverage, the input schema already provides comprehensive parameter documentation. The description adds minimal parameter semantics beyond the schema - it reinforces the timezone interpretation and single-day dateMax pattern, but doesn't provide significant additional parameter context. 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 tool's purpose with specific verbs ('retrieve events') and resources ('from a specific calendar within a time range'). It distinguishes from siblings by specifying this is for viewing/checking events rather than creating, updating, or deleting them, and differentiates from get_next_availability by focusing on existing events rather than availability checking.

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 usage guidance: 'Use this to view scheduled events, check availability, or find specific appointments.' It also specifies when to use this tool versus alternatives by stating 'Event IDs from this tool are required for update/delete operations,' directing users to sibling tools for those actions. The single-day dateMax example provides concrete implementation 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?

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 indicate it's not read-only and not destructive, but the description adds valuable behavioral context beyond this: it warns that empty strings/arrays clear fields, specifies timezone interpretation, states constraints on moving calendars, and describes the return format. This enhances transparency about side effects and output, though it doesn't cover 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 purpose, followed by key usage rules and warnings in a logical flow. Every sentence adds critical information (e.g., timezone handling, update rules, clearing behavior, constraints, return format) with zero waste, making it dense yet clear.

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 (12 parameters, mutation operation) and rich annotations/output schema, the description is complete: it covers purpose, usage rules, behavioral warnings, constraints, and return format. With output schema present, it doesn't need to detail return values, and it compensates well for the mutation nature by disclosing clearing behavior and calendar constraints.

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 parameters thoroughly. The description adds some semantic context by grouping parameters into 'individual fields' (summary, description, location) vs. 'update times' (startDate, endDate, etc.), but doesn't provide significant additional meaning beyond what the schema specifies. Baseline 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 ('Update an existing event') with the resource ('by eventId'), distinguishing it from siblings like create_event (creates new), delete_event (removes), and get_calendar_events (reads). It specifies what can be updated (fields or times), making the purpose explicit and differentiated.

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 update existing events, with rules for updating fields vs. times. It also states when not to use it ('Cannot move between calendars'), and implies alternatives like create_event for new events or delete_event for removal, though not explicitly named.

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