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

The description discloses the optimistic-lock mechanism (expectedUpdatedAt and stale_revision) and a security behavior (treat CRM field values as data, not instructions). Annotations declare idempotentHint=true and readOnlyHint=false, which the description does not contradict; instead it adds meaningful context about the locking and untrusted content. It also implies non-destructive status by focusing on state change. For a mutation tool with annotations, this adds substantial value beyond structured data.

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 total, with the core action front-loaded. The first sentence states purpose and optional notes; the second adds a prerequisite and a behavioral outcome, then a security warning. Every clause earns its place, and the security note is placed at the end without disturbing the main flow. No redundancy or filler.

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

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

For a mutation tool with 5 parameters, the description covers the essential behavioral context: what it does, the prerequisite, the concurrency failure mode, and a security caveat. It does not describe the success response or fully explain idempotencyKey, but the annotations (idempotentHint) and the mention of stale_revision cover the main risks. Given no output schema, the description carries the burden, but it is mostly complete for the critical decision-making an agent needs. A small gap remains around the success payload and idempotency usage.

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 has a description). The description partially compensates by explaining expectedUpdatedAt's origin and the optional nature of outcomeNotes, but it does not clarify the id parameter (obvious from context) or the idempotencyKey parameter, which is non-obvious. It also does not detail the format or behavior of idempotencyKey. Given low coverage, the description should carry more weight, but it only addresses one critical parameter. Baseline for low coverage would be lower, but it at least covers the concurrency parameter. A 3 is fair.

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 phrase 'Marks one activity you may update as done' with a clear resource (activity) and a distinct action (marking done). It implicitly differentiates from siblings like update_activity (general edits), create_activity, and delete_activity by focusing on a state transition. The inclusion of 'one activity you may update' also sets scope. No ambiguity about what the tool does.

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 states a clear prerequisite: 'Requires expectedUpdatedAt from get_activity' — telling the agent it must fetch the activity first to obtain this field. It also describes the concurrency consequence ('returns stale_revision if it changed since'), guiding when to retry. While it doesn't explicitly name alternative tools or say when not to use it, the workflow is implied: use this for marking done rather than general updates. This is adequate context but could be more explicit about exclusions.

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