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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses return value ('Returns the created calendar object as JSON, including its calendar_id') and error behavior ('Returns "Error: Invalid request..." (400) if title is missing'). 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?

Well-organized with clear sections: what it does, args, returns, examples, don't-use guidance, and error handling. Each section earns its place without redundancy, and the core purpose is 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?

Despite lacking an output schema, the description covers return format, error handling, usage alternatives, and parameter guidance. For a 9-param tool with 100% schema coverage, this is sufficiently 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 baseline is 3. The description adds value by providing a usage example for the title parameter and clearly separating required from optional fields, which helps the agent understand parameter selection in context.

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 and resource: 'Creates a new calendar (a container that events live inside).' It distinguishes from siblings by explicitly contrasting with addevent_create_event, making the purpose 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?

Provides explicit when-not-to-use guidance: 'Don't use when: you just need to add an event to an existing calendar (use addevent_create_event with calendar_id instead).' Also includes a concrete example to illustrate when to use 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 indicate non-read-only, non-idempotent behavior. The description adds valuable behavioral context: error handling for missing fields/invalid calendar_id/400 responses, default behaviors (datetime_end defaults to +1 hour), return value shape (event_id and landing_page_url), and caveats like recurring_rule alignment. This goes well beyond 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 description is appropriately sized for a complex 20-parameter tool. It is well-structured with clear sections: purpose, Args, Returns, Examples, Error Handling, and When-not-to-use. Every section serves a purpose and the key information is 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?

Given the high complexity (20 params, no output schema), the description is remarkably complete. It explains return values, error handling, defaults, and use cases. It even addresses edge cases like all-day events and cross-client reminder limitations. The only minor gap is not discussing the openWorldHint annotation, but that is not essential for tool invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 20 parameters. The description adds a helpful Args summary and examples that map natural language to fields (e.g., 'third Tuesday' -> recurring_rule). While not fundamentally new, the examples and consolidated overview add value above the schema alone.

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 'Creates a new event on an AddEvent calendar' with a specific verb and resource. This clearly distinguishes it from sibling tools like addevent_update_event, addevent_delete_event, and addevent_search_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 explicit when-to-use guidance through examples and an explicit 'Don't use when: the event already exists (use addevent_update_event instead).' This directly tells the agent when to avoid this tool and names the alternative.

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 critical behavioral traits: default silent creation when notify is omitted, the uniqueness requirement for email per event, and error conditions (400 for duplicate email or missing rsvp_form_data fields). It also states the return value clearly. These details add substantial value over the minimal annotation set and do not contradict any hint.

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 with clear sections (overview, Args, Returns, Examples, Error Handling) and uses bullet points for parameters. It is thorough but not verbose; every sentence contributes either context, example, or error information. This makes it easy to scan and process.

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 5 parameters, a nested object, and no output schema, this description covers all necessary aspects: purpose, prerequisites, every parameter, return value, error handling, and usage examples. It is fully actionable for an agent to invoke the tool correctly and understand the outcome.

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 parameters. The description adds practical context, such as the 'backfilling attendees from another system' use case for omitting notify and the note that the default RSVP form requires a 'name' field. This enriches parameter understanding beyond the raw schema definitions, though most semantic weight is carried by 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 'Registers an RSVP attendee on an event,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like search_rsvps, get_rsvp, update_rsvp, and delete_rsvp. It further clarifies scope by stating it only works on events created with rsvp_enabled: true, removing any ambiguity about applicability.

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 when-to-use and when-not-to-use guidance: 'Don't use when: the event doesn't have RSVP enabled (check with addevent_get_event first).' It also gives concrete examples of appropriate usage, such as adding an attendee or importing signups silently, making it easy for an agent to decide when to invoke this tool.

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 beyond the destructiveHint annotation by disclosing permanence ('cannot be undone'), the cascading effect on events, and specific error handling (404). This adds valuable operational context.

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-organized with clear sections for Args, Returns, Examples, and Error Handling. It is concise but the Returns line ('A confirmation message') adds little value and the Args section duplicates schema 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?

For a simple 1-parameter delete tool without an output schema, the description covers the essential context: purpose, permanence, cascading effects, return type, error behavior, and a pre-check recommendation. It is sufficiently 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?

