TimeTree MCP Server

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses audience ("comments are visible to everyone in the calendar") and notification behavior (default silent, no push). It would be stronger if it warned about duplicate posting given idempotentHint=false, or mentioned any rate/permission limits.

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 short sentences, front-loaded with the action and return value, then side effects, then sibling routing. No filler and no repetition.

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?

Output schema exists so return details need not be spelled out, and all four parameters are schema-documented. The description covers action, side effect, identifier sourcing, and alternatives — everything an agent needs 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?

Schema coverage is 100%, so baseline is 3; the description still adds value by telling the agent where event_uuid comes from (get_events) and reinforcing the silent-no-notification default. calendar_id and content semantics are left to 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?

States a specific verb and resource ("Post a comment on an event") plus the return shape ("return it with its id"). It also explicitly names the sibling tools it is not (update_event, update_event_comment, delete_event_comment), so an agent can disambiguate without opening schemas.

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

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

Gives explicit routing: use get_events to obtain event_uuid, use update_event for the event's own note, and use update_event_comment/delete_event_comment for later edits or removal. When-to-use and when-to-use-something-else are both covered.

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

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

Goes well beyond the annotations by disclosing which fields carry over (title, note, location, URL, label, reminders, checklist), that recurrence is not copied so the result is a single event, that attendees and virtual attendees only carry within the same calendar, and that the original is unchanged. This is exactly the kind of edge-case detail an agent needs for a non-idempotent, open-world write tool.

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

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

Three sentences, front-loaded with the core action, followed by copied-field semantics and edge cases. No filler and no repetition of the name or title.

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?

An output schema exists, so the description needn't explain the return shape, and it doesn't. It covers the behaviors that matter for correct invocation – recurrence dropping, attendee scoping, source immutability – leaving nothing an agent would need to guess.

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 parameter meaning is already documented. The description reinforces the calendar_id vs target_calendar_id distinction ('optionally into another calendar') and implies default behaviors, but adds no syntax or constraints beyond the schema baseline.

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

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

States a specific verb and resource ('Copy an existing event to a new date and time, optionally into another calendar') plus the return value. It is clearly distinguishable from create_event and update_event siblings because it copies existing state rather than creating from scratch or mutating in place.

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 scenario (duplicating an event to a new date/time, possibly into another calendar) is stated clearly, giving a strong implied when-to-use. It does not name alternatives like create_event or state exclusions, which keeps it just below 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 declare idempotentHint=false and destructiveHint=false; the description makes the non-idempotency actionable by warning that after a timeout the calendar may already exist and list_calendars should be checked first. It also confirms no side effects on existing data and that an ID is returned, adding real value beyond the annotation flags.

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 sentences, front-loaded with the core action, then exclusions, then constraints, then failure handling. Only the name-length clause is partly redundant with the schema's minLength/maxLength, a minor wasted clause.

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?

Output schema exists so return values need no prose, and annotations cover the safety profile; the description still supplies the retry/duplicate risk and scope limits an agent needs. The remaining hole is the semantics of the `purpose` enum, which nothing documents.

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 0%, so the description must carry parameter meaning. It restates constraints already enforced structurally (name 1-20 characters, purpose required) but never explains what `purpose` affects, whether it is user-visible, or whether it can be changed later. Useful reinforcement, but not compensating for the coverage gap.

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 ("Create a new, empty calendar owned by you") plus the outcome ("return its ID"). The scope exclusions ("does not invite anyone or change existing calendars") make it unambiguous against siblings like create_event or get_calendar_members.

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

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

Clear context for invocation and explicit negative scope (no invitations, no mutation of existing calendars), plus a concrete recovery path: check list_calendars before retrying after a timeout. It stops short of naming which sibling to use for follow-up steps such as adding members or events, so not a full when/when-not/alternatives mapping.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower, yet the description adds real side-effect context: other calendar members will see the event and attendees may be notified. It does not address the non-idempotent nature (repeated calls create duplicate events) or required permissions, which would have pushed this to a 5.

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

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

The main action is front-loaded in the first sentence, followed by feature enumeration and then sibling routing. Three sentences, no filler; the only mild redundancy is re-listing features that the schema already exposes.

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

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

