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

Goes well beyond the annotations: it discloses the two-phase CONFIRMATION_REQUIRED flow, the re-check of busy time immediately before writing, and the fact that newly-busy slots are skipped rather than double-booked. This is precisely the behavioral context an agent cannot infer from readOnlyHint/destructiveHint flags.

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

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

Three sentences, front-loaded with the purpose and followed by the guardrail flow and the safety behavior. No filler and every sentence earns its place.

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

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

With no output schema, the description compensates by describing what the first call returns (confirm_token plus a summary), and it fully explains the write-time safety behavior. Nothing an agent needs in order to invoke 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 the baseline is 3, but the description adds real meaning about the confirm_token sequencing and about skip_activities by explaining that busy time is re-checked so declined/conflicting activities are dropped. That is workflow semantics beyond the per-field descriptions.

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

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

States a specific verb and resource ('Create calendar events for a plan') and distinguishes itself from the sibling propose_schedule by describing the apply step versus the proposal step. An agent can tell it apart from create_event and propose_schedule 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 states the prerequisite (plan_id from propose_schedule) and the exact two-call sequence, including the condition that the token is supplied only after the user approves. It stops short of naming when to prefer this over raw create_event, but the workflow routing is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds real behavioral value by disclosing the shape of the result — per-account busy periods plus a merged timeline — and the cross-account aggregation, which is meaningful given there is no output schema.

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

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

Two sentences, zero filler, and the return contract is front-loaded before the usage hint. Every clause carries information.

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

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

For an aggregated free/busy query with no output schema, the description supplies enough about what comes back to call it correctly, and parameters are fully covered by the schema. It stops short of explaining merging semantics across timezones or how empty/overlapping periods are represented, which would matter for an aggregation tool.

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

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

Schema description coverage is 100% and all five parameters (accounts, time_min, time_max, timezone, calendars) are documented in the schema itself, including the default-permission semantics for accounts. The description only restates the time-range notion, adding no syntax or format 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 specific verb+resource ('Return the busy periods across accounts ... plus the merged busy timeline') with clear scope. It implicitly separates itself from detail-reading siblings via 'without reading event details,' but it never distinguishes itself from the very close sibling find_available_slots, which occupies nearly the same conceptual space.

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

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

Gives a concrete usage context ('Use this to answer "am I free at 3pm?"') and an implied when-not ('without reading event details'), which steers the agent away from list_events/get_event. It does not, however, address when to prefer find_available_slots or find_cross_account_conflicts, both obvious adjacent tools.

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

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

Beyond the annotations, the description discloses the key behavioral trait: the tool returns a command string and does not perform the login, with OAuth consent happening out-of-band in the browser. It does not cover what happens if the account id already exists or how the returned command should be conveyed, which the non-idempotent annotation hints matters. No direct contradiction with readOnlyHint=false, since the description never claims the tool is side-effect free.

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

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

Two sentences, front-loaded with what is returned, followed by the crucial caveat about where consent happens. No filler.

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

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

With 3 fully documented parameters and no output schema, the description supplies the one thing the schema cannot: that the return value is an instruction to hand to the user rather than an action performed in-band. Adequate for the tool's complexity, though edge behavior (duplicate account ids) is unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents 'role', 'access', and 'account' with enums and defaults. The description mentions none of them, so it adds nothing beyond the structured fields; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Return the exact command the user must run to connect a new Google account') and immediately dispels the wrong mental model that the tool performs the OAuth flow. An agent can distinguish this from disconnect_account or set_account_role without opening any schema.

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

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

It clearly states the context: OAuth consent happens in the user's browser, so this tool is used to obtain the instructions rather than to log in. It does not explicitly name a sibling alternative (e.g., disconnect_account) or state prerequisites, so it is strong but not fully routed.

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

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

The description adds critical behavioral context beyond the annotations: the AMBIGUOUS_ACCOUNT failure mode when `account` is omitted, and the instruction not to guess. Annotations correctly declare a non-destructive, non-idempotent write operation, and the description does not contradict them. However, it omits other useful behaviors — e.g., the default 'none' for send_updates (though that is in the schema) and whether the event is immediately visible or requires 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?

