Create, update, or delete a user segment

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

With only destructiveHint=true provided, the description carries real weight: it explains conditional writes via ifMatch (412 on concurrent modification, re-read and re-apply), that ifMatch is rejected on create/delete, that conditions replaces the entire list, and that an empty description string clears the field. These are non-obvious API behaviors beyond what annotations declare.

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?

Dense but every clause earns its place: action requirements first, then the concurrency/etag rule, then the negative constraint on ifMatch. No filler and the most decision-relevant content 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?

Output schema exists so return values need not be described. For an 8-parameter mutation tool with destructiveHint, the description covers the mutation surface, per-action parameter requirements, destructive replacement semantics, and optimistic-concurrency error handling.

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, but the description adds cross-parameter meaning the schema cannot: which parameters are required per action value, and the create/update/delete-specific rejection of ifMatch. It also reinforces the replace-whole-list semantics of conditions.

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?

Opens with a specific verb+resource ('Manage reusable user segments') and immediately distinguishes it from siblings by noting segments are referenced by userSegmentId by targeting rules. The title and description together make clear this is the write/mutation counterpart to list_segments/get_segment.

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 explicit per-action requirements (create needs key+name; update needs segment+changes; delete needs segment) and routes the agent to get_segment for the etag used by ifMatch. It stops short of saying when to prefer this tool over alternatives in a workflow sense, but the action-level routing is clear and actionable.

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