For an 18-parameter mutation tool it is well covered: annotations supply the safety profile, an output schema exists (so return values needn't be explained, though the uuid is still mentioned), and schema coverage is complete. The remaining gap is that non-idempotency and permission requirements are left unstated.

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

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

Schema description coverage is 100%, so every one of the 18 parameters is documented in the schema and the baseline is 3. The description adds some meaning beyond it by explaining that attendees are user IDs sourced from get_calendar_members and by naming the virtual-member and RRULE features, but it doesn't clarify formats for timestamps, timezones, or label IDs.

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 ("Create an event in a TimeTree calendar") and adds the return artifact ("return it with its uuid"). It enumerates supported feature axes (all-day, reminders, RRULE, attendees, virtual members, checklist) and explicitly separates itself from create_memo and copy_event, so the agent can distinguish it from siblings 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?

It gives explicit routing rules with conditions: memos without a date go to create_memo, duplicating an existing event goes to copy_event. It also points at get_calendar_members as the source of attendee IDs. What's missing is guidance on when NOT to use it in favor of update_event/create_calendar, but the create-vs-update distinction is largely self-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?

Adds real context beyond annotations: the created memo is returned with its uuid, and 'Other calendar members can see it' discloses a visibility side effect that annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) do not convey. It stops short of naming required permissions or whether attendee notification occurs, which is the remaining gap.

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 short sentences, front-loaded with the action and its return value, then the definition, then the routing guidance. No filler and nothing buried.

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 creation tool with 9 params, full schema coverage, and an output schema, the description supplies what structured fields cannot: the concept boundary versus events, the visibility consequence, and the follow-up tool. Return-value details are correctly left to the 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 description coverage is 100%, so the schema already explains calendar_id, date defaults, label_id values, and checklist structure. The description's mention of 'note, list, or checklist' loosely maps to the note/checklist fields but adds no syntax or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Create a memo in a calendar') and immediately defines the resource by contrast: 'a note, list, or checklist that is not a scheduled event, such as a shopping list.' That definition is what separates it from create_event, so an agent can pick the right tool without inspecting either schema.

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

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

Explicitly routes both alternatives: 'Use create_event for something that happens at a time' and 'Change it later with update_memo.' This covers when to use it, when not to, and which sibling handles the adjacent cases.

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

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

Annotations already cover the safety profile (non-destructive, open-world, non-idempotent). The description adds real behavioral context beyond them: the member is visible to everyone in the calendar, and there's a hard cap of 10 per calendar. It stops short of auth requirements, but the visibility and quota disclosures are genuinely useful.

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

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

Three tightly-packed sentences, front-loaded with what the tool does and the concept, then visibility, then the quota, then the return value. Every sentence earns its place with no waste.

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?

Output schema exists and the description still briefly notes the returned id/uuid. Combined with full schema coverage and annotations, an agent has everything needed to call this correctly — the concept, constraints, and side effects are all present.

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 six parameters including the type enum and birthday format. The description adds conceptual context (linking to virtual_user_attendees) but no parameter-level syntax beyond what the schema provides — baseline 3.

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 ('Add a virtual member to a calendar') and immediately explains the concept — someone without a TimeTree account like a child, pet, or car — which clearly distinguishes it from update_virtual_member and delete_virtual_member 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?

Explains the context for use (assigning events via virtual_user_attendees) and states the key constraint (max 10 per calendar). It doesn't explicitly route against an alternative, but for a create operation the context is clear enough that an agent knows when to reach for 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 already declare destructiveHint=true and idempotentHint=true, so the description's 'Cannot be undone' is reinforcing rather than new. The genuinely additive piece is the series-wide deletion scope ('including every occurrence of a recurring event'), which an agent would not infer from annotations alone. It does not mention permissions or whether the event must belong to the given calendar.

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 short sentences, front-loaded with the destructive scope, then irreversibility, then the alternatives. No wasted text and ordering prioritizes what matters most.

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?

Output schema exists and parameters are fully documented, so the description only needs to convey scope and alternatives, which it does well. The only real gap is any precondition tying event_uuid to calendar_id for a destructive call.

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 parameters carry descriptions pointing to get_events and list_calendars as sources. The description adds no syntax or constraint detail beyond that, so baseline 3 applies.

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

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

Specific verb plus resource ('Delete an event') with an explicit scope qualifier: every occurrence of a recurring event. It also names the two sibling tools it must not be confused with (delete_event_occurrence, delete_memo), so an agent can distinguish it without opening schemas.

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?

