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

Goes well beyond the annotations by disclosing the full side-effect profile: in-app notifications to assignee and creator, next-occurrence creation for repeating activities, Google Calendar event updates and attendee emails, and the stale_revision concurrency signal. The idempotent no-op behavior is stated explicitly and is consistent with idempotentHint=true, and the external side effects are consistent with openWorldHint/destructiveHint.

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 expectedUpdatedAt requirement, then layers in side effects in a logical order. The prose is dense but each sentence carries distinct information; the closing untrusted-content warning is useful but generic boilerplate that slightly inflates length.

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 steps up by naming the stale_revision error signal and the unchanged-return behavior, so an agent knows both the success and the no-op/conflict paths. Side effects, concurrency requirements, and idempotency are all covered for what is otherwise a mutation with sparse schema documentation.

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

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

Schema description coverage is only 20% (only workspaceId is documented inline, and even that is a conditional-requirement note), so the description must compensate. It meaningfully explains expectedUpdatedAt as a concurrency token sourced from get_activity and flags outcomeNotes as optional, but id and idempotencyKey carry no added meaning, leaving the coverage gap only partially closed.

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

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

States a specific verb and resource plus scope: 'Marks one activity you may update as done, with optional outcome notes.' This cleanly separates it from siblings like update_activity, create_activity, and delete_activity, and the 'one activity you may update' phrasing signals the permission/eligibility constraint.

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 prerequisite ('Needs expectedUpdatedAt from get_activity') and a clear no-op condition for already-done activities, which tells the agent when the call is unnecessary. It stops short of naming explicit alternatives such as update_activity for non-completion edits, so it is clear context rather than full when/when-not routing.

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