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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds real behavioral context beyond them: the section's score is recalculated as a side effect, and reversal restores the previous part points. That side-effect disclosure is exactly what an agent needs before mutating a grade. It stops short of stating permission requirements or whether the override is reflected downstream in released results.

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 short sentences, front-loaded with the mutation and its scope, then the recalculation and reversal consequences. Only 'as on the website' is wasted words; otherwise every sentence carries 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?

An output schema exists, so return values need no explanation, and the recalculation/reversal notes cover the main behavioral risks of this mutation. But with 7 required parameters at 29% schema coverage and no description of the 'part' identifier semantics, an agent still lacks enough guidance to construct a correct call confidently.

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 only 29% (three ID fields documented, part/points/reason/reasonCategory not), so the description must compensate. It partially does by implying points, the single 'part' target, and the teacher's reason/reasonCategory pairing, but says nothing about the format or valid range of 'part' or how assignmentId/submissionId/itemId relate to each other.

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 names a specific verb (changes), resource (points on one rubric part of an AI-scored FRQ in a submission), and scope (a single rubric part). This distinguishes it from the sibling override_essay_score, which operates on the whole essay, though it doesn't name that sibling explicitly. The trailing phrase 'as on the website' is vague filler that doesn't add scope information.

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 context ('AI-scored FRQ', 'one rubric part', teacher's reason required) implies when this tool applies, and the reversal sentence hints at the undo path. However, it never states when to choose this over override_essay_score or score_submission, nor any prerequisites such as whether the submission must already be scored or the assignment published.

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