Kalender Sync

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

Goes well past the annotations (readOnlyHint=false, destructiveHint=false): it discloses that availability is checked LIVE, that overlaps do NOT block creation and instead return a warning the agent must surface, that only blocks_time:true entries count as conflicts, and that credits_exhausted means the call was not performed and no write confirmation exists. That is exactly the kind of consequence-level detail annotations cannot carry.

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 purpose, then behavior, then parameters, then the status contract — a sensible ordering. It is long, and the all-day inclusive-end rule is restated from the schema, but for a tool with this many sharp edges most sentences carry operational weight.

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 8-parameter write tool with a sibling list of 14, the description covers the failure mode (credits_exhausted), the conflict semantics, timezone/all-day handling, and calendar selection. An output schema exists, so it correctly does not spend space on return shape beyond the status/warning contract.

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 75%, and the description fills the important gaps: all-day end is INCLUSIVE with a concrete 1–3 September example, both ends must use the same form, calendar_id is conditionally optional, and title is required. It does not address location or description (the undescribed schema fields), but those are self-evident string 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?

Opens with a specific verb+resource ('Creates an event') plus a scope constraint ('in one of the calendars this access may write to') that immediately separates it from update_event and delete_event. An agent knows what this does and where it lands 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 routes the agent: 'check the day with get_availability first' when a user asks to book a specific day, 'list_calendars shows the writable calendars', and calendar_id is only needed when several calendars are writable. It also gives a when-not-to-act rule (credits_exhausted → do not retry automatically).

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 destructive, idempotent, open-world and non-read-only, but the description adds substantial context beyond them: the async result state `created_pending_processing`, that the target may look empty for minutes, that the sync keeps running (and survives revocation of this assistant's access), the request_id idempotency contract including the failure mode on mismatched params, atomic all-or-nothing creation for two-way, and zero credit cost.

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 core action and its precondition are front-loaded, and paragraphs are thematically split (confirmation, idempotency, result lifecycle, two-way rules, out-of-scope). It is dense and somewhat long, but nearly every sentence carries operational information rather than 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 mutation tool with 6 parameters, an output schema, and a genuinely complex lifecycle (preview dependency, background processing, persistent sync semantics, two-way atomicity), the description covers confirmation requirements, return-state expectations, retry behavior and limits. Nothing an agent needs 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 coverage is 100%, so baseline is 3, but the description adds real semantics: request_id stability rules, default direction, reverse_detail_level defaulting to detail_level in two-way, and the constraint that detail levels must not exceed max_detail_level/max_reverse_detail_level from preview_sync.

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 ('Creates a sync between two of the user's own calendars') and immediately narrows scope to the user's own calendars, one-way or two-way. It also delineates what this tool does NOT cover (syncs with other people, changing rules, reversing direction) and names the alternative surface for those.

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 precondition ('after the user confirmed this specific source, target, direction and detail level(s) in the chat'), a required prior step ('Call preview_sync first and tell the user what it reports'), and routes deletion and out-of-scope sync management to named siblings (preview_delete_sync, delete_sync) and the Kalender Sync app via syncs_url.

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 destructive and openWorld, but the description adds substantial context beyond them: provider-level propagation to mirrored calendars, irreversibility, cascade cancellation for co-participants, shared refusal semantics with update_event, and the credits_exhausted non-execution contract (no result data, do not retry). This is exactly the behavioral disclosure a destructive tool needs.

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

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

Front-loaded with the core action, then builds outward to scope, confirmation duties, and error semantics. Dense and largely waste-free, though the middle paragraphs are prose-heavy enough that an agent must read carefully to extract the actionable rules.

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-format details are not required, yet the description still covers the critical conditional return case (credits_exhausted yields no write confirmation). Combined with the addressability rules and refusal/alternative routing, nothing an agent needs to call this safely 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 50%: event_id is documented as coming from create_event, but calendar_id has no description in either the schema or the prose. The description clarifies which events are addressable, which implicitly constrains the calendar scope, but does not explain the calendar_id parameter itself. Baseline 3 for a partially documented 2-param tool.

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 ('Deletes an event') and immediately clarifies scope: deletion happens at the provider and propagates through sync. It explicitly distinguishes itself from siblings by naming respond_to_event as the correct tool for invitations organised by others.

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 when/when-not conditions: only events THIS access created unless manageable:true, confirm with the user first for events not created by this access, warn participants are cancelled along with the deletion. Names the alternative (respond_to_event) and the fallback behaviour of update_event refusals.

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, so the bar is lower, yet the description adds substantial context: copies are removed from target calendars while source events are untouched, the action is irreversible, removal happens in the background within minutes, and it costs no credits. It also discloses the token-gating behavior ('without a valid, unexpired token for exactly this sync nothing is deleted').

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 paragraphs: purpose+workflow, then destructive scope, then side effects and alternatives. Front-loaded with the verb and the confirmation requirement; no sentence is filler given the safety-critical nature of the 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?

With an output schema present, return-value explanation is unnecessary, and the description covers everything else an agent needs: prerequisites, token semantics, what is destroyed, what is preserved, reversibility, timing, and cost. Nothing material is missing 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 baseline is 3, but the description adds real meaning to confirmation_token: it must be valid, unexpired, and scoped to exactly this sync, and ref must match the one used in preview_delete_sync. That is semantic detail genuinely beyond the schema's terse 'from preview_delete_sync' 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?

Opening sentence states a specific verb and resource ('Deletes one of the user's own syncs') and the scope ('own' syncs). It is clearly distinguishable from siblings preview_delete_sync (the prerequisite step) and set_sync_paused (named as the non-destructive alternative).

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 workflow: call preview_delete_sync first, report the sync and copy count to the user, then call only after explicit in-chat confirmation. It also names the correct alternative ('to only stop syncing, use set_sync_paused instead') and warns against prompt-injection triggers, which is exactly the when/when-not guidance an agent needs.

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 this a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered by structured data. The description nevertheless adds real behavioral context beyond them: the reason set is closed, unknown reasons surface as `other` with no guessed next step, and the call costs no credits. These are useful, but the return-format detail is partly the output schema's job, so this sits at a solid 3 rather than higher.

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 dense but front-loaded, leading with what it explains and following with the closed-reason/no-guess/no-credit caveats and the sibling routing. Every sentence carries distinct information, though the first sentence packs multiple clauses and the second paragraph is comparatively long.

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 diagnostic with an output schema, the definition covers purpose, behavioral quirks (closed reason set, `other` fallback), cost, and where adjacent operations live. Nothing an agent needs to call it correctly or interpret the result 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% for the single `ref` parameter, so the baseline is 3. The description adds only the scoping qualifier that the sync must be one of the user's own; it introduces no format or provenance detail beyond what the schema already supplies.

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 — explaining why one of the user's own syncs is not running — and pins the scope to recorded state and reason. It distinguishes itself from siblings by naming set_sync_paused and the Kalender Sync app for the adjacent operations. An agent can identify this as the diagnostic read for a single sync 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 routes the agent: resuming a paused sync is set_sync_paused, while reconnecting an account, reviewing the plan or replacing a calendar happens in the Kalender Sync app via next_step_url. Both the when-to-use and the when-not-to-use-this paths are stated rather than 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?

With annotations already covering the safety profile, the description adds substantial non-obvious behavior: direct reads merged with no cached copy, 60-second read reuse that can briefly hide new events, per-calendar as_of, exclusion of cancelled events, inclusion of tentative/all-day, partial-read handling via read: false in sources and warnings, and the credits_exhausted not-performed state. This is exactly the extra context annotations cannot express.

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 opening sentence front-loads the purpose, then proceeds in clearly labeled sections by concern. It is long, but the length is largely earned by genuinely surprising semantics (blocks_time for Apple all-day events, credit exhaustion); a few clauses could still be tightened.

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-parameter tool with an output schema present, the description still covers the non-obvious output semantics an agent must interpret (busy, blocks_time, as_of, sources/read, warnings, status) and the failure mode. Nothing needed to call and correctly use it 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% (from/to both documented as ISO 8601), so the schema carries the parameter burden and a 3 is the baseline. The description adds range semantics (busy times within the range, all-day inclusivity) but no new syntax or constraints for the two inputs.

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 first sentence gives a specific verb and resource ('Returns the user's busy times...across all calendars shared with this access'), which is sufficient to distinguish it from the event-mutation siblings and from search_events. It stops short of explicitly naming an alternative tool, so sibling differentiation is implied by scope rather than stated.

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 concrete intent-based routing ('for am I free / find me a slot, count only blocks_time: true'; 'for what do I have on, list everything') and an explicit prohibition ('Never present a blocks_time: false entry as nonexistent'). It also prescribes behavior for credits_exhausted (do not retry automatically). It never names a sibling tool to use instead, 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 read-only/non-destructive, but the description adds substantial behavior beyond them: zero credit cost, works at zero balance, that unreadable calendars remain listed deliberately and are excluded from `get_availability`, and that `sync_health` reflects Kalender Sync's own sync rather than provider availability. That last distinction is real operational nuance an agent could not infer.

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 highest-value facts (what it lists, that it is free), then organized one paragraph per return field with consistent backticked field naming. Eight short paragraphs for a zero-param tool is on the long side, but each paragraph carries a distinct decision-relevant rule, so little is 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?

With no parameters and an output schema already present, the description's job is interpretation and routing, both of which it covers: cost behavior, how each flag should influence downstream calls like `create_event` and `create_sync`, and how to relay `notice`/`missing_calendars` to the user. Nothing needed 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 is 4. The description instead invests in defining the semantics of returned fields (`readable`, `writable`, `sync_target`, `notice`, `missing_calendars`, `sync_health`), which is useful interpretation guidance even though an output schema exists.

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 ('Lists the calendars shared with this access') and immediately bounds scope with 'each with the detail level the user allowed.' It also implicitly separates itself from the other calendar tools by noting 'Credit warnings concern the other calendar tools, not this calendar list.' An agent can identify the tool's role 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 clear context: this is the free, always-available calendar directory, and it explicitly says the credit warnings apply to sibling calendar tools instead. It tells the agent to pass on `missing_calendars` and to mention `notice` only when relevant. It stops short of an explicit 'use this when the user asks X' routing statement.

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

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

Annotations already cover read-only/idempotent/non-destructive/closed-world, and the description still adds real behavioral context: no event titles returned, zero credit cost, null id/name for calendars outside the shared set rather than hiding the sync, shared_with_person syncs never name the other person's calendar, and what an empty list actually means.

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 purpose and return semantics, then the ref contract, then sibling routing. Dense but largely earns its length; the final paragraph reads a little like a tool directory and the dashboard URL could be trimmed, keeping it short of a 5.

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 explain return values, yet it covers the non-obvious edge cases (empty list, null calendar id, shared_with_person anonymity, two-way single entry) and the downstream ref usage. Nothing an agent needs 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?

The tool takes zero parameters, so the baseline is 4. The description still adds semantic value by explaining that the returned short refs are positional inputs to other tools, which is the closest thing to a parameter contract 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+resource (lists the user's own calendar syncs) and immediately scopes it: 'the user's own', with the clarification that a two-way sync is one entry, not two. An agent can distinguish this from list_calendars and from the create/preview sync 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?

Explicitly routes the agent: the short ref feeds diagnose_sync and set_sync_paused, pausing/resuming goes to set_sync_paused, creating goes to preview_sync/create_sync, deleting to preview_delete_sync/delete_sync. It also states the condition for re-calling (positional refs, call again if syncs may have changed).

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 readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: nothing is deleted, the tool returns a confirmation_token valid for 10 minutes and bound to this specific sync, delete_sync requires that token, and the call costs no credits. These are exactly the behavioral facts an agent needs and cannot infer from annotations.

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

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

The no-deletion guarantee and the token contract are front-loaded, and each sentence carries distinct information (preview contents, agent instruction, token lifecycle, eligibility, input source, cost). It is slightly dense and could be trimmed without loss, but nothing 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?

Given an output schema exists, return values need not be explained, yet the description still surfaces the one output an agent must handle (confirmation_token and its 10-minute validity). Combined with eligibility rules, input provenance, and the required confirm-then-delete flow, nothing needed 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% and the single ref parameter is documented in both schema and description. The description still adds value by constraining the ref's provenance ('from a current list_syncs result') and tying it to the target-calendar eligibility rule, though it adds no format details beyond the schema's example.

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 ('Shows what deleting one of the user's own syncs would do, without deleting anything') and enumerates what the preview contains (connected calendars, count of copies removed). It is clearly distinguishable from its sibling delete_sync, which it explicitly names as the follow-up step.

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 preconditions (only syncs whose target calendars are released for sync_target; syncs with another person are managed in the app), states the required input provenance ('Use a ref from a current list_syncs result'), and defines the downstream workflow by requiring the user to confirm and then call delete_sync with the token. Alternatives and exclusions 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?

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantially more: it reports ALL blockers rather than the first, deliberately does not claim an event count because it is not computed, a positive preview is not a reservation, a sync copies continuously rather than once, and it costs no credits. That is genuinely new behavioral context beyond the structured hints.

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

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

Dense and front-loaded with the core purpose, and most sentences carry load (blockers, non-reservation, no credit cost). Minor cost: the defensive 'that is not computed, so it is not claimed' clause and 'A sync copies continuously, not once' add words that could be tighter, and the prerequisite paragraph stacks several constraints in one block.

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 need not explain return values, and it covers what matters: prerequisites, the max_detail_level/detail_level/reverse relationship, the fact that all blockers are returned, and the caveat that create_sync re-validates. Nothing needed 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds real relational meaning: max_detail_level is the ceiling this access may copy, detail_level checks a specific level against it, and max_reverse_detail_level governs flow back for two-way. It also clarifies reverse_detail_level defaults to detail_level, which the schema only implies via $ref.

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 first sentence states a precise verb and resource ('Checks whether a sync ... could be created') and immediately bounds it with 'without creating anything,' which cleanly separates it from create_sync. The one-way/two-way enumeration further pins the scope and all 14 siblings are clearly not this 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?

It names the alternative (create_sync) and explains the relationship, stating that the same checks run again on write and conditions can change. Prerequisites are spelled out (source shared with this access, target released via list_calendars: sync_target; both for two-way), which is exactly the when-to-use context an agent needs.

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 past the destructive/openWorld annotations: the organiser is notified, is_recurring/is_organizer can be read instead of asking, refusals name the way forward and must not be retried, and credits_exhausted means the write did NOT happen with only warnings returned. This is exactly the mutation-side disclosure annotations cannot carry.

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 action and its consequence, then provenance, then scope rules, then failure handling. Dense and mostly waste-free, though the prose runs long and a bulleted shape for the scope rules would read faster.

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 the description still covers the exception paths that matter: credits_exhausted (no write performed), warnings, and refusal messages. Nothing material 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 coverage is 100%, so the baseline is 3, but the description adds real decision semantics: the 'on Tuesday IS occurrence' heuristic, the rule that calendar_id should always be passed to avoid a round trip, and the provenance of event_id. It stops short of adding anything on comment beyond the schema's own CalDAV note.

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 precise verb+resource: accepts/declines/tentatively accepts an invitation someone else sent, and immediately contrasts with deleting an invitation from the calendar. An agent can distinguish this from create_event, update_event and delete_event 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?

Explicitly routes the agent: event_id/calendar_id come from get_availability or search_events, manageability is verified via list_calendars, and it names the alternative action (removing from the calendar) and why it is wrong. It also gives a concrete decision rule for when to ask the user about scope and when not to.

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 readOnly/openWorld annotations: discloses that free/busy-only calendars can never match and emit a warning, that 'no match' is not proof of absence, that cancelled events are unsearchable, and the exact status semantics (credits_exhausted means the call was not performed). This is exceptional behavioral 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?

Long but well front-loaded and dense with operational content; each paragraph (visibility limits, result fields, range, status) carries distinct and useful information. Slightly verbose for some readers, but 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?

Given an output schema already defines the return shape, the description covers everything else an agent needs: coverage constraints, default range, and the credit-exhaustion failure mode. Nothing needed to invoke or interpret the call 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 baseline is 3, but the description adds real meaning: the range behaves like get_availability (single span of at most 92 days, lookback bounded to one year) and defaults to the last 7 days plus the next 85 when from/to are omitted, enriching the schema's brief 'Default: 7 days ago' notes.

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 (finds) and resource (events), and pins down the matching semantics: case-insensitive substring on title, location and description, scoped to calendars shared with this access. An agent can immediately distinguish it from get_availability and the mutation 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?

Explicitly routes the agent: use results' event_id/calendar_id to call update_event, delete_event or respond_to_event directly rather than re-calling get_availability. It also instructs not to filter out blocks_time:false events, and tells the agent not to auto-retry on credits_exhausted.

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: the action is irreversible ('the notification email cannot be recalled after sending'), rate-limited ('at most 5 messages per account in 24 hours'), returns a feedback_id receipt, and fixes nothing. This explains why destructiveHint=true/openWorldHint=true apply, so no contradiction with the 'does not change calendars' reassurance.

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 purpose and scope, then progressively tighter rules. It is longer than average, but each sentence adds a distinct constraint (rate limit, consent semantics); little is redundant with 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?

Covers purpose, triggers, prohibitions, irreversibility, rate limits, and the consent parameter, and an output schema exists so return values need not be spelled out (feedback_id is still noted as a receipt). Nothing needed 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. The description still adds real meaning for contact_ok: it is consent rather than a promise of reply, defaults to false for every category including 'bug', and never subscribes the user to a newsletter - nuances the schema does not fully carry.

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: stores a user feedback message and notifies the Kalender Sync team. It also clarifies the negative scope ('does not change anything in the user's calendars'), which cleanly separates it from every calendar-mutating sibling like create_event or 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?

Explicitly names the triggering conditions (a wanted capability the tools lack, or something broken) and the hard precondition (only when the user explicitly asked or clearly agreed after being offered). It also states an exclusion: never on your own initiative and never include calendar content the user did not provide.

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: idempotent set-semantics with the changed:false signal, both directions of a two-way sync affected together, no deletion on pause, and copies removed again on resume – which usefully explains the destructiveHint. It also discloses zero credit cost. Not a 5 only because it does not say what permissions or error responses to expect.

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 core action and the non-toggle semantics, then layers conditions. The later sentences are dense and somewhat long, but each carries a distinct constraint (side effects, eligibility, cost) rather than restating the name.

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 state-mutating tool this covers semantics, side effects, eligibility limits, ref provenance and cost, and an output schema exists to explain the return. An agent has everything needed 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 description coverage is 100%, so ref and paused are already documented (ref from a current list_syncs result, true = paused). The description reinforces the ref-provenance rule but adds no format or constraint detail beyond the schema, 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 concrete verb and resource: "Sets whether one of the user's own syncs is paused." It immediately disambiguates from a toggle and scopes the operation to the caller's own syncs, so an agent can distinguish it from siblings like create_sync, delete_sync and diagnose_sync.

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 preconditions and exclusions: only syncs into sync_target calendars can be paused, and syncs paused due to plan/calendar/update issues cannot be resumed here. It also names the source of the ref ("a current list_syncs result"), routing the agent to the right upstream tool.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the mutation/external-visibility profile is partly covered. The description adds substantially beyond them: participant notification behaviour, that a synchronised copy must be changed at source, that editing one date of a recurrence affects only that date, and that on credits_exhausted no write occurs and only warnings/credit info are returned.

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 one-line purpose, then organised into addressable-event types, refusal cases, and a status caveat — each block earns its place. It is dense and long for a single tool, but no sentence is pure padding and the bullets aid scanning.

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 9-parameter destructive mutation with an output schema, the description covers everything an agent needs to act correctly: which events are editable, the four failure modes and their alternatives, side effects on participants and copies, recurrence granularity, and the credits_exhausted no-op case. Return-value details are rightly delegated 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 coverage is only 56%, but the description compensates on the most consequential semantics: title/start/end represent the complete new state, and passing timestamps versus bare dates toggles all-day status. It also clarifies event_id provenance and that calendar_id must reference a manageable calendar. location, description and all_day still carry little or no explanatory text, keeping this short of a 5.

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 ('Updates an event') and immediately narrows scope by defining the two addressable event classes and naming the sibling tools that produce the relevant ids (create_event, get_availability, list_calendars, respond_to_event). An agent can distinguish this from create_event/delete_event/respond_to_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?

Explicitly enumerates when the call works (events this access created, or any event in a manageable calendar) and four refusal conditions with the prescribed alternative for each (not released, shared below full detail, synchronised copy, someone else organises it → respond_to_event). It also fronts the credits_exhausted status check so the agent knows the call may be a no-op.

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