Explicit routing: single-occurrence or following-occurrence deletion goes to delete_event_occurrence, and memo deletion goes to delete_memo. The implied default (whole event/series) is unambiguous by contrast.

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 already mark the tool as destructive and non-read-only, but the description adds important context not present there: the deletion cannot be undone and TimeTree restricts deletion to the comment's author. It could mention what happens on repeated deletion or permission failures, but the added behavioral context is substantial.

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 short sentences, each with a clear purpose: the action, the destructive/permission behavior, and where to get the key parameter. Nothing is wasted.

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

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

The tool has annotations covering destructiveness and an output schema, so the description does not need to explain return values. It completes the picture with irreversibility and author-only permission, though it does not describe failure behavior when the caller is not the author.

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 all three parameters, including that comment_id comes from list_event_comments. The description repeats this provenance for comment_id but adds no syntax or format details 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 states a specific verb and resource: deleting an event comment. It clearly distinguishes this from sibling deletion tools like delete_event and delete_memo by naming the exact resource type.

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 prerequisites: the comment must be deleted by its author, and the comment_id should come from list_event_comments. It does not explicitly name alternatives, but the usage context is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context beyond those annotations: the deletion cannot be undone and the special case where starting at the first occurrence removes the entire series. It does not discuss side effects such as attendee notifications, but given the annotation coverage this is a strong disclosure.

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 tightly written sentences, front-loaded with the operation and scope, followed by the sibling alternative and required prerequisites. Every sentence carries actionable 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 destructive recurring-event deletion tool, the description covers purpose, scope choices, sibling alternative, identifier sourcing, edge-case behavior, and irreversibility. An output schema exists, so return values need not be described.

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 nevertheless adds practical retrieval semantics: event_uuid and occurrence_start_at should come from get_events with start_before set, and it clarifies the scope distinction between deleting one occurrence versus that occurrence and all later ones.

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 (delete) and resource (one occurrence of a recurring event) and explicitly distinguishes the scope from sibling delete_event, which deletes the whole series. An agent can tell exactly which tool to choose without opening schemas.

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

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

It names the alternative (delete_event for the whole series), explains how to obtain the required identifiers via get_events with start_before, and warns that deleting from the first occurrence onward deletes the whole series. These are explicit when-to-use and prerequisite instructions.

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 already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description reinforces permanence with 'Cannot be undone' and adds a useful behavioral boundary by noting the tool fails for regular events. It does not cover permissions or error details, but the failure-mode guidance is valuable context 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?

Four short sentences, each earning its place: operation, irreversibility, UUID source, and failure boundary. The core action and constraints are front-loaded with no wasted prose.

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 rich annotations, full schema descriptions, and presence of an output schema, the description supplies everything an agent needs: what is deleted, that it is permanent, where to get the memo UUID, and when to choose delete_event instead. No material invocation detail 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 both calendar_id and memo_uuid are already documented in the input schema. The description adds only a sourcing hint for memo_uuid ('from list_memos'); it does not elaborate on the calendar_id parameter beyond what the schema already states. Baseline 3 is appropriate when the schema carries the parameter documentation.

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: 'Delete a memo.' It then explicitly distinguishes this tool from delete_event by warning that it 'Fails for regular events (use delete_event).' An agent can identify the exact operation and sibling boundary without opening any schema.

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

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

It tells the agent where to source the required UUID ('Get memo_uuid from list_memos') and names the competing alternative for regular events ('use delete_event'). This is explicit when-to-use and when-not-to-use guidance, not merely implied 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description reinforces this with 'Cannot be undone' and adds the useful pointer that the identifier comes from a lookup call, but it says nothing about required permissions, side effects on events already created by that member, or error behavior.

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

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

Three short sentences, no filler, with the action and irreversibility front-loaded before the identifier lookup hint. Every sentence carries information the agent needs.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile for this two-parameter mutation. The only gap is the absence of any note on downstream effects (whether existing events survive the removal), which matters for a destructive delete.

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 earns extra credit by warning 'the uuid, not the id' — a real disambiguation between two similarly named identifiers that the schema descriptions alone do not flag.

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 ('Remove a virtual member from a calendar') with unambiguous scope. It is clearly distinct from the generic delete_event and from its siblings update_virtual_member and create_virtual_member, without the agent needing to open any schema.

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

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