Two sentences with zero waste. The main action is front-loaded, and the failure-mode guidance is directly attached to the condition that triggers it. Every part of the description earns its place.

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

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

For a 13-parameter creation tool with 85% schema coverage and no output schema, the description covers the most agent-critical behavioral nuance: account ambiguity failure. It doesn't mention the return value (event ID) or default notification behavior, but those are largely covered by the schema. The description is complete enough for an agent to call correctly and handle the main error case.

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 85%, so the schema already documents most parameters (account, send_updates, timezone, recurrence, etc.). The description reinforces the account parameter's fallback behavior but doesn't add syntax or format details for other parameters beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource ('Create an event') and adds a scope qualifier ('on one account') that distinguishes it from sibling tools like update_event, move_event, or propose_schedule. An agent can tell this is for direct event creation 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?

The description clearly states the when-not condition — if `account` is omitted and multiple accounts are eligible, it fails with AMBIGUOUS_ACCOUNT and the agent should ask the user rather than guess. It does not explicitly name alternative tools (e.g., update_event, propose_schedule), but the guidance on account selection is clear and actionable.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, but the description goes well beyond them by disclosing the confirmation handshake, the exact return of the first call, and the irreversibility. This is behavioral 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?

Three tight sentences, front-loaded with the destructive nature and then the confirmation protocol. No filler or repetition.

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

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

No output schema exists, yet the description explains the shape of the first response (CONFIRMATION_REQUIRED, what would be deleted, confirm_token), closing the gap for a destructive tool. Nothing an agent needs to call it 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 80%, so most params are self-documented; the description adds real value by explaining the provenance and required timing of confirm_token (returned by a prior CONFIRMATION_REQUIRED response, only after approval). It does not touch account/calendar/send_updates, which the schema already covers.

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 ('Permanently delete an event') and immediately flags the destructive scope. An agent can distinguish it from update_event, move_event, and the read-only siblings without opening the schema.

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

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

Gives an explicit two-phase protocol: the first call yields CONFIRMATION_REQUIRED, the agent must surface it to the user, and only re-call with the token after explicit approval. This is exactly the when-and-how-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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true, so the safety and idempotency profile is fully covered. The description adds that it reports the session's own role, which is useful context but not deep behavioral detail. It does not describe caching, scope limits, or output shape, so a 3 is appropriate.

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

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

Two sentences, front-loaded with the verb and the enumerated scope, then the use case. No filler and nothing repeated from the title.

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

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

For a zero-param, read-only explanatory tool with no output schema, the description covers when to use it and what it returns. The only minor gap is that it does not sketch the return structure, but it is otherwise complete for an agent to call it correctly.

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

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

Zero parameters, which is the baseline-4 case. The description correctly implies a no-input, whole-picture explanation, and nothing about invocation is ambiguous.

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 (Explain) and resource (the role model), then enumerates exactly what it returns: which permissions each role grants, what role the session runs as, and what each connected account may do. This is clearly distinguishable from siblings like get_account or set_account_role.

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 says when to use it: to answer questions like "why can't you delete that?" accurately instead of guessing. This names the triggering scenario and the failure mode it prevents, which is strong routing guidance.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds substantial context beyond them: what is destroyed (stored tokens), what is removed (registry entry), that it is irreversible, and that a confirmation step gates execution. That is exactly the added-value disclosure expected for a destructive tool.

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

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

Three tight sentences: action, consequences/irreversibility, then the confirmation requirement. Front-loaded and every clause earns its place.

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

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

