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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds real behavioral context beyond them: partial-update semantics ('only what you pass changes'), the URL-backed media storage caveat (deleting the file breaks the image), fallback behavior suggestion via the remove param, and admin/access gating. It also notes the return shape mirrors riddle_template_create.

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 core action and the partial-update rule are front-loaded, and every sentence carries information. The trailing access-condition sentence is dense and cryptic ('without full access only for a Riddle whose origin.writableByThisKey is true'), relying on a reference link rather than plain language.

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 substitutes by saying the return matches riddle_template_create. It covers permissions, image lifecycle, and the immutability of content, but leaves open edge behavior such as passing remove and coverMediaId together, or what happens for an unknown id.

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 coverage is 100%, so the baseline is 3; the description earns above that by explaining the mediaId workflow (upload first via media_upload_link) and the storage-by-URL consequence for coverMediaId/iconMediaId, which the schema only gestures at. It does not add detail on how remove interacts with coverMediaId/iconMediaId in the same call.

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 template's title, gallery image, icon) and immediately scopes it against siblings by noting the template's content cannot be changed and that riddle_template_create should be used instead. An agent can distinguish this from riddle_template_create, riddle_template_get, and riddle_builder_update without reading the 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?

Explicitly names the prerequisite workflow for images (media_upload_link into the template's project, then pass the reported mediaId), the alternative for content edits (create a new template from the edited Riddle), and the permission condition (public templates only by Riddle admins; otherwise requires origin.writableByThisKey). When-to-use and when-not-to-use are both present.

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