Names the prerequisite step explicitly: fetch the identifier from get_calendar_virtual_members before calling. It does not address when to prefer update_virtual_member or how to handle members still assigned to events, so it falls short of explicit exclusions/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 declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds useful behavior beyond that by disclosing the fixed set of 10 labels and the fields returned (ID, name, color, order). It does not discuss ordering semantics or whether labels can be missing, but the added context is real value, not repetition.

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?

Two tight sentences with zero waste. The core purpose is front-loaded and the downstream usage hint follows, so an agent can stop reading after the first clause if it only needs to know what the tool does.

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

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

For a single-parameter, read-only listing tool with an output schema and clear annotations, the description covers purpose, return contents, downstream use of the IDs, and the mutation alternative. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single calendar_id parameter is fully documented in the schema, including the note that it comes from list_calendars. The description adds nothing about the parameter itself, so the baseline 3 applies; its added meaning ('use the IDs as label_id') concerns the return values, not the input.

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 ('List the 10 color labels of a calendar') and enumerates exactly what comes back: IDs, names, colors, and order. It is clearly distinguished from the sibling mutation tool update_calendar_labels, so an agent can pick it 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?

Explicitly directs the agent to feed the returned IDs in as label_id when creating or filtering events, and names update_calendar_labels as the tool for renaming or recoloring. It gives the alternative for the mutation path clearly, though it does not state a 'when not to call this' condition.

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 openWorldHint=true, so safety is covered. The description adds a meaningful behavioral boundary beyond that: it only returns account-holding members and excludes virtual members, with an explicit redirect for the excluded case. It stops short of describing ordering, pagination, or the include_deactivated default behavior, hence not a 5.

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

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

Two compact sentences, front-loaded with the purpose before the routing guidance. The 'with their user IDs, names, and roles' clause slightly overlaps what the output schema already provides, but it is short and gives the agent a fast read on result shape.

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 an output schema exists and parameter coverage is complete, the description needs only to convey purpose, scope, and the sibling boundary, all of which it does. An agent has everything required to call this 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?

Schema description coverage is 100%, so both calendar_id and include_deactivated are fully documented in the schema. The description references user_id only in its role as a returned field, not as a parameter, and adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('List the people who share a calendar') plus the scope constraint (members with TimeTree accounts) and the return shape (user IDs, names, roles). It immediately distinguishes itself from get_calendar_virtual_members, so an agent can route correctly without opening either schema.

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

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

Gives explicit usage instructions: 'Use user_id for event attendees,' and names the alternative tool with the exact condition that selects it ('For members without an account, such as children or pets, use get_calendar_virtual_members'). This is a textbook when/when-not/alternative breakdown.

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 openWorldHint=true, so the safety profile is covered; the description adds that the call is scoped to a single calendar and clarifies the meaning of the two returned identifiers and what each is good for. It does not discuss pagination, how deactivated members appear, or the open-world implication of account-less entities, leaving modest gaps against 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?

Three tight sentences, front-loaded with purpose and the definition, then return-value roles, then the alternative tool. Nothing is repeated from the schema or annotations and no sentence is 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?

With an output schema present, the description needn't restate return structure and instead explains what the returned ids are for, plus a clear sibling routing rule and a definition of the resource. For a two-parameter read tool this leaves nothing an agent needs 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% with per-parameter descriptions (calendar_id sourced from list_calendars, include_deactivated with its default), so the structured data already carries the meaning. The description adds no parameter-level detail beyond implying calendar scoping; baseline 3 applies when the schema does the heavy lifting.

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

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

Specific verb+resource ('List the virtual members of a calendar') plus a plain-language definition of what a virtual member is (a person or thing without a TimeTree account, e.g. child, pet, car). It explicitly contrasts with the account-holder equivalent and names the sibling that handles those, so the agent can distinguish the two without opening either schema.

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

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

Names the alternative explicitly ('For members with accounts use get_calendar_members') and the condition that selects it, which is the exact routing decision an agent faces between this tool and its sibling. It also signals downstream use ('id for virtual_user_attendees on events', 'uuid to update or delete the member'), which tells the agent why it would call this first.

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 and openWorldHint, so safety and scope are covered structurally. The description adds that the result is an ID plus a name, which is useful, but says nothing further about availability, auth requirements, or failure modes. Adequate but not rich 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?

