media_set_update_asset_titles

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

Adds behavioral details beyond annotations: GET-then-PUT-full-array dance, preservation of other assets, rejection of unknown ids, and idempotency. The description aligns with idempotentHint=true and destructiveHint=false without contradiction.

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?

Description is long but each sentence adds necessary context, particularly the safety warning and behavioral guarantees. Structured with a clear WHY section that justifies its length.

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?

Covers all user-relevant aspects: purpose, safety, input constraints, idempotency, and edge cases (empty titles). No output schema exists but description provides enough context for a mutating tool without needing return details.

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?

Adds meaning for `titles` with example mapping, constraint that keys must be existing asset ids, and empty-string clearing semantics. While `site` lacks description, the tool's core parameter is thoroughly explained 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 specific verb+resource: 'Safely edit one or more asset titles in a media_set (gallery).' Clearly distinguishes from siblings like media_set_set_assets by explaining it's for title-only edits, and contrasts with dangerous partial PUT.

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?

Provides explicit why: 'WHY THIS TOOL' explains that PUT /media_sets/{id} is replace-not-merge and partial edits silently drop assets. It gives the safe scenario and warns about unknown ids, so the agent knows exactly when to use it.

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