Teamup Calendar MCP by usefulapi

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

Goes well beyond the annotations: it spells out the consequence of non-idempotency ('a repeated call creates a second event'), describes the return payload ('the new event and an undo_id'), names the recovery tool and its time limit ('teamup_undo_event_action removes the event again within one hour'), and cites the endpoint. The duplicate-creation and undo-window facts are exactly what an agent would otherwise get wrong.

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

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

Five short sentences, all front-loaded with the operation type and requirements. Nothing is redundant; each clause either sets a precondition, a required input, a behavioral caveat, or a recovery path.

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 15-parameter mutation with no output schema, the description supplies the missing pieces: permission requirement, minimum inputs, non-idempotent consequence, the contents of the reply, and a one-hour undo route. An agent has everything needed to call it safely.

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 93%, so the schema already documents nearly all 15 parameters including formats and defaults. The description only reiterates the three required fields, adding 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 up front ('WRITE: create an event') and lists the three minimum required fields, so the agent knows exactly what the call produces. It does not explicitly name a sibling (e.g. teamup_update_event) to contrast against, but the create-vs-mutate distinction is unambiguous from the verb.

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 concrete precondition ('Needs a calendar key with add or modify permission') and the minimum input set ('at least subcalendar_ids, start and end'), which is clear usage context. It stops short of stating when-not to use it or naming teamup_update_event as the alternative for changing existing events.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context the annotations do not carry: admin permission is required and the plan may cap the number of sub-calendars. The non-idempotency sentence restates the annotation, slightly diluting the added value.

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 WRITE flag and the action, then prerequisites, then the non-idempotency warning, then the endpoint. Nothing is bloated, though the non-idempotency sentence largely duplicates the idempotentHint annotation.

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 low-complexity create tool with full schema coverage and annotations covering safety, the description supplies permissions, plan limits, idempotency behavior, and the endpoint. The only real gap is the return value (e.g. the new sub-calendar's id), which matters since no output schema exists.

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% – all four parameters (name, color, active, overlap) already have inline descriptions, type constraints, and defaults. The description adds no parameter-level meaning such as name uniqueness or color semantics, so the baseline of 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?

The description opens with a specific verb+resource pair ('WRITE: create a sub-calendar') and names the HTTP operation, so its identity is unambiguous. 'Create' versus the sibling teamup_update_subcalendar is self-evidently differentiated, and no schema inspection is needed to tell them apart.

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 preconditions (a calendar key with admin permission, possible plan limits on count), which is useful context for when the call will succeed. However, it never names an alternative or an exclusion, e.g. when to call update_subcalendar or list_subcalendars instead; usage is only implied by the verb.

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 readOnly/destructive/idempotent, but the description adds substantial non-obvious behavior: not retried, undo_id returned, one-hour restorability, permanence afterward, and the exact endpoint semantics for occurrence vs series.

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?

Dense but every clause earns its place: risk flag front-loaded, permission, retry behavior, recovery path, then per-occurrence semantics. 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?

Covers risk, permissions, undo/restore behavior, and recurring-event scoping for a destructive tool with no output schema. Minor gap: no mention of error/refusal behavior when version is set, though the schema documents version.

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. Description nonetheless adds real value: explains the occurrence-id format (123-rid-<unix start>) and clarifies that redit 'single' is the default versus 'all' deleting the whole series.

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 (delete) and resource (event), and distinguishes scope with 'or for a recurring event the chosen occurrences'. Clearly separable from teamup_get_event, teamup_update_event, and teamup_create_event.

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

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

Explicitly names the permission needed ('Needs modify permission') and routes to the recovery sibling (teamup_undo_event_action, one hour window). Lacks explicit when-not-to-use guidance, such as pointing to teamup_update_event if the agent only wants to modify rather than remove.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds meaningful non-obvious behavior: the full set of returned sections and the security detail that 'the calendar key itself is never returned' — context an agent cannot get from the annotations or the empty schema.

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 what is returned, followed by the actionable 'call this first' instruction and a security caveat. It is dense but every clause carries information; the long enumeration in sentence one is the only mild readability cost.

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?

There is no output schema and no input schema, so the description effectively serves as the return-value documentation, listing the fields an agent will receive. Combined with the 'call first' usage cue and the key-not-returned note, an agent has everything needed to call 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?

The tool takes zero parameters, so there is nothing for the description to document and the baseline is 4. The description does not introduce any parameter guidance, which is correct here.

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 ('The calendar this connection points at') and enumerates the returned facets: title, timezone, date settings, custom fields, sub-calendars, key permission, plan features. This clearly separates it from sibling tools like teamup_get_subcalendar, which would only cover one sub-calendar, and it even names the endpoint (GET /{calendarKey}/configuration).

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 sequencing guidance: 'Call this first to learn the sub-calendar ids and the timezone,' which tells the agent both when to invoke it and what prerequisite knowledge it yields. It does not state when not to use it or name a direct alternative, so it falls short of the top band.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that by disclosing the shape of the response (including attachment metadata, version and change history) and the occurrence-id semantics, though it says nothing about permissions or pagination/traversal for large collections.

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 the resource in two tight clauses and follows with the occurrence-id rule. The return-field list is long but earns its place since no output schema exists; the trailing raw HTTP route is mildly redundant for an MCP tool but harmless.

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 tool with no output schema, the description compensates well by enumerating returned fields and clarifying the id format. 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema pattern alone does not convey: the 'rid-<unix start>' structure is explained as selecting one occurrence of a recurring event. That interpretation of an otherwise opaque id format is a real contribution.

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 resource ('One event by id') and enumerates exactly what it returns, including title, times, sub-calendars, recurrence, signups, comments, attachments, version and change history. This makes it trivially distinguishable from siblings like teamup_list_events, teamup_search_events and teamup_list_changed_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?

Gives concrete selection guidance for a key case: use the occurrence id ('123-rid-<unix start>') to fetch a single occurrence of a recurring event. It does not explicitly state when to prefer this over search_events/list_events or note that the id must already be known, but the 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 readOnlyHint, openWorldHint and destructiveHint=false, so safety is covered. The description goes beyond them by disclosing the returned field set (name, color, overlap rule, active state, links), which partially substitutes for the absent output schema; it omits error/auth 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?

Two tight sentences with the identity and returned fields front-loaded, followed by the endpoint. No filler and nothing redundant.

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 tool with annotations covering safety, the description covers identity and return fields, compensating for the missing output schema. Minor gaps remain around failure modes (e.g., unknown id) and auth, so it stops short of fully 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% for the single required subcalendar_id, so the schema already documents it fully. The description adds no syntax, format, or constraint detail beyond 'by id', so the 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 ('Get sub-calendar') plus the scope ('by id'), and the phrase 'One sub-calendar' implicitly distinguishes it from the list_subcalendars sibling. It even enumerates the fields returned, so an agent knows exactly what this call yields.

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 'by id' scope implies this is the single-item lookup versus the list variant, but there is no explicit when-to-use, no named alternative, and no stated prerequisites. Usage is inferable but not spelled out.

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, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuinely non-obvious behavior: secret key values are never returned, and identity must be established via id/name instead. That is meaningful 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?

Three tight sentences with the core purpose front-loaded, then the auth constraint, then the secret-handling caveat. The trailing 'GET /{calendarKey}/keys' is slightly redundant but harmless.

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

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

With no output schema, the description carries the return-value burden and does so by naming the four exposed fields, plus auth requirements and the secret-omission behavior. Pagination is covered by the schema, so nothing essential is missing for a correct 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 description coverage is 100% and all four filters (type, limit, offset, name_contains) are documented in the schema, including the pagination contract via next_offset. The description adds no filter syntax or format detail, so the baseline of 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 calendar's access keys') and immediately disambiguates what an access key is ('sharing links and user accesses'), plus enumerates the returned fields (name, role, active state, per-sub-calendar permission). No sibling tool covers this resource, so the agent can place it instantly.

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 a concrete prerequisite ('Needs a key with admin permission') and a usage rule for telling links apart ('use the id and name'). It does not name alternatives or exclusions, but there are no overlapping siblings in this tool set, so the missing piece is low-impact.

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, destructiveHint false, openWorldHint). The description adds meaningful behavior beyond that: deleted events carry delete_dt, recurring events return as series not occurrences, and the 30-day cap. This is more than the annotations provide, though it could clarify whether it requires auth or paginates.

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 sentences, each earning its place: scope, series handling, delete_dt marker, and the sync feedback instruction. Front-loaded with the core purpose and ends with the endpoint hint, 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?

