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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, so the safety profile is fully covered and the description's burden is lower. It does add real behavioral substance: only assignments marked complete with a grade entered count, and ungraded work is not penalized until graded, which explains the computed result. It stops short of pagination, term ordering, or what the target_grade mode returns when the target is unreachable.

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?

Three sentences, front-loaded with the primary return shape before the alternative mode, and every clause carries information about output or counting rules. The middle sentence is long but earns its place by defining the grading rule; there is no filler or restatement of the title.

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 4-param read tool with full schema coverage and an output schema, this covers the essentials, and extra return-value detail is a bonus rather than a requirement. It is slightly incomplete about partial target_grade input (e.g., target_grade supplied without class_id) and about include_past_terms behavior, which the description leaves entirely to the schema default.

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 100%, so the baseline is 3 and the schema already documents each parameter, including the 'with target_grade' conditionality on class_id and target_id. The description usefully explains the parameters as a coupled set (the target_grade mode requires the other two) and clarifies that ungraded status affects results, but it adds no format or constraint detail beyond 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?

States a specific verb and resource ('Get the user's grades') and enumerates exactly what is returned: per-term classes, overall grade, trend, grading scheme, category weight/average, ungraded assignments. It also names the distinct alternate mode triggered by target_grade, so an agent can tell this apart from list_classes or list_assignments without opening a schema.

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?

Gives clear context for the two modes: default returns grade breakdowns, while supplying target_grade/class_id/target_id returns Helium's computed needed score. It never states when-not to use it or contrasts it with the listing siblings, but the mode-switch condition is explicit and the cross-references ('an id from get_grades', 'an id from list_assignments') show where prerequisite ids come from.

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