Kalender Sync

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

Annotations only say it is a non-destructive write with open-world access; the description goes far beyond that with live-vs-cached availability checks, overlap-as-warning semantics, provider-specific reminder retention (Outlook keeps only one), timezone storage behavior in Apple Calendar, and the `credits_exhausted` no-write case. This is behavior an agent cannot infer from 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?

Well structured with bolded subsection headers and front-loaded purpose, and nearly every sentence carries an operational fact. It is on the long side for a tool description, and the illustrative asides (e.g. the "Baustelle Darmstadt" example) could be trimmed without losing meaning.

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

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

An output schema exists, yet the description still tells the agent which result fields matter (`status`, `warnings`, `reminders`, `reminders_not_kept`) and how to act on them. For a 9-parameter write tool with side effects and provider quirks, nothing essential to a correct call is missing.

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

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

Schema coverage is 78%, and the description still adds meaning the schema doesn't: all-day `end` is inclusive with a worked example, `calendar_id` is only needed when multiple calendars are writable, `title` is required, and the reminders array semantics (most-important-first, 0–40320, all-day counted from 00:00 of day one, `[]` vs omit) go well beyond the schema's one-liner.

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 an event") plus the scope constraint ("in one of the calendars this access may write to"). An agent can immediately distinguish this from update_event, delete_event, and create_sync 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 to siblings: check `get_availability` first when booking a specific day, use `list_calendars` to see writable calendars. It also declares when-not-behavior (overlaps are allowed, warnings must be surfaced) and tells the agent not to retry on `credits_exhausted`, which is exactly the kind of usage rule a description should carry.

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: it discloses that the result is created_pending_processing with nothing copied for a few minutes, that the sync keeps mutating the target afterward and survives revocation of assistant access, that two-way legs are all-or-nothing, and that the cost is zero credits. The destructiveHint is substantiated by explaining that the sync removes its own copies in the target and that deletion is handled by delete/delete_sync instead.

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?

Every paragraph carries distinct information (precondition, idempotency, lifecycle state, two-way rules, colors, out-of-scope) and the purpose is front-loaded. It is on the long side, and the Outlook category-name and Apple Calendar color detail is close to vendor trivia an agent rarely needs mid-call.

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 mutating, open-world, idempotent tool with an output schema, the description covers the remaining burden: preconditions, the returned status value, post-call lifecycle, failure atomicity for two-way, and where the unsupported operations live. Nothing an agent needs in order 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?

Though schema coverage is 100% (baseline 3), the description adds semantics the schema cannot: request_id replayed with identical parameters returns the same sync while a reused id with different parameters fails rather than duplicating work, and reverse_detail_level defaults to detail_level with both legs created atomically. event_colors defaults are spelled out per direction and per calendar platform.

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 names a specific verb (creates a sync) and resource, and explicitly scopes it to the user's own calendars, one-way or two-way. It distinguishes itself from siblings by naming preview_sync, preview_delete_sync, delete_sync and syncs_url, so an agent can pick it without opening another 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 an explicit precondition chain: user must have confirmed source, target, direction and detail level(s), and preview_sync must be called first with its result relayed. It also names what this tool cannot do (syncs with other people, changing rules, reversing direction) and routes those to the Kalender Sync app, which is a genuine when-not clause.

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 a safe idempotent read, but the description adds value beyond them: reasons are a closed set, unrecognised values degrade to `other` rather than being guessed, and no next step is claimed in that case. It also discloses cost ('costs no credits') and the timestamps reported (last_synced_at, error_since).

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 behavioural content is front-loaded in the first sentence and the routing in the second paragraph, with no filler. It is slightly dense — the degradation and cost clauses are packed into one long sentence — but nothing is 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?

