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

The description asserts "Changes only your own progress bar, so it runs without asking first," which tells the agent this is a harmless auto-approvable write and conflicts with destructiveHint=true and the non-readOnly annotation. The useful additions (own-account scope, undo semantics) are real, but the reassurance directly undercuts the structured safety signal.

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 with the primary action and its undo front-loaded; nothing is padded. The closing clause about running without asking is the only sentence that does not purely earn its place, since it conflicts with the annotations.

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

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

For a 3-parameter mutation with annotations and no output schema, the description covers scope and reversibility adequately. It omits any mention of the response (success/failure shape) and of side effects like course progress or level/unlock gating, which an agent could reasonably want to know.

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 documents group, lesson_id provenance (get_course), and completed=false. The description's "completed false clears it" restates the schema rather than adding syntax or edge-case 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?

"Mark a lesson done in your own course progress, or undo it" gives a concrete verb (mark done / undo), the resource (lesson), and the scope (your own progress), which separates it from the content-editing sibling update_lesson. It never names a sibling outright, but the per-account framing 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?

The description establishes clear usage context: this is per-account progress, not course content, and it is reversible via completed=false. It stops short of explicitly routing the agent (e.g. "to edit lesson content or publish, use update_lesson"), so no true exclusion is stated.

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