Get Classlist Emails

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

The readOnlyHint annotation already covers the safety profile, so the description only needs to add behavioral context. It does so by clarifying scope (all roles in the course). However, it does not disclose output format or uniqueness guarantees, though these are minor for this simple read operation.

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?

Two sentences with no filler. The main action is front-loaded, and the usage guidance is compactly integrated. Every sentence contributes useful information.

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 single-parameter, read-only tool with a fully documented schema, the description covers the essential context: what it fetches, who it includes, and when to use it. No output schema is present, but the return type is easily inferable from the description. A brief note on output format would make it 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?

The input schema has 100% description coverage for courseId. The tool description only refers to 'a course' and does not add details beyond the schema, which is acceptable because the schema already defines the parameter clearly.

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 states a specific action and resource: fetching all email addresses for a course. It explicitly enumerates the included roles (instructors, TAs, students), making the tool's purpose unmistakable and clearly distinct from sibling tools like get_roster or get_announcements.

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 trigger conditions: the user wants a class email list, needs to email the whole class, or wants contact info for everyone enrolled. It does not explicitly name alternatives to avoid, but the use-case framing is sufficiently directive.

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