update_submission

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

Annotations already signal mutation and idempotency. The description adds valuable behavioral detail: answers are a 'full replacement answers object,' not a partial merge, and the tool refetches the updated submission for the response. It also provides authorization and ownership constraints 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 compact and well-organized: a one-sentence purpose, concise parameter list, and explicit return value. Every sentence earns its place and there is no filler or repetition of schema details.

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?

With an output schema present and annotations covering idempotency, the description covers the necessary operational context: permission, ownership, full replacement semantics, and the refetched return value. It lacks an explicit 'use this for existing submissions, not new ones' contrast with submit_form, but the wording makes that distinction reasonably clear.

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?

With 0% schema description coverage, the description carries the full burden and does so well: form_id is numeric, submission_id is numeric and ownership-restricted, and answers is a full replacement object shaped like submit_form. The only gap is that the answer object's internal shape is deferred to submit_form rather than described directly.

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 uses a specific verb and resource: 'Update an existing submission's answers.' The word 'existing' distinguishes it from submission creation via submit_form cops. It is also clearly distinct from update_form because the target is a submission, not a form.

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 states clear prerequisites: 'Requires allowEditSubmissions on the form' and 'Must belong to the current user.' It implies the use case is editing an existing submission, though it does not explicitly name submit_form as the alternative for new submissions. This is clear context with minor room for improvement on alternative routing.

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