submit_annotation_changes

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

Goes well beyond the annotations by disclosing the actual effect (a blue review badge, no geometry change), the atomicity guarantee ('the whole batch is validated before status writes'), retry semantics for identical revision/summary, and the required recovery path on conflict. These complement rather than restate readOnly=false, idempotent=true, destructive=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?

Front-loaded with the action in the first sentence, then preconditions, safety notes, exclusions, and error recovery in short blocks; every sentence carries information. The idempotency sentence partly echoes the idempotentHint annotation and could be tightened, but nothing is 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?

Covers invocation, preconditions, side effects, idempotency, and conflict recovery, which is strong for a batch-mutation tool with an idempotent, non-destructive profile. With no output schema, it stops short of describing what a successful call returns (e.g., per-item validation results), which is the one remaining gap.

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 0%, so the description must carry the load and does: it explains each nested field's source (scene_name, marker_id, expected_revision taken from the pre-edit read) and the intent of summary ('brief summary of actual completed work'). It also adds a batch-size constraint (1..200) that appears nowhere in 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?

Names a specific verb and resource ('mark 1..200 affected annotations as MODIFIED') and scopes it with a concrete bound and a triggering condition ('After model edits succeed'). The negative list ('does not change geometry, approve work, overwrite user notes') separates it cleanly from adjacent write-style actions and from the read-only sibling get_surface_annotations.

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?

States when to invoke it ('after model edits succeed'), what to pass and from where ('from the read before editing'), and how to recover from failure ('a revision conflict requires rereading and reconciling'). It gives clear context but never explicitly names an alternative tool or a case where the call should be skipped.

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