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

With no annotations provided, the description carries the behavioral burden and does well by disclosing that the photo is never changed and earlier versions are kept. It also states that an empty shapes list clears the markup. It does not cover permissions, validation failures, or return behavior, which are meaningful gaps for a mutation tool.

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 three focused sentences with the main action and coordinate system front-loaded. It includes only relevant details about versioning and clearing, with no filler or repetition.

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?

For a two-parameter mutation tool with no annotations and no output schema, the description covers the key behavioral context: what is saved, coordinate system, non-destructive versioning, and clearing semantics. It is missing expected response details and authentication or permission requirements, but the core call semantics are present.

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 low, so the description must compensate. It adds useful meaning for the shapes parameter by listing shape types, explaining 0..1 photo coordinates with top-left origin, and noting that an empty list clears markup. It still leaves media_id unexplained and does not mention limits such as maxItems or stroke width bounds.

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 states the verb and resource: save markup over a photo as a new layer version. It also enumerates supported shape types and coordinate semantics. It does not explicitly differentiate from the sibling media_getMarkup, so sibling routing is only implied by the Save/Get names.

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?

Usage is implied by the save operation and the note that an empty list clears markup, which gives some context. However, the description does not state when to use this versus media_getMarkup, media_requestUpload, or other media tools, nor does it mention prerequisites such as having an existing photo.

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