For a two-parameter destructive action with no output schema, the description covers effect, reversibility, and the confirmation gate; nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, including detailed semantics for account and confirm_token, so the schema carries the parameter burden. The description only echoes the confirmation requirement and adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ('Revoke this server's access to a Google account') and the concrete effects: delete stored tokens, remove from registry. An agent can clearly distinguish this from connect_account among 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 clear context: destructive, irreversible, and reconnecting requires fresh Google consent, plus 'Requires confirmation'. It does not explicitly name connect_account as the reverse alternative, but the consequence statement effectively routes the decision.

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 safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuine behavioral context beyond annotations: it merges busy periods from every checked account and warns that the slot is only trustworthy if every relevant calendar was included — useful for interpreting results and for deciding whether to restrict accounts.

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

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

Three sentences, intensely front-loaded, zero filler. Each sentence adds a distinct insight: the merge behavior, the return semantics, and the reporting obligation.

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, 11-parameter tool with a 100%-covered schema and no output schema, the description covers result interpretation and critical caveats well. It could better address account omission or pagination, but the main operational insight is present.

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

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

Schema coverage is 100%, so every parameter's meaning is documented in the schema; the description adds no parameter-level syntax or format details. Baseline 3 is appropriate when the schema does all the parameter work.

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

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

Specific verb+resource: finds free times, and the description clarifies scope ('across all their calendars at once' and 'Merges busy periods from every checked account'). This distinguishes it from check_freebusy, which likely examines a single account/interval.

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

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

The description implies the tool is for finding free/busy windows and hints that accounts matter, but it never names alternatives like check_freebusy or find_cross_account_conflicts, nor states when to prefer it. No when-not-to-use guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the burden is lower, and the description adds genuinely useful behavior: it returns conflicting pairs plus the exact overlap window. It does not, however, mention result limits or what happens when the account list is empty, which would round it out.

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

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

Two tight sentences: the purpose and scope come first, the illustrative example disambiguates rather than pads, and the return shape closes it out. Nothing is redundant with the name or title.

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

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

With no output schema, the description correctly takes on the job of describing the return value (conflicting pairs with overlap window), and the annotations plus the fully documented schema cover parameters and safety. An agent has everything needed to select and call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents accounts filtering, ISO 8601 time range, timezone, and the include_same_account default. The description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

The description states a specific verb and resource ('Find events that overlap') and pins the scope to 'across different accounts', which is exactly what distinguishes it from siblings like check_freebusy or list_all_events. The concrete example (personal doctor appointment colliding with a work meeting) removes any ambiguity about the operation's semantics.

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

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

The cross-account scope implies when this tool is appropriate, but no sibling is named and no exclusion condition is given (e.g. 'use check_freebusy instead when you only care about a single account/slot availability'). Usage is inferable rather than stated.

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

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

Annotations already establish readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value by disclosing the nature of the returned data, notably that the OAuth access level reported is the one 'actually granted by Google' and that permissions shown are 'effective', which is not derivable from annotations or schema.

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

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

One tightly packed sentence that front-loads the action and then enumerates the payload with zero filler. Every clause earns its place.

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

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

With no output schema, the description usefully compensates by listing the salient returned fields (role, granted OAuth level, calendars policy, effective permissions). It stops short of describing error behavior or what happens when the account id does not resolve, but is adequate for a simple read tool.

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

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

Schema description coverage is 100% and there is a single required parameter, so the schema already explains the account id fully. The description adds no format, aliasing, or resolution detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Show one account in detail') and enumerates the content returned: role, OAuth access level granted by Google, calendars policy, effective permissions. It is clearly distinguishable from list_accounts by the singular scope, though it does not name the sibling explicitly.

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

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

Usage is implied by 'one account in detail' versus the sibling list_accounts, and the required account id in the schema reinforces it. However, there is no explicit statement of when to use this versus list_accounts or describe_permissions, nor any prerequisites.

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 and open-world, so the safety profile is covered. The description adds non-obvious behavioral context the annotations cannot: the cross-account scoping rule that makes event ids account-bound. It does not cover not-found or wrong-account failure behavior, keeping it below 5.

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

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

Two short sentences, no redundancy. The core action is front-loaded and the constraint sentence directly explains the required-parameter semantics.

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

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

For a simple read tool with rich annotations and a fully documented schema, the definition covers what an agent needs to call it. It omits error/failure semantics (e.g., id not found, id from another account), which is a minor remaining gap.

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

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

Schema description coverage is 100% and each parameter is documented, so the baseline would be 3. The description goes further by explaining why 'account' is mandatory (id validity is account-scoped), adding rationale beyond the schema's own 'required whenever more than one account could apply'.

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 ('Fetch a single event by id'), and the word 'single' implicitly separates it from the list_events/search_events siblings. An agent can identify the operation 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 a clear usage rule: the account must be passed explicitly because an event id is only meaningful inside its originating account. It does not name alternatives (list_events, search_events) or say when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing the shape of the payload (fixed vs flexible fields), which helps the agent interpret results, though it says nothing about size, pagination, or freshness.

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

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

Two tight sentences with no filler; the content enumeration is front-loaded and the actionable 'read before proposing' instruction closes it. Every clause earns its place.

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

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

There is no output schema, so the description carries the burden of describing returns, and it does so thoroughly (times, windows, durations, energy levels). Combined with the read-before-scheduling guidance, an agent has everything needed to call and use it.

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

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

The tool takes zero parameters, so the baseline is 4; the schema fully covers what little there is. The description correctly adds no parameter detail because none 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 ('Show') and resource ('the routine'), then enumerates the exact contents (sleep/wake times, job window, recurring activities with duration, window, energy level). This clearly distinguishes it from sibling mutators like update_routine, reset_routine and propose_schedule.

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 use condition: 'Read this before proposing a schedule so you can explain what is fixed and what is flexible,' which ties it to the propose_schedule workflow. It does not explicitly name alternatives or when not to use it, but the pre-condition is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by telling the agent when to invoke it (name-to-account resolution) and what each entry contains, though it does not mention pagination or result size for an open-world listing.

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

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

Two sentences, both front-loaded: the first defines the output fields, the second the trigger condition. Every clause earns its place with no filler.

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

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

For a zero-parameter read-only list tool with no output schema, the description covers purpose, returned fields, and the routing trigger. 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?

There are zero parameters, so the baseline is 4. The description correctly implies a no-argument call and enumerates the fields returned per account, matching an empty input schema.

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

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

States a specific verb (List) and resource (connected Google accounts) and enumerates the returned fields (id, email, role, enabled state, permissions). This distinguishes it from the singular sibling get_account without opening either schema.

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

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

Provides an explicit trigger: 'Call this first when the user refers to a calendar by name' so the agent can map a name to an account id. It does not name a when-not or a specific alternative to use instead, but the condition is concrete and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so safety and idempotency are covered. The description adds the union scope and start-time ordering, but says nothing about result volume, pagination, or what 'readable' excludes – gaps that matter for a cross-account aggregation.

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

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

Two sentences, front-loaded with the scope, followed by the routing guidance. Every clause carries information and nothing is padded.

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

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

For a read-only list tool with no output schema, the description covers scope, ordering, and when to reach for it, which is enough for correct invocation. Minor unaddressed points like pagination or the size of a cross-account result set keep it from being fully complete.

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

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

Schema description coverage is 100%, so time_min, time_max, and timezone are all documented in the schema. The description only echoes the existence of a time range and adds no format, default, or timezone behavior beyond what the schema supplies, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource (list every event) with an explicit scope that separates it from the single-account siblings: 'across every readable account and calendar in a time range'. The added detail that results are 'sorted by start time' further pins down what the tool returns.

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 a clear trigger ('when the user asks about their whole schedule') and a second intended use ('before reasoning about cross-account conflicts'), which points toward find_cross_account_conflicts. It stops short of naming alternatives or stating when NOT to use it (e.g., for a single account, prefer list_events).

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that results span multiple connected accounts and include per-calendar access level, but says nothing about pagination, ordering, or permission failures beyond the annotation set; a 3 is fitting given the low bar annotations set.

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

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

Two tight sentences with no filler; the operational fact (what it returns and why it matters) is front-loaded right after the scope statement.

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

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

With no output schema, the description usefully discloses the returned fields (calendar id and access level), which is exactly what an agent needs before chaining into event tools. Minor gaps remain around result ordering/paging and whether calendars are grouped per account, so it is not perfect.

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

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

Schema description coverage is 100%, and the single 'accounts' parameter is documented in the schema including its omission default ('every account you are permitted to read'). The description only restates 'one or more connected accounts' without adding format or filtering detail, so baseline 3 applies.

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

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

States a specific verb and resource ('List the calendars') and clarifies scope ('on one or more connected accounts'), which cleanly separates it from siblings like list_accounts, list_events, and get_account. It also names the downstream value (the calendar id needed by the event tools), so an agent knows exactly what it gets back.

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

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

The phrase 'returns the calendar id needed by the event tools' implies this is the prerequisite lookup before event operations, giving clear context for when to call it. There are no explicit exclusions or named alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive, so the safety profile is covered. The description adds useful behavioral detail — that results are labelled with their source account and that omitting `accounts` fans out across all readable accounts — but says nothing about pagination, rate limits, or result ordering.

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

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

Three sentences, zero filler, with the broad-scope default and the concrete example front-loaded before the labeling note. Every sentence carries distinct information.

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

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

For a read-only listing tool with a fully documented schema and annotations covering safety, the description covers the key default-scope behavior and the account labelling of results. With no output schema, a brief note on return shape or ordering/pagination would round it out, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so all six parameters are already well documented, including the `accounts` omission default and the ISO 8601 / bare-date semantics of the time bounds. The description's restatement of the `accounts` default adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource ('List events in a time range') and clarifies the default scope when `accounts` is omitted, which is more than a restatement of the name. It does not, however, differentiate itself from close siblings such as `list_all_events` or `search_events`, leaving the agent to infer which listing tool applies.

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

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

It gives a concrete usage context ('what do I have tomorrow?') and explains the condition under which the default broad query happens, which helps the agent decide on argument shape. It stops short of naming when to prefer an alternative such as `search_events` or `check_freebusy`.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context the annotations don't: a hard same-account constraint imposed by the underlying API. It still omits what happens to the source copy (does the original survive?) and any permission requirements, which is why it is not a 5.

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

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

Two sentences, zero filler, with the scope constraint front-loaded before the workaround. Every clause earns its place.

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

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

For a four-parameter mutation tool with no output schema, the description covers the essential constraint and failure mode. Remaining gaps are the fate of the original event and permission prerequisites, which an agent might still want.

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%, with to_calendar and from_calendar already documented in the schema ('on the same account', 'currently on'). The description's same-account statement reinforces but does not extend those, and event_id remains undocumented in both places. Baseline 3 fits.

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 (move) and resource (event) and bounds the scope precisely with 'to a different calendar on the SAME account'. It also names the create-then-delete workaround, which separates it from siblings like create_event/delete_event without the agent needing to open those schemas.

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

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

Gives an explicit when-not condition (cross-account moves are impossible) and the exact alternative procedure (create on target, delete original). An agent hitting a cross-account request is routed unambiguously.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, idempotentHint), but the description adds genuine context beyond them: it writes nothing, and the response carries a plan_id, per-block explanations, and a workload verdict. It does not cover rate limits or the staleness/freshness of the plan, which is the only remaining gap.

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

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

