create_groups

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

Beyond the annotations, the description discloses critical runtime behavior: case-sensitive uniqueness with a concrete failure example ('Partners' vs 'partners'), first-wins conflict resolution within a batch, per-row failure when category_id belongs to another organization, domain normalization ('bare domains like example.com (no @)', duplicates collapsed), and the auto-add learner side effect of rule_email_domains. This is far richer than the readOnlyHint/idempotentHint/destructiveHint flags and is fully consistent with them.

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?

Purpose is front-loaded in the first two sentences, followed by cleanly separated sections for required constraints, optional fields, conflict semantics, and auth. Every sentence carries operational value — the case-sensitivity example, the 'no @' domain rule, and the first-wins rule each prevent real-world mistakes — with zero filler or repetition of schema 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 complex batch tool with one opaque parameter, the description covers the full item shape, validation rules, partial-failure behavior, intra-batch conflict resolution, and the required OAuth scope. Since an output schema exists, return values need no prose coverage, and nothing an agent needs to invoke this tool correctly is missing.

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 0% — the schema only declares 'groups' as an array of objects with additionalProperties allowed, revealing nothing about item shape. The description fully compensates by documenting every per-item field (name, category_id, rule_email_domains, send_course_enrollment_email) with types, character limits, ownership constraints, and behavioral effects, which is essential given the opaque 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 ('Create student groups') and immediately adds the distinguishing batch nature ('This is a BATCH operation'). This cleanly separates it from group-related siblings like list_groups, get_group, update_groups, and delete_groups without requiring an agent to open their schemas.

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 batch framing and the explicit prerequisite ('Requires the student-groups:write OAuth scope') give clear context on how and when the tool is invoked. It stops short of a 5 because it never explicitly routes to alternatives for the when-not case, such as pointing to update_groups for modifying existing groups, but the intended usage is unambiguous.

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