The input schema already provides 100% coverage and a detailed description for calendar_id. The description's Args section merely restates the parameter with less detail, adding no new meaning.

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 'Permanently deletes a calendar' with a specific verb and resource, and further clarifies that it affects events on the calendar. This distinguishes it from related tools like addevent_delete_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 example suggests calling addevent_search_events first to check events, providing practical guidance. However, it doesn't explicitly state when not to use this tool or name alternatives for calendar deletion.

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 beyond the annotations by emphasizing the permanence ('This cannot be undone'), detailing error handling for non-existent event IDs, and stating the return value. These are meaningful behavioral traits that are not fully captured by the destructiveHint and idempotentHint annotations, providing valuable context for the agent.

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 and well-structured with sections for Args, Returns, Examples, and Error Handling. It front-loads the primary purpose and every sentence contributes useful information, avoiding redundancy or unnecessary length.

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

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

For a simple single-parameter delete tool, the description covers all necessary aspects: purpose, parameter, return value, error handling, and usage examples. The annotations already provide safety and idempotency hints, and the description fills in the remaining behavioral details, making it complete for safe and correct invocation.

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

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

The input schema already provides full coverage of the only parameter (event_id) with a clear description. The description's Args section repeats similar information without adding new semantic details. The example given in the description is more about usage guidance than parameter semantics, so it does not meaningfully enhance understanding of the parameter itself.

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 'Permanently deletes an event' with a specific verb and resource, and distinguishes itself from sibling tools like addevent_delete_calendar and addevent_delete_rsvp by targeting events. The title and description align, leaving no ambiguity about the tool's function.

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 a concrete example ('Delete the duplicate event we just created') and an explicit 'Don't use when' exclusion for hiding events, noting there is no archive/unpublish option. This gives clear guidance on when to use the tool and when to avoid it, though it does not name an alternative sibling tool.

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 readOnlyHint=false. The description adds 'cannot be undone' and specific error handling (404 with 'Not found'), giving additional context about permanence and failure behavior beyond the hints.

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 a clear front-loaded first sentence, followed by useful structured sections for args, returns, and errors. Every sentence adds value 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?

For a simple one-parameter delete tool, the description fully covers purpose, return value, and error handling. Annotations cover destructive and idempotent behavior, so no gaps remain for the agent.

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%, and both the schema and description describe attendee_id as required and permanent. The description adds minimal meaning beyond the schema—it just restates the parameter's purpose without new details.

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 'Permanently deletes an RSVP attendee' with a specific verb and resource. This clearly distinguishes it from sibling tools like update_rsvp or get_rsvp, and the destructive nature is explicit.

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 delete semantics, but the description does not explicitly state when to use this over alternatives (e.g., update_rsvp for changing attendee status). No exclusions or alternative recommendations are provided.

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 read-only, idempotent, non-destructive behavior. The description adds valuable context by specifying the 404 error response and the JSON return format, without contradicting 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?

Four short sections (purpose, args, returns, error handling) with no redundancy; every line adds 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?

For a simple get-by-ID tool with a single parameter, the description covers the return format and error behavior. Combined with rich annotations, it is fully complete without an output 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 coverage is 100% and the description merely paraphrases the schema's parameter description. No additional semantic meaning is provided beyond marking it required (already in 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 clearly states the verb 'retrieves' and the specific resource 'single calendar by its calendar_id', distinguishing it from sibling search/update/delete tools.

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

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

It provides clear context for when to use (when you have a calendar_id and need a single calendar), but does not explicitly name alternatives or exclusions, 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?

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds return format ('full event object as JSON') and a specific error-handling behavior ('Error: Not found...' on 404). This meaningfully extends the annotation context, though it does not cover potential auth or rate-limit 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 with clear sections (Args, Returns, Examples, Error Handling) and every sentence contributes new information. It is brief yet comprehensive, with the core purpose stated in the first sentence for immediate recognition.

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 single-entity retrieval tool with one parameter and no output schema, this description covers all essential aspects: what it retrieves, how to pass the parameter, what the return value looks like, and error behavior. It also points to the appropriate sibling for cases where the ID is unknown, fully equipping the agent to act 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?

The input schema already fully describes event_id with 100% coverage, so the baseline is 3. The description adds value by giving a concrete example mapping user language ('Show me the details for event evt_abc123') to the parameter value, which helps the agent extract the argument from natural language.

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 'Retrieves a single event by its event_id', which clearly states the exact verb, resource, and identifier used. It also distinguishes itself from addevent_search_events by explicitly noting that this tool requires an event_id, making the purpose unmistakably specific.

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: 'Don't use when: you don't have the event_id yet (use addevent_search_events first)'. This names the alternative tool and tells the agent exactly when to avoid this tool, going beyond mere 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 already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context by stating the return format ('full RSVP attendee object as JSON') and the 404 error when not found, going beyond what annotations 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 concise and well-structured into purpose, args, returns, and error handling sections. Each section is brief and earns its place 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?

