review_submission_user_s_assessment_submission

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

The description goes well beyond the annotations by disclosing non-idempotency, server-side auth injection, rate-limit throttling, retry behavior on 429/5xx, and detailed HTTP response/error semantics. This is especially valuable since annotations only provide basic hints like readOnlyHint=false and idempotentHint=false.

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 well-structured and front-loaded: it immediately states the write nature, endpoint, and purpose, then organizes behavior, parameters, returns, and usage into clear labeled sections. Each sentence provides actionable information without unnecessary filler.

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?

The description is complete for a tool with no output schema. It covers the write behavior, idempotency implications, authentication model, rate limits, retries, HTTP return format, error mappings, and the necessary pre-call read check. The nested body schema handles the remaining payload details.

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 100%, so the schema already documents the parameters and their nested fields. The description adds meaningful invocation guidance by clarifying that the entire JSON payload goes into the single body argument, is forwarded verbatim, and that the endpoint expects a body even though the schema marks it optional.

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 operation: reviewing a user's assessment submission by updating grades and feedback and recalculating grades. It also labels the tool as a WRITE operation that creates data, and separates it from the related read-only Assessment tools get_assessment_responses and get_form_responses.

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 explicitly states when to use the tool: only when the user asked to create this review. It also instructs the agent to first check with a read tool that the target exists and the record is not already present, providing a clear precondition and guarding against duplicate actions.

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