Sixteen Bridges

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

The description adds real behavioral context beyond the annotations: name collision is a no-op that returns the existing bucket unchanged, and user confirmation is required before calling. What remains unstated is what the response looks like beyond 'that bucket' and whether the description field is ignored on collision — though 'unchanged' implies it is.

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: purpose first, confirmation requirement second, collision behavior third. Nothing is wasted and the most important information leads.

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 two-parameter create tool with full annotation coverage and no output schema, the description covers purpose, precondition, and idempotent behavior. The only gap is not naming update_bucket as the alternative for modifying an existing bucket.

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 both parameters are already documented in the schema (name: 'A short name, e.g. Work'; description: 'One line: what goes in it'). The description reinforces the intent of the description field with examples ('Work, Personal, Skills…') but adds no syntax or constraint detail beyond 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 ('Make a Sixteen Bridges bucket') and immediately explains what a bucket is for ('group bubbles'), which distinguishes it from update_bucket and delete_bucket among the siblings. An agent knows exactly what object is being created.

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?

'Ask the user first' is an explicit precondition for invocation, and 'A name they already have returns that bucket, unchanged' tells the agent not to pre-check for existence. It does not, however, route the agent to update_bucket when the intent is to rename an existing bucket.

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

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

Beyond the annotations, the description explains that deletion is initially a move to trash, that sixteenbridges_restore_bubble can undo it for 7 days, and that after that it is permanently deleted. The instruction to ask the user first adds important safety context for a destructive operation.

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, followed by recovery behavior and the safety instruction. No sentence is wasted.

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 single-parameter destructive tool with annotations covering safety and a fully described id schema, the description supplies the essential behavioral and recovery context. No output schema exists, and the return value is not necessary for correct invocation.

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?

The single id parameter is fully documented in the schema, including its pattern and the sibling tool to use for obtaining it. The description does not add parameter-specific meaning, which is acceptable given 100% schema coverage.

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 states a specific action and resource: moving a Sixteen Bridges bubble to the trash. It also distinguishes this from permanent deletion by naming the restore path and the 7-day window.

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?

It explicitly tells the agent to ask the user first and names sixteenbridges_restore_bubble as the recovery alternative, including the 7-day restore window. This is clear when/when-not guidance for a destructive tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description earns credit for adding the non-obvious side effect: bubbles survive in an unbucketed state and none are deleted. It stops short of saying whether the bucket deletion is reversible or whether an empty bucket is required.

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, action first, side effect second, safety instruction last. Every clause carries information an agent needs and nothing is padded.

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 one-parameter destructive tool with rich annotations, the essentials are covered: what it deletes, what survives, and that user confirmation is required. Missing only edge-case behavior such as whether deleting a non-empty bucket is allowed or how bubbles are later recovered.

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% and the single `bucket` parameter is fully documented in the schema, so the description adds no format, matching, or lookup detail. Baseline 3 applies when the schema carries the semantics.

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?

Specific verb (Delete) plus resource (a Sixteen Bridges bucket), immediately distinguishable from the sibling delete_bubble. The added note that bubbles are not deleted further separates it from any operation on bubbles themselves.

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?

'Ask the user first' gives a real precondition for invoking it, which is more than nothing. But it offers no explicit when-not guidance or comparison to update_bucket/move_bubbles for a user who just wants to empty or reorganize a bucket.

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

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

Annotations already declare this a safe, idempotent read, so the description's value is the paging contract: long bubbles arrive in 30000-character pages and the reply ends with the offset to read next. That is a genuinely non-obvious behavioral trait an agent must know to avoid treating a truncated page as the full content. It stops short of covering error handling or what the 'short header' contains.

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?

Two sentences, zero waste, and the identifier-plus-return-shape is front-loaded ahead of the pagination caveat. Every clause carries information an agent needs.

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?

With no output schema, the description must convey return shape, and it does: header, Markdown body, and a trailing next-offset. Pagination — the one thing most likely to cause a silent correctness bug — is covered. The vague 'short header' and the absence of any note on missing/invalid ids keep it from a 5.

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%, with per-parameter descriptions for id, offset, and max_chars, so the schema already does the heavy lifting. The description reinforces the offset/max_chars interplay by explaining the 30000-character default and continuation offsets, but adds no syntax or constraints beyond the schema. Baseline 3 is appropriate.

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 — 'Read one Sixteen Bridges bubble' — and describes what comes back: a short header followed by Markdown content. 'One' explicitly distinguishes it from the sibling sixteenbridges_list_bubbles, so an agent can route correctly without opening a 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?

The single-object framing implies usage (fetch a specific bubble by id), but the description never says when to prefer this over list_bubbles, nor when to continue paging versus re-reading. The routing hint it does provide lives in the schema ('From sixteenbridges_list_bubbles'), not the description.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description does add real value beyond them: the "newest first" ordering, the exact result shape, and the fact that results come "with their buckets and allowance." It stays silent on result volume behavior and the pagination mechanics, which are only inferable from the schema's cursor field.

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?