The single required parameter is fully covered by the schema, and an output schema exists so return values need not be explained. The description still adds enough about outputs (reported timestamps, next_step_url) and degradation behaviour to make the tool callable with correct expectations.

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 `ref` format and its provenance from list_syncs are already documented in the schema. The description adds the ownership constraint ('one of the user's own syncs'), which narrows which refs are valid beyond the raw schema text.

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

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

States a specific verb and resource — explains why one of the user's own syncs is not running — and scopes it ('own', not shared-with-others) in a way an agent can act on. It also distinguishes the resource from siblings (diagnosis vs. sync creation/pausing) without ambiguity.

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 goes to set_sync_paused, while reconnecting accounts, reviewing the plan or replacing a calendar happen in the Kalender Sync app, with next_step_url pointing there. It also excludes a use case ('reports no event-level causes'), so the boundaries are 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses that calendars are read live at the provider with no cached copy, that reads are reused for up to 60 seconds so a just-created event may be missing, and that unreadable calendars surface as read: false in sources plus warnings. It also explains the credits_exhausted status meaning the call was never performed and that only warnings/credit data return in that case — precisely the kind of failure-mode context annotations cannot convey.

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 organized into labeled paragraphs ('How the answer is produced', 'What busy contains', 'Completeness'), which makes a long description scannable. It runs roughly 400 words and re-explains several return-field semantics despite an output schema existing; the Apple/iCloud all-day caveat and credit-failure rule earn their space, some of the event_id/reminders detail is closer to redundancy.

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

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

Covers the full contract an agent needs: what is returned, the blocks_time interpretation trap that would otherwise cause wrong answers about availability, partial-failure signaling via sources.read and warnings, and the credits_exhausted short-circuit. With an output schema present, it correctly spends its words on semantics the schema cannot express rather than restating the shape.

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 only two required params (from, to) with ISO 8601 examples already documented in the schema. The description adds no format, boundary, timezone, or range-length guidance beyond 'a given range,' so it neither compensates for nor improves on 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?

Opens with a specific verb and resource plus scope: 'Returns the user's busy times in a given range, across all calendars shared with this access.' The scope qualifier ('shared with this access, not necessarily all calendars they own') is an important disambiguator. It never names a sibling such as search_events, so an agent must still infer which tool wins for a targeted event lookup rather than a free/busy query.

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 decision rules: 'for am I free / find me a slot, count only blocks_time: true' versus 'for what do I have on, list everything and let the user judge,' plus the prohibition 'Never present a blocks_time: false entry as nonexistent' and the do-not-retry rule on credits_exhausted. These are concrete when-to-use and how-to-interpret directives, but no alternative tool is ever named, so sibling routing is left to the agent.

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

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

Annotations already declare 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 declare read-only, idempotent, non-destructive, so the bar is lower, yet the description adds substantial behavior: null id/name for calendars outside the shared set, shared_with_person syncs never expose the other person's calendar, no event titles returned, and no credits consumed. It also warns the short ref is positional and callers should re-list if syncs may have changed.

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 definition first, then caveats, then sibling routing. Some sentences are convoluted ("where a page in Kalender Sync completes it, next_step_url") and the closing multi-tool paragraph is list-like, but nearly every sentence carries information an agent needs.

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

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

For a no-parameter read tool with annotations and an output schema, the description covers what is returned, the edge cases (empty list, null calendar, shared_with_person), the cost model, and which tools consume the returned ref. Nothing material 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?

Zero parameters, so the baseline is 4. The description goes beyond the schema by explaining the returned field semantics (event_colors source/fixed/off, next_step_url, sync_1 short refs), though an output schema already exists and carries part of that load.

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 user's own calendar syncs) and immediately scopes it: own syncs only, one entry per two-way sync, no event titles. An agent can distinguish it from list_calendars and from the mutation siblings 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 to alternatives: set_sync_paused for pausing/resuming, preview_sync and create_sync for creating, preview_delete_sync and delete_sync for deleting, and the dashboard for rule changes. It also states a when-not: an empty list means the user has no own syncs, not that none are possible.

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

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

Beyond the readOnly/non-destructive annotations, it discloses the confirmation_token lifetime (10 minutes), that the token is scoped to this specific sync, that delete_sync requires it, and that the call costs no credits. These are exactly the behavioral details an agent needs to avoid misusing the preview.

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

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

The description is front-loaded with the key non-destructive purpose and confirmation workflow. It is somewhat longer than strictly necessary for a one-parameter tool, but nearly every sentence carries actionable information such as token scope, eligibility, and 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?

Given the output schema, annotations, and single fully documented parameter, the description covers everything needed: purpose, confirmation workflow, token dependency, eligibility limits, and credit cost. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and the schema already explains that ref comes from list_syncs. The description adds useful semantics by restricting valid refs to the user's own deletable syncs whose target calendars are released for syncs.

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 gives a specific verb and resource ('Shows what deleting one of the user's own syncs would do') and immediately clarifies it is a non-destructive preview. It also states the concrete payload (connected calendars, number of copies that would be removed), which distinguishes it cleanly from delete_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?

It states the workflow explicitly: show the preview to the user in plain words, ask for confirmation, then call delete_sync with the token. It also says when this tool is not usable (syncs with another person are managed in the app) and where to get the required ref (a current list_syncs result).

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 carry the full safety profile, so the description is graded mainly on added context. It does add real behaviour an agent could not infer: it costs no credits, it does not compute or claim an event count, a sync copies continuously rather than once, and a positive preview is not a reservation. Those are useful disclosures, though they are framed as caveats rather than a systematic account of what the response contains.

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 capability and the 'without creating anything' constraint are front-loaded in the first sentence. The precondition and caveat material in the second paragraph is dense but each sentence carries distinct information; the only slight cost is length for a straightforward preview 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 6-parameter read-only tool with a full output schema, the description supplies what the schema cannot: the sharing/release preconditions, the non-reservation caveat, cost, and why no event count is returned. 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 coverage is 100% and both enums are documented in-schema, so the baseline applies. The description adds interpretation for detail_level versus max_detail_level and reverse_detail_level defaulting to detail_level, but it does not cover direction, event_colors, or the two required IDs beyond restating them.

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 precise verb and resource ('Checks whether a sync between two of the user's calendars could be created ... without creating anything') and explicitly separates itself from create_sync and from preview_delete_sync by scope. The one-way/two-way framing makes the capability immediately legible.

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 preconditions for use in concrete terms: source must be a calendar shared with this access, target must be one released for syncs (pointing at list_calendars: sync_target), and two-way requires BOTH shared and released. It also tells the agent when a positive result is not sufficient, by pointing to create_sync re-running the checks.

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?

Adds substantial behavioral context beyond the annotations: visibility is limited to calendars this access can see, free/busy-only calendars cannot match and trigger warnings, cancelled events are excluded, and credits_exhausted means the call was not performed. This directly helps the agent interpret partial or failed results.

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 purpose is front-loaded and the paragraph structure groups matching semantics, visibility limits, result fields, range behavior, and status handling. It is somewhat long and dense, but nearly every sentence provides operational guidance that helps correct invocation.

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

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

Given the presence of an output schema, the description does not need to enumerate return fields, yet it still highlights key result attributes like event_id, calendar_id, is_organizer, is_recurring, and reminders. It covers visibility caveats, range constraints, cancellation behavior, and credit failure handling, leaving little relevant ambiguity.

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 useful range semantics not fully captured by the schema: a single span of at most 92 days, lookback bounded to one year, and default coverage of the last 7 days plus next 85. It also clarifies that query matches title, location, and description via case-insensitive substring.

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: finds events by text across calendars shared with this access. It specifies the matching fields and case-insensitive substring semantics, which clearly distinguishes 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?

Gives explicit routing guidance: act on returned event details directly instead of calling get_availability again, and do not filter out blocks_time:false events because they are still ordinary appointments. It also explains when 'no match' is not proof of absence and how to handle credits_exhausted without automatic retry.

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 flag a destructive write, and the description goes well beyond them: title/start/end are a complete replacement state (so a timed event can flip to all-day and back), a reminders list replaces rather than merges, other participants are notified, and same-email-address refusals are permanent settings rather than transient errors. It also discloses the credits_exhausted no-op path where only status/warnings come back with no write confirmation.

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 replacement-state rule, then organized under bold headings for the exceptional cases. It loses a point for length and for restating the reminders replace/omit/Outlook-first semantics that the reminders schema property already documents almost verbatim.

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

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

For a 10-parameter destructive mutation spanning several calendar providers, it covers the branches an agent must handle: partial vs. full update, refusals and their remedies, notification side effects, reminder truncation reported via reminders_not_kept, and the credits_exhausted early exit. Return values are explained even though an 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?

Rich added meaning for reminders (ordering by importance, 0-40320 minutes, all-day counting back from 00:00 of the first day, Outlook keeping only the first, personal vs. Nextcloud-shared scope) and for start/end as a full new state. However, with schema coverage at 70%, three parameters — location, description and calendar_id — get no explanation in either place, so the description doesn't fully close the gap.

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

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

States a specific verb and resource ('Updates an event') and immediately defines two addressable event classes with the id source for each (create_event vs. get_availability via list_calendars). An agent can tell this apart from create_event, delete_event and 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 names the reminders-only shortcut (pass event_id, calendar_id, reminders and leave title/start/end out), enumerates four refused situations, and routes each to its alternative — e.g. 'call respond_to_event with response: "declined"'. It also states when title/start/end are required, which is the key branch point.

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