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

Annotations already declare non-readOnly, non-destructive, non-idempotent, non-openWorld, so the safety profile is covered. The description adds genuinely new context: editor-level authorization is required, concurrent edits are mediated by another collaborator's edit lease, and media is left untouched. It does not explain the practical consequence of non-idempotency (e.g. repeated calls or partial-failure behavior), leaving one gap.

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, front-loaded sentences with zero filler: capability first, then preconditions, then scope exclusion. Every sentence earns its place.

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 mutation tool with no output schema and 4 params, the description covers access, concurrency, and scope, but omits the highest-value unknown for an updater: whether fields not supplied are preserved or cleared. Without that, an agent cannot safely predict the effect of a partial update.

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 only 25% (just project_id is documented), so the description must compensate. It does enumerate the three editable fields, which is some value, but adds nothing about limits (e.g. title maxLength 180, summary maxLength 4000), whether omitted fields are left unchanged (patch semantics), or that visualStyle reuses the summary shape. Partial compensation only.

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 (Edit) plus the exact editable fields (title, summary, visual style) on a named resource, and the closing clause 'Does not regenerate media' distinguishes it from generation siblings like create_generation_request. It stops short of naming a sibling alternative directly, so it is clear but not fully differentiated.

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 concrete preconditions — 'Requires editor access' — and a usage constraint — 'respects another collaborator's active edit lease' — plus a negative scope statement about media regeneration. No explicit alternative tool is named for cases where the agent lacks editor access, so guidance is strong but not exhaustive.

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