Two sentences, zero filler, front-loaded with the core action and result shape before the filter and entry-point cues. The parenthetical field list is dense but earns its place since there is no output schema.

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?

With no output schema, the description compensates by naming the six returned fields plus the bucket/allowance metadata. Ordering, both filters, and the entry-point recommendation are all present, which is everything an agent needs to call this list tool correctly.

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 schema already documents limit, query, bucket, and cursor thoroughly. The description reinforces query ("searches titles and contents") and bucket ("keeps to one") but adds nothing on limit or the cursor/"More:" pagination contract. Baseline 3 is appropriate when the schema carries the weight.

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 ("List the user's Sixteen Bridges bubbles") and even enumerates the returned fields, so the agent knows exactly what comes back. "Start here" hints at its role as the entry point among the thirteen siblings, but it never explicitly distinguishes itself from near-neighbors like sixteenbridges_get_bubble or sixteenbridges_list_deleted_bubbles.

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?

"Start here" establishes it as the default entry point and the two filter clauses (query searches titles and contents; bucket keeps to one) tell the agent how to narrow results. What's missing is an explicit exclusion — nothing says when to prefer get_bubble for a single item or list_deleted_bubbles for trash.

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

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

Annotations already declare this a safe, idempotent read, so the bar is lower, and the description still adds real value: a 7-day retention window, newest-first ordering, and the presence of an expiry timestamp per item. It stops short of saying whether items are purged immediately after expiry or how large the result set can get.

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 carrying verb, scope, ordering, and payload content with no filler. Everything an agent needs to decide is front-loaded.

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?

With no parameters, no output schema, and annotations covering the safety profile, the description covers what the tool returns and its retention boundary. A brief note on result size or pagination would close the remaining gap.

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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies no filtering input is available, which matters because an agent might otherwise expect date-range or bucket scoping arguments.

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 (list), resource (bubbles), and a narrow scope (deleted in the last 7 days, newest first). It implicitly contrasts with sixteenbridges_list_bubbles by restricting to deleted items, but never names that sibling, so separation requires the agent to infer it.

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 'deleted in the last 7 days' framing implies this is the recovery-discovery view, but there is no explicit routing such as 'use before sixteenbridges_restore_bubble' or 'for live bubbles use sixteenbridges_list_bubbles'. The obvious next step is left to inference.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the bar is lower. The description still adds real value: sort order ("newest first") and the fact that received items carry a new/unread flag, which an agent could not learn from the annotations.

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 front-loaded sentence with the verb first and zero filler. The trailing colon-list of returned fields is dense but earns its space; nothing is padded.

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, so the description has to sketch the return payload, and it does: counterpart identity, bubble ids, newness flags. The gap is pagination and the merged sent/received ordering, though the cursor parameter partly covers paging on the schema side.

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%, with both cursor and direction fully documented, so baseline 3 applies. The phrase "which received ones are new" loosely gestures at the direction=received mode but adds no syntax or pagination detail beyond 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?

Specific verb and resource ("List what the user shared and was shared on Sixteen Bridges") plus the returned fields: with whom, bubble ids, new flags. It implicitly separates itself from sixteenbridges_share_bubbles and sixteenbridges_list_bubbles by being the read-side of share relationships, but never names a sibling explicitly.

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 implies when to call it (you want the share ledger) but offers no explicit when-not or named alternative among the 12 siblings. The direction parameter's sent/received split is only explained in the schema, not here, so routing is left to inference.

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

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

Annotations already declare non-destructive, idempotent, non-read-only behavior. The description adds real value beyond them: the 50-item cap, atomic all-or-nothing semantics, and the guarantee that no other fields are modified. It omits permission/auth requirements, which keeps it from 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?