For a read-only, two-param tool with a rich schema and annotations, the description covers the essential behavioral surprises (delete_dt, series-vs-occurrences, 30-day limit, sync loop). No output schema exists, so a bit more on response shape could help, but it's largely complete.

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

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

Schema coverage is 100%, so mode and since_timestamp are already fully documented in the schema, including the mode enum behavior and the timestamp constraints. The description reinforces the 30-day limit and the sync feedback loop but adds little syntactic detail beyond the schema. 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?

States a specific verb+resource (list events created/changed/deleted since a timestamp) and differentiates from siblings like teamup_list_events by framing it as a synchronization delta feed. The agent can immediately tell this is the incremental-sync tool, not a general listing tool.

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 frames usage ('for syncing') and gives a concrete operational instruction: pass the reply's timestamp as since_timestamp next time. It also documents the 30-day lookback constraint and the mode enum semantics, so an agent knows when and how to use it, though it doesn't name specific sibling 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 cover the safety profile (readOnlyHint, destructiveHint=false), and the description adds genuinely non-obvious behavior: recurring events are expanded into per-occurrence entries with ids of the form series id + '-rid-' + start, notes are markdown, and times follow the calendar timezone unless tz is set. It does not mention result caps or pagination.

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 dense sentences, front-loaded with purpose and scope, then return-shape behavior, then timezone handling, then the HTTP endpoint. No filler and nothing repeated from the schema.

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

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