Three sentences, front-loaded with what it does, then the payload contract, then the approval workflow. Every clause carries information; nothing is redundant with the name or title.

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

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

There is no output schema, so the description carries the return-value burden and does so by naming the plan, plan_id, explanations, and workload verdict. Combined with the annotation safety profile and full schema coverage, an agent has everything needed to call it and hand off to apply_schedule.

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 all six parameters (days, only, exclude, accounts, timezone, start_date) are already documented, including defaults and formats. The description adds no parameter-level meaning 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 specific verb and resource chain (read calendars, find commitments, compute a balanced schedule) and explicitly frames itself as the non-writing planner, which separates it from apply_schedule in the same workflow.

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

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

It gives explicit routing: this tool computes the plan, then 'show the plan to the user and get explicit approval before calling apply_schedule.' That names the alternative and the condition that gates it, so no inference is needed.

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

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

The description says it 'Overwrites any customisation,' which is a destructive effect, while the annotations declare destructiveHint=false. This directly contradicts the safety profile an agent would rely on 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 description is front-loaded with the action and includes a useful enumeration of the default routine. The list is somewhat long but gives concrete meaning to 'default,' so it mostly earns its place.

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

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

For a one-parameter, no-output-schema mutation tool, the description states the effect and overwrite behavior clearly. It could say more about when to prefer update_routine, but the schema and annotations cover most other structural needs.

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

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

