update_enrollments

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

Beyond the annotations, the description discloses important behavior: null clears due_at and expires_at but is rejected for active, omitting active leaves it unchanged, and deactivating removes a learner's access. It also states the required OAuth scope. No contradiction with 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 well-structured with a short purpose, a bulleted set of fields, a highlighted asymmetry note, and a final scope requirement. Every sentence adds information; nothing is 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?

The description covers purpose, batch semantics, field-level rules, side effects, and auth requirements; an output schema exists so return values need no explanation. It stops short of describing failure/partial-failure behavior or how unknown fields in the item objects are handled, which would be useful for a batch mutation 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?

With 0% schema description coverage, the description carries the full burden for the enrollments array and does so thoroughly: each item needs an id, the writable fields are listed, and the null semantics for each field are specified. This is far more actionable than the bare 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?

The description opens with a specific verb and resource: 'Change access on existing enrolments', and identifies it as a BATCH operation. It then enumerates the writable fields, making it easy to distinguish from sibling tools like list_enrollments, get_enrollment, complete_enrollments, and bulk_enroll_students.

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 frames this as operating on existing enrollments in batch, and the required OAuth scope is stated. It does not explicitly name alternatives or state when not to use it, but the context is sufficient to route an agent to this tool for updating active/due_at/expires_at.

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