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

Annotations already declare destructiveHint=true, so the mutation nature is known. The description adds behavioral context: it notes the update is for existing segments, suggests inspecting before changing to avoid unintended overwrites, and implies partial updates (only name or definition changes if only one is provided). It does not explicitly state that the definition is fully replaced when provided, but that is covered in the schema's parameter description. Given the annotations, this is adequate.

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 description is two sentences with no filler. It front-loads the primary purpose, then gives the essential workflow and constraint. Every word earns its place, and it avoids redundancy with the 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?

For a tool with a complex nested definition parameter, the description does not explain the DSL, but that is fully covered by the schema. The description provides the necessary workflow (get → update → preview) and the constraint on parameters. It lacks an explicit warning about full replacement, but that is in the schema. Overall, an agent has sufficient information to call the 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 coverage is 100%, so each parameter is fully documented. The description adds a cross-parameter constraint not present in the schema: 'At least one of name or definition must be provided.' This is valuable semantic information that helps the agent avoid invalid calls. It also provides context on how parameters relate (e.g., inspecting before update), which goes 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?

The description clearly states the action ('Modify an existing segment's name and/or filter definition') with a specific verb and resource, and it distinguishes from siblings like create_segment and get_segment by implying this is for updates only. It also specifies the condition that at least one field must be provided, making the tool's role 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?

Provides explicit workflow guidance: call nevent_get_segment first to inspect the current definition, and nevent_segment_preview afterward to confirm the audience count. It also implies when not to use this tool (when creating a segment) and the constraint that at least one of name or definition must be provided. This 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.