Schema description coverage is 100%, and the single optional timezone parameter is fully documented in the schema. The description adds no parameter-level detail, so it neither helps nor harms beyond the baseline.

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

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

The description uses a specific verb, 'Restore,' and a specific resource, the built-in default routine, then enumerates exactly what that default contains. An agent can distinguish it from update_routine or get_routine without inspecting schemas.

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

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

It implies when to use the tool by stating it restores defaults and overwrites customisation, but it does not explicitly contrast this with update_routine, name alternatives, or state when not to use it. The usage context is clear but inferred rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value by enumerating what the analysis actually surfaces (category hours, day balance, unbroken stretches, sleep protection), which matters because there is no output schema. It does not mention permissions or rate limits, but openWorldHint partly signals cross-account reach.

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

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

Two sentences, no filler, with the analytical content front-loaded before the usage directive. Could be tightened slightly but every clause earns its place.

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

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

With no output schema and no required parameters, the description does the needed work by describing the shape of the returned analysis and the pre-planning context. An agent has enough to call it correctly; only auth/permission nuances are unspecified.

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 week_of, accounts and timezone are fully documented in the schema itself. The description adds only the constraint that the week must 'already exist,' which is a marginal semantic addition. Baseline 3 is appropriate when the schema carries the parameter burden.

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?