With no output schema, the description carries the burden of explaining returns and it does so well (occurrence expansion, id format, markdown notes). The only gap is the absence of any statement about result limits or pagination, which matters for a range-listing 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 description coverage is 100%, so the schema already documents all four parameters including the 366-day constraint and the tz default. The description only lightly reinforces the tz/timezone behavior, adding little beyond the schema — the 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 with scope: 'List the events in a date range, optionally only on some sub-calendars.' This distinguishes it from generic siblings, though it never explicitly contrasts with teamup_search_events or teamup_list_changed_events, which are the closest alternatives.

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 date-range scoping and the optional sub-calendar filter, but there is no explicit when-to-use/when-not guidance and no routing to siblings such as teamup_search_events for keyword lookups or teamup_list_changed_events for incremental sync.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that: the enablement precondition, the shape of the payload returned, and the underlying GET endpoint. It stops short of noting pagination or empty-result 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 compact sentences, front-loaded with the resource and its payload before the precondition and endpoint. No filler, 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?

For a single-parameter read tool with no output schema, the description supplies the return fields, the precondition, and the endpoint — enough to call it correctly. Only pagination/empty-result behavior is unaddressed, which is a minor gap given the tool's simplicity.

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 parameter event_id is fully documented in the schema with a pattern. The description adds no format, sourcing, or lookup hints for the id beyond the API path template, so the schema does the heavy lifting — 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 the resource concretely ('the people signed up for an event') and enumerates the returned fields (name, email, id), so an agent knows exactly what it gets. The verb 'list' comes from the tool name rather than the description, and no sibling is explicitly distinguished, but none of the 14 siblings covers signups, so confusion risk is low.

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?

Adds one genuinely useful precondition — 'Signups must be enabled on the event' — which tells the agent when the call will succeed. However, it gives no guidance on when to reach for this tool versus teamup_get_event or teamup_list_events, and no error behavior when signups are disabled.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context beyond them: that results are permission-scoped and that admin keys additionally surface inactive sub-calendars, which is exactly the kind of hidden filtering behavior an agent must know. It stops short of describing pagination mechanics or rate 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?

Two short sentences with the resource definition front-loaded, followed by the one non-obvious behavioral caveat. The trailing endpoint reference is compact and adds a concrete anchor without padding.

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 four-optional-parameter, paginated list tool with no output schema, the definition covers the resource, its permission-scoped visibility, and the inactive caveat. Pagination and return-field shape are left to the schema, which is acceptable, though a hint about what a sub-calendar object contains would close the remaining gap.

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 limit, offset, name_contains and include_inactive are fully documented in the schema and the baseline is 3. The description adds no syntax or format detail for any parameter; its mention of inactive entries only loosely reinforces the include_inactive 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 (List) and resource (sub-calendars) and adds a clarifying gloss ('the colored lanes that events belong to, such as people, rooms or resources') that makes the concept unambiguous. The plural verb naturally separates it from the sibling teamup_get_subcalendar, and the endpoint line confirms the resource path.

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 name rather than stated: there is no explicit 'use this when you need X, use get_subcalendar when you need one item'. The permission note ('A key with admin permission also sees inactive ones') is the only conditional guidance, and it describes visibility rather than when to choose 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds genuinely non-annotated behavior: recurring events are expanded in results, and results are paged via limit/offset. It does not detail result ordering or how expansion affects counts, keeping it just short of full 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?

Three short sentences, front-loaded with the core search action and constraint, then the recurring-expansion caveat and paging model. Every clause carries information; the trailing endpoint reference is compact and useful for an open-world HTTP tool.

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 search tool with full schema coverage, no output schema, and safety annotations, the description covers search semantics, the 'today only' default trap, expansion behavior, and pagination. Missing only minor return-shape details (result ordering, what next_offset looks like), which the schema's offset description partly compensates for.

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 seven parameters are already documented in the schema (defaults, bounds, formats, next_offset usage). The description restates the query length and default date range but adds no syntax or format detail beyond the schema, making the baseline 3 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?

