update_assignment

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

With no annotations, the description carries the transparency burden. It discloses partial-update semantics ('Only include fields you want to change') and cross-resource compatibility, both non-obvious behaviors. However, it doesn't mention permissions, side effects on discussions/quizzes, or error conditions, preventing a higher score.

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 concise sentences with front-loaded purpose, then usage detail, then a pointed alternative. Every sentence adds value and there is no redundancy.

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?

Given the tool's complexity (12 parameters, no annotations, no output schema), the description covers key aspects: purpose, usage, scope, and alternative. Missing return/response details and permission requirements, but these are less critical for an update tool and the description is otherwise quite 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 coverage is 67%, so the schema handles most parameters but leaves name, position, published, and points_possible undescribed. The description adds general semantics about partial updates but doesn't detail these missing parameters. It partially compensates but doesn't fully bridge the gap.

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 clear action ('Update an existing assignment') and resource, and explicitly differentiates from sibling tools like update_assignment_dates by noting it also handles graded discussions and New Quizzes. This makes the tool's purpose unambiguous and distinct.

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 provides explicit usage guidance: 'Only include fields you want to change' tells the agent how to invoke it, and 'For date-only changes, prefer update_assignment_dates' offers a clear alternative. It also states that it works for other resource types, helping decide when to use it instead of update_discussion or update_new_quiz.

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