Create Course Groups

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

Far beyond the annotations, it discloses required permissions (manage_groups_add, manage_groups_manage, read_roster), hard limits (200 students, 50 groups, 250,000 CSV characters), the single-use caller/content/state-bound token, partial-result semantics with created IDs and run_id, 24-hour server-local run records that do not survive restart and require affinity, and the concurrency caveat that Canvas offers no atomic membership compare-and-set.

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?

Information density is high and the critical preview/approval workflow is front-loaded, with limits and failure semantics after. It is a dense block of short sentences with little grouping, which slightly impedes scanning, but almost every clause carries operationally relevant content.

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, non-idempotent bulk mutation, it covers workflow, permissions, limits, partial failure, resumption, token invalidation and concurrency; an output schema exists so return-value documentation is unnecessary. The only meaningful omission is how course_identifier is interpreted and what exactly a preview call returns before a token is supplied.

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 burden well: it specifies csv_data columns (group_name, description, canvas_user_id, one student per row), that names/emails are rejected as IDs, that existing group-set names are rejected for group_set_name, and the single-use nature of confirmation_token. The gap is course_identifier, whose ID-vs-slug/integer semantics are never explained.

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 ('Preview, then confirm creation of a NEW course group set and its groups/members') and defines the scope (CSV-driven bulk creation). It also implicitly separates this tool's job from resume_course_group_creation by describing the resume path and its fresh preview/token requirement.

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 gives a clear operational sequence: preview, show the complete preview, obtain the instructor's explicit approval, then confirm. It also states the resume path ('resume uses a fresh preview/token and checks ALL current memberships'). What it does not do is name resume_course_group_creation explicitly or state when to prefer other group tools such as list_groups.

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