get_classlist

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

Annotations already establish readOnlyHint=true and openWorldHint=true, and the description adds meaningful behavioral context: the default result contains instructors/TAs with NetIDs and emails, while everyone=true additionally includes all students. It does not discuss auth, rate limits, or errors, but for a read-only roster lookup the added scope is valuable beyond the 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 a single, efficient sentence that front-loads the primary return content before the flag behavior. It contains no filler and does not repeat what the schema already provides.

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 two-parameter read-only tool with no output schema, the description conveys the essential returned fields and the only mode-changing flag. A more explicit statement of the default behavior and output shape would improve completeness, but combined with the schema and annotations it is sufficient for straightforward use.

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 schema already documents the course parameter (ID or text) and everyone has a boolean default, so the main missing semantics was the meaning of everyone; the description supplies that by stating everyone=true lists all students too. The default staff-only result is only slightly implicit, but the semicolon structure makes the intended reading clear.

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 clearly identifies the resource: course staff (instructors, TAs) with NetIDs and emails, plus the optional expansion to students via everyone=true. It lacks an explicit verb like 'retrieves' or 'lists' for the default mode, but the tool name and return description make the purpose unambiguous and distinct from siblings like list_courses or get_grades.

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?

No guidance is provided about when to use get_classlist instead of a sibling tool, and no alternatives or exclusions are named. The everyone flag is parameter-level guidance, not tool-selection guidance, so the description leaves usage context entirely implicit.

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