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

Annotations already carry the safety profile (destructiveHint=true, idempotentHint=false), and the description adds genuinely non-derivable behavior: existing section ids mean removal, settings are merged rather than replaced, and an undoId is returned for restoring the prior draft. It stops short of describing auth needs or what happens to omitted fields beyond settings.

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 mutable surface, then the two operational caveats (published lock, section-id semantics) and the return value. 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 destructive 11-parameter mutation with a rich schema and an output schema, the description covers the highest-risk gotchas (published immutability, section removal semantics, undo path). It omits any indication that settings are merged vs. replaced only for the top-level object and says nothing about whether title/instructions are replaced wholesale, a minor residual 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?

With 55% schema coverage across 11 parameters, the description compensates by mapping the mutable fields to parameters and clarifying the tricky ones: 'Existing section ids identify sections to remove' for removeSectionIds, merge semantics for settings, and the courseVariant constraint that matching sections must be removed in the same call. Nested class/section details are left to 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 ('changes') and resource ('a draft') and enumerates the mutable surface: title, instructions, course, classes, dates, settings, sections. An agent can distinguish it from create_assignment_draft and restore_assignment_draft 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?

Gives a clear exclusion ('Published assignments cannot be changed here') and implies the undo path via restore_assignment_draft, but never names that sibling or states which tool should be used for published assignments instead. Clear context, no explicit routing.

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