Three short sentences, front-loaded with the primary action, then the removal case, then the atomicity/limit guarantee. No filler or redundancy.

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, but the description discloses the two behaviorally important outcomes an agent needs: atomic success/failure and that no other bubble attributes change. A brief note on return/error shape would close the remaining gap.

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%, and both parameters are fully documented in the schema, including the "none" sentinel and the ID pattern. The description's mention of "none" and the 50 limit restates schema constraints rather than adding new meaning, so baseline 3 applies.

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 ('File ... in one of the user's buckets') and the inverse operation ('take them out with bucket "none"') on a named resource. This clearly separates it from sibling mutations like delete_bubble, update_bubble, and update_bucket.

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 usage context: assigning vs. clearing membership via the literal "none" value, which is the key decision point for this tool. It stops short of explicitly naming sibling alternatives (e.g., whether update_bubble could also change bucket), so it is clear but not fully routing.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description needn't restate them. It adds the useful context that the target must be a trashed bubble, but says nothing about what happens on a name collision, whether the bubble returns to its original location, or what error occurs for a non-trashed id.

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 with no waste, front-loading the action and resource before the parenthetical id source. Nothing could be removed without losing information.

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 one-parameter mutation with full annotation coverage and no output schema, the description covers what to call it with and where the id comes from. Missing only the post-restore outcome (destination, collision behavior), which is a minor gap given no output schema exists to explain returns.

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?

Only one parameter, fully documented in the schema (100% coverage) including a regex pattern. The description repeats the id provenance already stated in the schema field description, adding no new format or constraint detail. Baseline 3 applies.

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 (restore) and resource (bubble) plus the scope 'back from the trash', which distinguishes it from sixteenbridges_delete_bubble and sixteenbridges_get_bubble. It stops short of explicitly naming the inverse sibling, but the operation is unambiguous.

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?

Names the prerequisite source of the id (sixteenbridges_list_deleted_bubbles), which tells the agent when this tool applies: only for bubbles already in the trash. No explicit when-not or failure-case guidance, so it falls short of a 5.

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

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

Annotations already cover the safety profile (write, non-idempotent, non-destructive). The description adds the return value (new id) and instructs the agent to set source to its own app identity, but omits an idempotency warning (e.g. duplicate saves create separate bubbles), which is a notable gap even with annotations.

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?

Two tight sentences front-load purpose and then details. Every phrase earns its place, and there is no redundancy.

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 simple creation tool with annotations covering safety and a schema covering most parameters, the description is mostly complete: it states the return value and gives source/bucket guidance. Missing idempotency context and explicit bucket optionality are minor gaps that structured fields partially cover.

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 80%, so baseline is 3. The description adds useful meaning for `source` (set to the app you are, clarifying the enum choice) and `bucket` (pick by description fit), plus reiterates the title length limit. It does not clarify the optional `label` parameter, which the schema handles.

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 (save) and resource (bubble), and implies creation by saying it returns the new id. It doesn't explicitly differentiate from update_bubble, which exists as a sibling for editing, so it stops short of a 5.

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 parameter-level guidance (set source to your app identity, choose bucket by description fit), but offers no explicit when-to-use versus update_bubble or other alternatives. Usage is implied by 'save context' rather than spelled out.

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

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

Annotations declare the mutation profile (readOnly=false, openWorld=true, non-idempotent, non-destructive). The description adds a genuinely new trait not in structured data: atomicity ('All arrive or none do'). It does not address reversibility, permission requirements, or failure modes, so it falls 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?

Three short sentences, each carrying distinct information (what, guardrail, atomicity), with the core action front-loaded. 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 2-parameter mutation with full schema coverage and no output schema, the description covers action, scope, guardrail and atomicity. It omits what a successful response looks like (e.g., whether share ids or a record are returned), a minor gap for an outbound share 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 description coverage is 100%, so both parameters are already documented, and the description only echoes the 'exact address' constraint and the 20-item ceiling that the schema already enforces via maxItems. Baseline 3 is appropriate.

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 ('Send copies'), the resource ('Sixteen Bridges bubbles'), the destination type ('another Sixteen Bridges account') and channel ('by email'), with a bounded scope ('up to 20'). This is clearly distinguishable from siblings like list_shares or move_bubbles 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?

'Only when the user asks, to the exact address they give' gives an explicit trigger condition and a constraint on the recipient value. It does not name an alternative tool (unlike the high-calibration example), but no sibling overlaps meaningfully, so the routing risk is low.

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

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.

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

Annotations already declare this is a non-readOnly, idempotent, non-destructive, closed-world mutation, so the safety profile is covered. The description adds genuinely useful behavior the annotations do not: an empty description string deletes the description rather than being a no-op. It omits whether at least one of name/description must be supplied and how name collisions are handled.

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 with the resource and the two mutations front-loaded, and the one non-obvious edge case in a tight parenthetical. Nothing is wasted.

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 three-parameter, fully documented, non-destructive update with annotations covering the safety profile and no output schema to explain, this is sufficient to call correctly. The only residual gap (must at least one field be set?) is minor given full schema coverage.

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 each parameter already has a description and the baseline would be 3. The description adds real semantics beyond the schema by explaining that an empty 'description' value clears the field, which the schema alone does not convey.

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?

Specific verb ('Rename') plus resource ('a Sixteen Bridges bucket'), and it names the two mutable fields (name, one-line description). It does not explicitly contrast itself with siblings like sixteenbridges_update_bubble, but the resource word 'bucket' vs 'bubble' carries the distinction well enough.

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 by the two enumerated mutations and the parenthetical rule that an empty description clears it. There is no statement about when to prefer this over a sibling, and no note on what happens if an agent calls with only 'bucket' and no changes.

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