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

The annotations already flag this as destructive and non-idempotent, so the description's job is supplementary. It does add real value by disclosing what is destroyed — 'replace its content' signals full overwrite versus the additive 'append' mode — which is exactly the kind of mutation-severity context annotations cannot convey. It stops short of stating irreversibility or permission requirements.

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?

A single sentence, front-loaded with the three operations, with the one bit of qualifying detail (the append shortcut) placed inline rather than as an afterthought. No filler.

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 4-parameter mutation tool with full schema coverage, live annotations, and no output schema, the description covers all modes and their effects. The remaining gap is whether the call returns the updated bubble and whether title/content/append may be combined — minor but worth noting for a destructive operation.

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 schema already documents all four parameters and the baseline is 3. The description earns an extra point by explaining append semantics beyond the schema text: adding to the end without resending the whole bubble, which clarifies the practical trade-off against `content`.

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 names a specific verb (update) plus resource (Sixteen Bridges bubble) and enumerates the three mutation modes: retitle, replace content, or append. This clearly separates it from siblings like move_bubbles, save_bubble, and update_bucket, which operate on different objects or semantics.

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 rather than stated: the parenthetical 'no need to send the whole bubble again' tells the agent to prefer `append` for additions rather than rewriting. However, there is no explicit when-to-use guidance, no mention of choosing this over save_bubble or create_bucket, and no statement of whether multiple fields can be combined in one call.

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