Names a specific verb ('Analyse') and resource ('a week that already exists on the calendars'), then enumerates the concrete outputs: hours per category, day balance, long unbroken stretches, sleep protection. This distinguishes it from write-side siblings like propose_schedule and update_routine, which an agent can rule out immediately.

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 states when to use it: 'open a weekly planning session, before proposing the next week,' which also implies ordering relative to propose_schedule. No explicit when-not or named alternative is given, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description. The description adds matching-scope behavior (titles, descriptions, locations, attendees) and the default cross-account read scope, but says nothing about result caps, ordering, or truncation behavior despite a max_results ceiling of 2500.

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

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

Three short sentences, zero filler, with the core capability and its matching scope front-loaded before the account-scoping caveat. 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 six-parameter search with no output schema, the description covers purpose, match fields and default scope, which is enough to invoke correctly. It omits anything about the result shape, ordering, or how max_results bounds output, which is the main remaining gap given there is no output schema to lean on.

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 83%, so the schema already documents query, accounts, time_min, time_max and timezone; baseline 3 applies. The description adds a little meaning by clarifying what the `query` string is matched against, but leaves max_results (the only undocumented parameter) unexplained and only restates the accounts default.

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 technique ("Full-text search") plus the resource (events) and scopes it to a time range, which cleanly separates it from the list_events / list_all_events siblings. It stops short of naming those siblings or explicitly contrasting search from listing, so differentiation is inferable rather than explicit.

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

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

The description implies the trigger condition (you have a text query and a time window) and clarifies the default account scope, which is genuinely useful. It never states when to prefer this over list_events, list_all_events, or find_cross_account_conflicts, nor any exclusions, so guidance is only implied.

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

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

Annotations declare destructiveHint=false, but the description adds the non-obvious consequences: tokens are preserved and a disabled account is excluded from every operation, including read fan-outs. That is the key behavioral fact an agent needs and it is not encoded in the annotations. It stops short of stating reversibility or whether enable is idempotent.

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

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

Two short sentences, no redundancy, and the most decision-relevant fact (tokens are not deleted) is front-loaded in the first sentence.

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 two-parameter boolean toggle with full schema coverage, annotations for the safety profile, and no output schema, the description covers what is required. The only gap is the absence of routing guidance versus sibling account-management tools.

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

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

Schema description coverage is 100%, so both parameters (account id, enabled boolean) are already fully documented, including the multiple-account disambiguation hint. The description adds no parameter-level detail beyond the schema, so baseline 3 applies.

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

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

States a precise verb pair (enable/disable) and resource (account), and clarifies the scope of the change: tokens survive. This cleanly separates it from destructive siblings like disconnect_account or delete operations. It doesn't explicitly name a sibling, so it falls short of a 5.

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

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