Two sentences, front-loaded with the return values, then the actionable usage guidance. Every clause earns its place with no 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?

A no-parameter identity lookup with an output schema and read-only annotations needs only its return values and intended use explained, and the description does exactly that. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The schema is empty and fully covered, and the description correctly describes only the return payload rather than implying any input it would need.

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

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

Specific verb+resource: returns the signed-in TimeTree user's user ID and name. It is clearly distinct from lookalikes such as get_calendar_members, which return other users, so an agent can route correctly 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 explicit use cases—finding "me" among calendar members, event attendees, comment authors, and activity—and names get_calendar_members as the related call. It gives clear context but does not state any when-not-to-use condition, keeping it just 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?

The description adds substantial behavior beyond the annotations: it returns image content directly rather than saving a file, supports JPEG/PNG/GIF/WebP up to 5 MiB, includes free-account images, and explicitly excludes premium event file attachments. This gives the agent a clear operational profile.

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 compact sentences, front-loads what the tool does, and follows with parameter sourcing, return behavior, supported formats, and exclusions. Every sentence contributes relevant information without repetition.

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 full schema coverage, read-only annotations, an output schema, and sibling comment tools, the description covers purpose, parameter sourcing, direct return behavior, format constraints, and an important unsupported case. Nothing needed 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 input schema already documents all four parameters, including that comment_id and image_index come from list_event_comments. The description reinforces those sources but does not add syntax or constraints 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 states a specific verb and resource: view one image attached to an event comment. It also scopes the tool by noting free-account images are included while premium event file attachments are not, which clearly distinguishes this from related comment-listing 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 tells the agent where to obtain the required comment_id and image_index via list_event_comments, and it names an explicit exclusion: premium event file attachments are not supported. It does not offer alternative tools for unsupported attachments, so it falls 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 only cover read-only and open-world safety; the description adds genuinely non-obvious behavior: it reads every page then filters, limit applies after sorting, memos are included by default, and recurring events expand when start_before is set. It also warns that occurrences share the series uuid, so update_event mutates the whole series and update_event_occurrence/delete_event_occurrence must be used for one occurrence.

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

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

Front-loads purpose and the sibling routing, then layers behavioral notes efficiently. It is dense rather than padded, though the recurring/update-series warning is slightly beyond the immediate calling decision.

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 an output schema present, return values need not be explained. The description still covers pagination, filter/sort/limit order, default memo inclusion, and recurring expansion, which is everything an agent needs to call it correctly on a complex calendar.

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 earns a step above by clarifying ordering semantics (limit applied after filtering/sorting), the include_memos default, and the interaction between start_before and expand_recurring, though these largely echo the schema text.

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 ('Find events in a calendar') plus the filter dimensions (start time range, keyword, label) and sort order. It explicitly distinguishes itself from get_updated_events and get_recent_activity, so an agent can select it without opening the schema.

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

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

Gives the exact question this tool answers ("what is on my schedule") and routes the alternative cases to get_updated_events and get_recent_activity for "what changed". Also notes list_memos as the memos-only alternative, leaving no ambiguity about when to pick a sibling.

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 openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the 5-country cap, the 2-year range cap, the date sort order, and what day_off means in the response. It does not mention rate limits or behavior when a country has no data, so it falls short of a 5.

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

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

Three short sentences, all front-loaded: capability and limits first, the day_off note second, sibling disambiguation last. Every sentence carries non-redundant 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?

An output schema exists, so return values need not be explained, yet the description still clarifies the key output field (day_off). Combined with annotations and full schema coverage, an agent has everything needed to call and interpret 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?

Schema coverage is 100%, so baseline is 3, but the description adds the 2-year date-range constraint that does not appear in the schema and clarifies the intent of days_off_only via the day_off concept. It does not add format or edge-case detail for country_iso beyond what the schema already documents.

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 (look up) and resource (public holidays and observances), plus hard scope limits: up to 5 countries, up to a 2-year range, sorted by date. It explicitly separates itself from calendar events by naming get_events, so an agent can distinguish it from siblings without opening either schema.

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

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

