blackboard_groups

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds value by noting 'visible membership' and 'no enrollment changes', but it does not disclose how view modes, group_id, or pagination affect behavior beyond what the schema already exposes.

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 a single, front-loaded sentence with no filler. Every clause adds useful information: it names the verb, the resource scope, and the non-mutating guarantee.

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 output schema and annotations carry some of the burden, but with five parameters and zero schema documentation, the description is thin. It communicates the core purpose but leaves view-specific usage, group_id targeting, and pagination conventions mostly implicit, making it adequate but not fully complete.

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%, so the description needed to compensate by explaining parameters like view, limit, offset, and group_id. It only provides high-level resource language ('groups, group sets, visible membership') that loosely maps to the view enum, but leaves the remaining parameter semantics entirely 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?

The description uses a specific verb, 'Read', and a specific resource, 'course groups, group sets and visible membership'. It also adds the scoping statement 'with no enrollment changes', which clearly distinguishes this as a read-only tool and separates it from potential write-oriented group tools.

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 gives clear context: use this tool to read course groups, group sets, and membership without affecting enrollments. It does not explicitly name alternatives among siblings like connects_groups or blackboard_courses, but the read-only scope and course-group vocabulary provide a clear usage context.

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