For a simple getter with one parameter, the description covers purpose, parameter, return format, and error handling. Given the annotations and absence of an output schema, this is complete 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 schema provides 100% coverage for attendee_id, describing it as 'The ID of the RSVP attendee to retrieve.' The description's Args section essentially repeats this info, adding no new details about format, uniqueness, or usage 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 clearly states it retrieves a single RSVP attendee by attendee_id, using a specific verb and resource. This distinguishes it from sibling tools like search_rsvps (which searches) and create/update/delete operations.

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 clearly implies this tool is used when you have an attendee_id and need the full attendee object. It does not explicitly mention alternatives like search_rsvps or when not to use, but the context is clear enough for a simple getter.

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 destructiveHint false. The description adds useful behavioral context by specifying the return shape ({ timezones, count }) and the filtering behavior, plus a concrete example. It does not go into edge cases or error behavior, but for a simple read-only lookup this is sufficient.

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: a one-sentence purpose, an Args section, a Returns section, and two useful examples. Every part earns its place without redundancy or fluff.

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 tool with one optional parameter and no output schema, the description is complete. It includes the return shape, usage context, and a practical example, while annotations cover the safety profile. No additional information is needed for correct invocation.

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

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

Schema coverage is 100%, and the schema already documents the 'search' parameter as an optional case-insensitive filter. The description reinforces this with an example, but adds little beyond what the schema already provides, so the 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 uses a specific verb ('Lists') and identifies the resource as 'timezone values supported by AddEvent's timezone field on events and calendars.' It clearly distinguishes this from sibling tools, which operate on events, calendars, and RSVPs rather than timezone metadata.

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 to use this tool: before addevent_create_event or addevent_create_calendar if you're unsure of the exact timezone string. This provides clear contextual guidance and names the relevant alternative workflows.

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 signal read-only and idempotent behavior; the description adds valuable context: empty result semantics ('An empty "calendars" array means no matches, not an error'), error handling for invalid sort combinations, and pagination behavior. This exceeds the annotation baseline.

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?

Well-structured with clear sections (intro, Args, Returns, Examples, Error Handling). Each section is concise and serves a purpose; no redundant fluff. Front-loaded with the primary purpose and non-mutation guarantee.

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 provides the return shape, pagination details, empty-result semantics, and error handling. For a 5-parameter tool with rich sibling context, this is fully self-contained and 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 covers all parameters with descriptions (100%), so baseline is 3. The description adds value by explaining the sort_order dependency (error for invalid combination), showing how calendar_ids is used in an example, and clarifying pagination defaults. This warrants 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 clearly states the tool 'Searches calendars you've previously created' with an explicit exclusion 'Does NOT create or modify calendars.' This distinguishes it from mutation tools and other search/list tools 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?

Provides clear use cases via examples ('What calendars do we have set up?' and 'Find the calendar_id for the WREIA calendar') and explicitly notes it is not for creating/modifying. However, it does not directly contrast with get_calendar, so differentiation from a single-calendar fetch is implied rather than explicit.

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, idempotentHint=true, and destructiveHint=false. The description reinforces this with 'Does NOT create or modify events' and adds valuable runtime behavior: return shape, empty array meaning, error handling for invalid filter combinations, and pagination semantics. This goes well beyond 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 description is well-structured into Args, Returns, Examples, and Error Handling sections. It is longer than necessary given the schema coverage, but every section earns its place for providing a comprehensive overview, especially without an output schema. It is not overly verbose and remains easy to scan.

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

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

