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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavior: the zero-revision upsert semantics and the idempotent-retry contract for operation_id. It omits what an existing variant loses on overwrite and what the required read_skills and expected_catalog_version preconditions actually gate.

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?

Three short sentences, front-loaded with the action and followed by the two most decision-relevant rules. No filler, though the terseness borders on under-specification given the tool's nested payload.

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 destructive, idempotent, nested-payload mutation with 5 required parameters, the description covers only revision and retry semantics. An output schema exists so return values need no explanation, and the schema carries some parameter docs, but the description says nothing about the work_id scoping, the request_key role, or when publication_proposal_id is needed.

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 50%, with read_skills and expected_catalog_version documented inline but work_id, arguments, request_key, and publication_proposal_id largely bare. The description adds real meaning for expected_revision (exact saved revision, zero = create) and operation_id (reuse on uncertain response), which are the two highest-risk parameters, but leaves the remaining parameters to 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?

"Save a GenAds variant" gives a specific verb plus resource, and the phrase "zero creates a new resource" clarifies that this is an upsert rather than a pure update. It does not name or distinguish itself from near-siblings such as native.save_genads_concept, save_genads_pack, or save_genads_media, so an agent must infer the boundary.

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 gives concrete operational guidance for two parameters: pass the exact saved revision, and pass zero to create a new resource; also reuse operation_id after an uncertain response (retry guidance). It never says when to choose this tool over the other save_genads_* siblings, nor does it state prerequisites such as requiring an accepted session bootstrap.

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