It gives a direct when-to-use rule (national holidays) and a when-not rule with a named alternative: 'not events in your calendars (use get_events for those)'. The only thing missing is whether days_off_only filtering is preferred in certain cases, which is minor.

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 and open-world, so the description's added value is the retention caveat ('TimeTree keeps only the last few activities per event, so this is a recent feed, not full history') and the 'newest first' ordering — both real behavioral traits an agent cannot infer from structured fields. It stops short of noting rate limits or per-event truncation details, so not a 5.

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

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

Three tight sentences: purpose and scope first, retention caveat second, alternative-tool routing last. No repetition of schema or annotation content, no 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?

With an output schema present, return shape needn't be explained, and the description still names the activity fields. Combined with the retention caveat and sibling routing, an agent has everything needed to select and call this 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?

Schema coverage is 100% and each of the three parameters (limit, since, calendar_id) is already documented there. The description adds no syntax, default, or format guidance beyond the ordering hint, so baseline 3 applies.

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

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

Opens with a specific verb and resource ('See who recently created, changed, or deleted events and memos in a calendar') and then enumerates exactly which change types count. An agent can distinguish it from read/CRUD siblings like get_events and get_updated_events without consulting 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?

Explicitly routes the agent: 'Use get_updated_events for the current content of changed events,' which is the one realistic confusion case. It also implicitly scopes usage to recent-feed questions rather than full-history queries.

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 readOnlyHint annotation, the description discloses two non-obvious behaviors: soft-deleted records are still returned with `deleted: true`, and recurring events are collapsed to one record rather than expanded. That materially changes how an agent interprets results. It stops short of describing ordering or how `limit` interacts with a large sync window, so it is strong but not exhaustive.

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 tight sentences: what it returns, the edge-case behavior, then the routing guidance. No restatement of the name, no filler, 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?

An output schema exists, so return shape need not be explained, and the description covers the two things an agent would otherwise get wrong: deleted records appearing in results and recurring events not being expanded. Combined with 100% schema coverage on the three parameters, nothing needed for a correct call is missing.

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

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

Schema description coverage is 100%, including the timestamp conversion guidance for updated_after, so the schema already carries the parameter burden. The description adds only the conceptual framing of "after a point in time" and nothing about limit or calendar_id semantics. Baseline 3 applies.

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

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

States a specific verb and resource ("List events and memos changed after a point in time") plus the return scope ("with their current content"). It is immediately distinguishable from get_events (schedule lookup) and get_recent_activity (who changed what), so an agent can pick it without opening any schema.

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

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

Explicitly names the use case ("sync or review changes since a time") and routes to two named alternatives with the conditions that select them: get_recent_activity for attribution, get_events for a schedule. That is when-to-use plus when-not-to-use in a single sentence.

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 and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: only *active* calendars are returned (inactive ones are silently omitted) and the member list is exposed. It stops short of noting auth requirements or whether membership is trimmed for large calendars.

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 short sentences, front-loaded with the core action, then the dependency rule, then the practical selection tip. Nothing is redundant with the schema or annotations.

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?

A zero-parameter read tool with an output schema and read-only annotations needs only purpose, sequencing, and a usage tip — all three are present. No return-value documentation is required since the output schema covers it.

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

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

Zero parameters, so the baseline of 4 applies and there is nothing for the description to disambiguate. The description correctly spends no words re-explaining an empty 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?

States a specific verb and resource ("List your active TimeTree calendars") and names exactly what is returned (IDs, names, members). The line "Call this first: every other tool needs a calendar_id from here" cleanly separates it from siblings like get_calendar_members or get_events, which all require an ID this tool supplies.

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

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

Gives an explicit sequencing rule (call this first, all other tools depend on its calendar_id) plus a concrete selection heuristic (match member names when the user names a person, with an example). This is prescriptive when-to-use guidance rather than vague 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context about the returned scope (comments only, excluding change history) and points to the sibling for image retrieval, though it says nothing about pagination, ordering, or result limits.

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 short sentences, front-loaded with the core action and followed by routing guidance; every sentence carries distinct information with no restatement of the title.

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?

An output schema exists and both parameters are documented, so the description needn't spell out return structure; it still adds scoping and sibling routing. Only minor gaps remain, such as ordering or whether results are paginated.

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% for both required parameters, including the note that calendar_id comes from list_calendars. The description's field list describes return values rather than the parameters, so it adds no semantics beyond the schema — baseline 3 is correct.

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 ("List comments") plus the fields returned (ids, author user IDs, image metadata), and explicitly scopes it against get_recent_activity. An agent can distinguish it from siblings 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?