Usage is implied rather than stated: the reader infers this is the tool for toggling an account's active state. There is no explicit when/when-not guidance or comparison against disconnect_account or set_account_role, which are the nearest alternatives.

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

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

Annotations cover safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds a valuable domain caveat beyond annotations: roles cannot exceed granted OAuth scopes, so promotion may silently fail to grant write. This is non-obvious behavioral context that an agent 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?

Two sentences, no waste; the core action is front-loaded and the caveat follows logically. Every sentence earns its place.

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

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

For a 2-param mutation with annotations and full schema coverage, the description is nearly complete: it states the action and the key caveat. Minor gaps: no mention of permission requirements to change roles or how the change takes effect.

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 documents both parameters with examples and enum values. The description adds no param syntax or format beyond what the schema provides. Baseline 3 applies when schema does the heavy lifting.

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

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

States a specific verb ('change') and resource ('role assigned to a connected account'), which is clear and distinct from siblings like set_account_enabled or connect_account. It doesn't explicitly name a sibling to differentiate, but the role-focused scope is unambiguous.

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

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

Usage is implied by the purpose but there's no explicit when-to-use/when-not guidance, no prerequisites stated, and no alternatives named. The OAuth-scope caveat hints at a constraint but isn't framed as usage guidance.

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

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

Annotations declare non-read-only, non-destructive, non-idempotent, so the safety profile is already covered; the description still adds genuinely useful behavior beyond that by explaining patch semantics ("only the fields you supply are modified") and the account-scoping requirement for ids. It omits the default notification behavior, but the schema's send_updates description carries that.

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

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

Three short sentences, front-loaded with the action and then the two most important behavioral facts. No filler, though the account sentence partially duplicates the schema text rather than earning new ground.

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 11-parameter partial-update tool with no output schema, the description supplies the two things an agent most needs to call it safely: patch semantics and the account requirement. Combined with annotations covering the safety profile and the schema covering defaults, this is adequate 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 55%, so several parameters (end, title, location, description, event_id) are undocumented in both places. The description adds the semantics that unspecified fields are untouched and that account is mandatory due to account-scoped ids, but that largely echoes the schema's own account description; it does not compensate for the coverage gap on the remaining fields.

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

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

States a specific verb and resource ("Change fields on an existing event") and clarifies that this is a partial update, which distinguishes it from create_event/delete_event. It does not, however, explicitly separate itself from the sibling move_event, which also alters event fields, so an agent must infer the boundary.

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

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

The description gives clear usage context for the partial-update behavior and states the account prerequisite, but offers no when-to-use/when-not guidance relative to siblings like move_event or update_routine. Usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is partially covered. The description adds a genuinely useful persistence detail ('Changes persist to data/routine.json'), but it omits whether changes merge or overwrite existing routine fields and does not confirm the write-confirmation behavior the annotations imply.

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

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

Three tight sentences: what it changes, when to use it, and where it persists. Front-loaded with the action, no filler, every sentence earns its place.

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

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

For a mutating tool with nested objects, zero schema coverage, and no output schema, the description leaves significant gaps: it never explains the nested sub-fields the active parameters carry, nor whether partial updates require an id (activity.id is required inside the object). It is under-specified given the tool's real complexity.

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

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

Schema description coverage is 0% and there are 3 top-level parameters (sleep, activity, max_scheduled_hours_per_day). The description names the domains but does not explain the nested fields (bedtime, wakeTime, session_minutes, sessions_per_week, weekdays, window) or the unit/format expectations, leaving the agent to infer nested semantics from the schema alone.

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

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

States specific verb (change) and the three concrete resources it mutates: sleep times, daily limits, and a single activity. The sibling set contains reset_routine and apply_schedule, and this description's scoping to three specific fields clearly differentiates it from 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?

Provides explicit trigger conditions via example user phrases ('make DSA 60 minutes', 'I want to wake at 6', 'move part-time work earlier'), which tell the agent exactly when this tool is appropriate. It does not name alternatives (e.g. apply_schedule or reset_routine) or exclusions, keeping it out of the 5 tier.

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