For a tool with 11 optional parameters and no output schema, the description covers the full picture: parameter semantics (via schema and description), return format, example use cases, error behavior, and when to use an alternative. It even clarifies that an empty events array is not an error, which is important for callers.

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 mostly restates schema descriptions (e.g., datetime_min matches events ending on/after, custom_data_key/value must be paired, page_size range). It adds minor examples but no substantial new parameter semantics beyond what the schema already 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 clearly states 'Searches events you've previously created. Does NOT create or modify events.' This specifies the action (search), the resource (previously created events), and explicitly distinguishes it from mutation tools like create/update/delete. It also contrasts with addevent_get_event by noting the alternative is cheaper when an event_id is already known.

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 usage guidance with concrete examples: 'What events do we have next month?' maps to setting datetime_min/max, and 'Find the Main Monthly event' maps to search. It also gives a direct exclusion: 'Don't use when: you already have the event_id (use addevent_get_event, it's cheaper).' This clearly tells when to use this tool versus 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 read-only, idempotent, non-destructive behavior, but the description adds substantial behavioral context beyond that: return shape, pagination semantics, empty 'rsvps' array meaning 'no matches, not an error', and explicit statement that it works only on previously created RSVPs. This is rich supplementary transparency.

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: a one-sentence purpose, a concise Args list, Returns object, examples, and an explicit anti-use case. Every section earns its place, and the formatting makes it easy to scan. Despite its length, it avoids redundancy and is optimally organized for an AI agent.

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 7 parameters, no output schema, and a moderately complex search tool, the description is complete: it documents all parameters with meaning, specifies the full return structure, clarifies edge-case behavior (empty results), and provides usage examples. There are no significant 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?

The input schema already describes all 7 parameters (100% coverage), so the baseline is 3. The description adds value by grouping related parameters (calendar_ids/event_ids), clarifying the meaning of attending ('Filter by response'), and giving real-world examples that illustrate parameter combinations. This exceeds baseline but does not need to fully compensate for 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 opens with a specific verb and resource: 'Searches RSVP attendees you've previously created.' It also explicitly distinguishes itself from mutation tools ('Does NOT create or modify RSVPs') and from the single-record sibling addevent_get_rsvp, making the scope 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?

Usage guidance is explicit and actionable. The description includes a direct 'Don't use when' section pointing to addevent_get_rsvp as cheaper when attendee_id is already known, and provides concrete examples showing when to use filters like attending and event_ids. This exceeds simple context and gives clear decision rules.

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 annotations (idempotent, non-destructive), the description adds specific error behavior (404 when calendar_id not found), return format (updated calendar object as JSON), and partial-update behavior. This gives the agent practical expectations without contradicting 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 description is compact and well-organized into Summary, Args, Returns, and Error Handling sections. Every sentence adds operational value, with no redundancy or filler.

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 10-parameter mutation tool with fully described schema and good annotations, the description supplies the missing context: partial update behavior, return type, and error handling. It is complete enough for an agent to invoke the tool correctly without further clarification.

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 provides 100% field-level descriptions, so the baseline is 3. The description adds meta-semantics: only provided fields are changed, calendar_id identifies the target, and other fields map to addevent_create_calendar. This is useful guidance 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 clearly states the tool 'Updates an existing calendar', using a specific verb and resource. It distinguishes itself from sibling tools like addevent_create_calendar and addevent_delete_calendar by emphasizing 'existing' and partial-update semantics.

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

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

It provides clear usage context: calendar_id is required and only provided fields are changed, so callers should include only what's changing. It doesn't explicitly name alternatives, but the 'existing calendar' wording and sibling tools make the intended use evident.

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 non-read-only, idempotent, non-destructive behavior. The description adds valuable context beyond that: partial-update semantics, 404/400 error handling, and the note that validation failures return an error. It does not contradict 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 description is well-structured with clear sections (Args, Returns, Examples, Error Handling, Don't use when). It front-loads the core purpose and each sentence earns its place, providing useful examples and error details 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?

For a tool with 21 parameters, the description covers the essential context: partial updates, error handling, return type (updated event object as JSON), and usage examples. It could have elaborated on edge cases (e.g., mutually exclusive fields), but the schema handles those details, and no output schema exists, so the return-type statement is 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?

Schema description coverage is 100%, so every parameter already has detailed meaning. The description adds a few example parameter uses (datetime_start, location) and clarifies that event_id is required while all others are optional, but it largely relies on the schema. Baseline of 3 is appropriate.

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

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

The description opens with 'Updates an existing event'—a specific verb + resource. It also clarifies partial-update semantics ('Only the fields you provide are changed; everything else is left as-is'), which distinguishes it from a full replace or create, and explicitly contrasts with addevent_create_event in the 'Don't use when' note.

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 when to use the tool ('Only the fields you provide are changed... include only what's changing') and when not to ('Don't use when: the event doesn't exist yet'), naming the alternative (addevent_create_event). The examples (moving a meeting, changing location) further clarify common usage scenarios.

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 (non-read-only, non-destructive, idempotent), the description adds valuable behavioral details: partial updates preserve unspecified fields, returns the updated object as JSON, and returns a 404 error for missing attendee_id. 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 well-structured with clear sections (Args, Returns, Examples, Error Handling) and a concise opening sentence. No superfluous content; each section 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?

Given the 4-parameter schema with full description and no output schema, the description covers the necessary return format and error behavior. The example and partial-update semantics make the tool fully understandable for an agent.

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% and each parameter is described, so baseline is 3. The description adds value by explicitly framing optional parameters as 'include only what's changing' and by providing an example mapping natural language to attendee_id and attending values (not-going).

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 it 'Updates an existing RSVP attendee' with a specific verb and resource. The title and content distinguish it from sibling tools like create_rsvp, delete_rsvp, and update_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 explains the partial-update behavior ('Only the fields you provide are changed') and gives a concrete example. It does not explicitly state when to prefer this over alternatives, but the RSVP-specific scope is clear from context.

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