Names two alternatives with the conditions that select them: get_event_comment_image "to view an image" and get_recent_activity "for who changed what," plus an explicit negative ("Only comments are returned, not change history").

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

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

Annotations already cover the read-only and open-world profile, so the description's job is lighter. It adds real value by disclosing the content scope (memos exclude scheduled events) and the overlap/duplication behavior with get_events, which an agent could not infer from annotations. It says nothing about ordering or pagination, but an output schema exists to cover returns.

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 tight sentences, front-loaded with the core purpose and followed by the sibling routing hint and the optional filter. No wasted clauses, though the trailing "Optionally only memos updated after a time" is slightly awkwardly phrased compared to the rest.

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 three-parameter read tool with full schema coverage, annotations, and an output schema, nothing an agent needs in order to call it correctly is missing. Purpose, scope, sibling routing, and the optional filter are all present.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including that calendar_id comes from list_calendars and that updated_after is a Unix millisecond timestamp. The description only echoes the updated_after filter in prose without adding format or default semantics, which is the baseline 3 case.

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

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

Specific verb and resource ("List the memos in a calendar") plus a definition of what a memo is — notes, lists, checklists that are not scheduled events. It explicitly contrasts itself with the sibling get_events, so an agent can distinguish the two without opening either schema.

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

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

It names the alternative (get_events) and the condition selecting it (events, not memos), and notes that get_events also returns memos unless include_memos is false — helpful routing context. It stops short of an explicit "use this tool when you want only memos without event payload", leaving that inference to the agent.

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 non-readOnly, destructive, idempotent and open-world, and the description adds the merge/read-modify-write behavior and the scope of impact on all calendar members. That is meaningful context beyond the structured hints, though it says nothing about failure modes or concurrency.

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 short sentences, front-loaded with the action and scope, followed by merge semantics and ID provenance. Nothing is redundant or padded.

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?

An output schema exists and the schema fully documents parameters, so the description only needs to carry the merge semantics and ID source — both of which it does, alongside annotations covering the safety profile.

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 both calendar_id and the nested label fields are already documented. The description adds only the provenance of label IDs; the merge rule it mentions is already stated in the schema's labels description, so baseline 3 applies.

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

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

States specific verbs (rename/recolor) and the exact resource (calendar labels), plus the audience scope ('for everyone in the calendar'). It is unmistakably distinct from the sibling get_calendar_labels, which it names as the ID source.

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 directs the agent to get_calendar_labels for IDs, which is the key prerequisite, and clarifies that omitting a label leaves it untouched. It does not state explicit when-not conditions, but the usage context is clear.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavioral context: array fields overwrite rather than append, and a recurring event edit applies to every occurrence. It stops short of permissions/auth or rate-limit context, so 4 rather than 5.

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

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

Three tight sentences: action first, mutation semantics second, sibling routing last. Zero filler, and the most decision-relevant content 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?

An output schema exists so return values need no prose, and 19 parameters are fully described in the schema. The description covers the remaining risk areas an agent needs — PATCH-style omission, array replacement, and recurrence scope — making it complete for a destructive mutation 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%, so per-field meaning is already documented; the description's value-add is the cross-cutting semantics that the schema cannot express — omit fields to leave them unchanged, supply arrays to replace wholesale, pass empty arrays to clear. That is meaningful beyond the schema, though it doesn't address the timestamps/timezone pairing specifically.

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?

"Change an event and return the updated event" gives a specific verb plus resource and states the return contract. It also explicitly distinguishes itself from update_event_occurrence and update_memo, so an agent can pick the right tool without opening schemas.

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

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

It states the partial-update rule ("Only provide the fields to change"), the replacement rule for array fields, and names two alternatives with the exact conditions that select them (single-occurrence edits, memos). Nothing about when to use this vs. siblings is left to inference.

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

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

The annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new context by disclosing the author-only restriction and clarifying that the operation fully replaces the text rather than appending. It does not describe failure modes or what happens to prior content beyond replacement, so it falls just short of a 5.

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

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

