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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real value beyond that: it discloses that uploaded screenshots are left untouched, that new previews and warnings are returned, and that the open_url from finish_project resolves to the new version. It does not state auth requirements for update_project itself, which keeps it short of a 5.

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 mutation scope is front-loaded in the first sentence, followed by the routing rules. It is dense and every clause carries information, though the multi-clause edit_asset routing sentence is heavier than it needs to be and could be split.

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?

No output schema exists, and the description compensates by stating the return (new previews and warnings) and the downstream consequence for finish_project's open_url. Combined with full schema coverage and the edit_asset fallback path, an agent has everything needed to call this correctly and to know when to stop.

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 100%, so the baseline is 3. The description maps its mutable fields onto the parameters (screen_name, headline, background_color, frame_color, device) but adds no syntax, format or default information beyond what the schema already documents in detail (e.g. the #RRGGBB pattern and headline length guidance live 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?

States a specific verb and resource ('Changes a screenshot set create_project made') and enumerates exactly what is mutable: screen name, headline, background colour, frame colour, device. It explicitly distinguishes itself from create_project (which made the set) and from edit_asset (which handles everything else), so an agent can route without opening any schema.

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?

Gives explicit when-to-use and when-not-to-use: use this only before the user saves; for anything more (device placement, size, fold, text styles, pieces, another canvas) use edit_asset with the same project_handle; a set already saved must be changed via edit_asset by asset_id. Alternatives and the conditions that select them are named outright.

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