States a specific verb and resource ('Search events by keyword... within a date range') plus the two key constraints (query length, date scope). This clearly separates it from the sibling teamup_list_events, which has no keyword search, and from teamup_list_changed_events. An agent can identify the tool's function 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 actionable usage context: the default range is today only, 'so always pass the range you mean', and notes paging via limit/offset. It does not explicitly name when to prefer this over teamup_list_events or teamup_list_changed_events, so it falls short of full alternative-routing guidance.

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

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

Annotations already declare write/destructive/idempotent/openWorld, but the description adds genuine behavioral constraints the annotations cannot express: a one-hour validity window, refusal when the event was changed by someone else since the original call, and the underlying endpoint. These are exactly the failure modes an agent needs to anticipate.

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 WRITE marker, then the required input, then the constraints and endpoint. 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 one-parameter mutation tool with no output schema, the description covers input provenance, time limit, and conflict behavior. It stops short of saying what a successful undo returns or whether any state is left behind after the one-hour window lapses.

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 undo_id parameter is fully documented there, so baseline is 3. The description adds only the provenance of the id ('from that call'), which slightly reinforces but does not meaningfully extend 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 (undo) and resource (a recent event creation, update or deletion), plus the exact identifier needed. It is clearly distinguishable from the sibling mutation tools (create/update/delete_event) and even names the operations it reverses.

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

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

The description makes the trigger condition clear: it is used with the undo_id returned by a prior create/update/delete call, so an agent knows to reach for it only after one of those operations. It doesn't explicitly name a sibling as the alternative path (e.g. 'to make a new change, use update_event'), so it stops short of full when/when-not routing.

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, which only declare destructive/idempotent/open-world hints. The description discloses the read-then-write version check, that concurrent edits are refused rather than overwritten, that version-less events are left unchanged, that attachments are untouched, the one-hour undo_id lifetime, and the underlying PUT endpoint.

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?

A dense single paragraph, but front-loaded with the WRITE marker and ordered from semantics to permission to recurrence to side effects. Nearly every clause carries operationally useful information, with only minor run-on tendency.

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?

No output schema exists, and the description covers the return shape (event plus undo_id with its lifetime), the version-check behavior, recurrence handling, and side-effect scoping. An agent has everything needed 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 coverage is only 47%, but the description compensates on the parameters that matter: partial-update semantics ('fields you leave out keep their value'), redit usage, and the occurrence-id format. Booleans like signup_enabled and comments_enabled remain unexplained, but those are largely self-describing.

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 'WRITE: change fields of an event', giving a specific verb, resource, and mutation type. It is immediately distinguishable from teamup_create_event and teamup_delete_event 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?

Gives clear conditional guidance: pass redit with single/future for recurring events, use the occurrence id format, and modify permission is required. It routes to teamup_undo_event_action for the undo path, but does not state when to prefer a sibling like teamup_create_event instead of this tool, so routing is clear but not exhaustive.

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=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds meaningful details beyond those: a concrete destructive effect ('Making a sub-calendar inactive hides it from users without admin rights'), the permission requirement, and partial-update semantics. It stops short of explaining all destructive consequences or error behavior, so 4 is appropriate.

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 tight sentences, front-loaded with 'WRITE:' and the core action. Every clause earns its place: what changes, partial-update semantics, permission need, destructive side effect, and endpoint. There is 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?

For an update tool with no output schema and five parameters, the description covers the essential behavioral context: write intent, partial update, admin permission, a destructive side effect, and the HTTP method/path. It does not mention error behavior or return values, but with no output schema the latter is not required. The coverage is strong but not exhaustive.

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 only 20%, so the description must carry more weight. It names the four updatable fields (name, color, overlap rule, active state), which maps to the optional parameters, and clarifies partial-update behavior. However, it adds no format or constraint details beyond what the schema already enforces numerically (e.g., color range 1-48, name length), so it only partially compensates for the low 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 states a specific verb and resource ('change a sub-calendar's name, color, overlap rule or active state') and clearly distinguishes it from sibling tools like create_subcalendar or update_event. An agent can immediately tell this is the partial-update tool for an existing sub-calendar.

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 context for use: 'WRITE' marks it as a mutation, 'fields you leave out keep their value' describes the partial-update behavior, and 'Needs admin permission' sets a prerequisite. It does not name alternative tools or state when not to use it, so it falls short of a 5.

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