Three short sentences, each earning its place: what it does, the permission constraint, and the disambiguation from siblings. The core operation 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?

An output schema exists, so return values need no explanation; the description covers the mutation's scope, the auth prerequisite, and the sibling alternatives. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, and the description repeats the comment_id provenance that the schema already documents ("The comment id from list_event_comments"). No additional semantics (e.g., content length limits, formatting) are added, so baseline 3 applies.

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

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

"Replace the text of an existing comment and return it" gives a precise verb, resource, and effect, and the description explicitly distinguishes itself from add_event_comment (create) and list_event_comments (source of the id). An agent can route between the three comment tools without opening a schema.

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

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

It states both the prerequisite ("Get comment_id from list_event_comments") and the alternative for the opposite operation ("use add_event_comment to post a new comment instead"). It also names the permission constraint ("only the comment's author edit it"), which tells the agent when this call will fail.

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 non-idempotent, and the description earns more credit by disclosing the actual side effects: scope "this" spawns a separate parent-linked event, while "this_and_following" truncates the series and starts a new one with a new uuid (or edits the whole series when the occurrence is first). That is exactly the consequence information an agent needs before mutating a recurrence.

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

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

Front-loaded with the core scope distinction and the sibling alternative before the mechanics. It is a dense, somewhat run-on paragraph, but at 18 parameters the length is largely justified and every clause carries operational meaning.

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 recurrence mutation with an output schema and full annotation coverage, the description supplies everything missing: prerequisites, scope semantics, downstream structural effects, and partial-update conventions.

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 defines all 18 parameters. The description still adds real semantics beyond it, notably that start_at relocates the occurrence and preserves its duration unless end_at is supplied, and that recurrences only applies with "this_and_following".

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 plus the exact scope of the change: one occurrence ("only this week") versus that occurrence and all later ones. It explicitly names update_event as the whole-series alternative, so the agent can distinguish it from siblings without opening either schema.

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

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

Gives explicit routing rules: use update_event for the whole series, and obtain the series uuid plus occurrence_start_at from get_events with start_before set. Also instructs to supply only the fields being changed, which prevents accidental overwrites.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: partial-update semantics (only send changed fields) and replace-not-merge behavior for checklists and virtual attendees. It does not mention permissions or auth requirements, which is the remaining gap.

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 short sentences, zero filler, with the core action stated first and the alternative routing (update_event) placed last where it belongs. Every sentence carries information the agent needs.

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?

An output schema exists, so return values need not be explained, and the description still notes the memo is returned. For a 9-parameter mutation tool, the critical semantics — partial update, list replacement, UUID sourcing, and the event/memo distinction — are all present.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a genuine semantic rule absent from the schema: omit unchanged fields because updates are partial. It also reinforces that list parameters replace rather than append, which matters for the two array fields.

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

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

States a specific verb and resource ('Change a memo'), plus the return behavior ('and return it'). It explicitly distinguishes itself from the closest sibling with 'Fails for regular events (use 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?

Gives a clear when-to-use rule ('only provide the fields to change'), a prerequisite for identifying the target ('Get memo_uuid from list_memos'), and an explicit exclusion with a named alternative ('Fails for regular events (use update_event)').

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value by disclosing partial-update semantics and that the updated entity is returned. However, it never explains why the operation is flagged destructive or what data may be lost, leaving the most important behavioral question unanswered.

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 short sentences, each load-bearing: purpose and fields, the partial-update rule, and the prerequisite lookup. Front-loaded and free of 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?

With an output schema present, return values needn't be explained, and the schema fully documents all seven parameters. The only meaningful gap is the unexplained destructive annotation on what reads as a partial update.

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 adds a mapping hint by calling one_word a "short description" and reinforces the uuid-vs-id constraint, but it omits shows_birthday entirely even though birthday is mentioned, so it does not materially expand on 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 names a specific verb ("Change") and resource (a virtual member), and enumerates the mutable fields plus the return behavior. It distinguishes itself from the related read tool by pointing to get_calendar_virtual_members for the uuid, though it never explicitly contrasts with create_virtual_member or delete_virtual_member.

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?

"Only provide the fields to change" tells the agent this is a partial update, and the uuid sourcing instruction (with the "not the id" warning) gives a concrete prerequisite workflow. No explicit exclusions or alternatives beyond the lookup tool are stated, so it falls 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.