pp_volume_modify

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

The description discloses the key behavior that settings merge with existing values, meaning unspecified parameters remain unchanged. It also implies non-creation by 'existing'. However, without annotations, it lacks information about error behavior, required permissions, or side effects beyond merging.

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 with no redundant phrasing. It gets straight to the point and avoids 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?

The tool has a complex nested settings schema, but the description only covers the merge behavior and existing-volume prerequisite. It doesn't mention that actor_name is required or what happens if the volume doesn't exist. The schema provides rich detail on settings, but the description leaves gaps for successful 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?

Schema description coverage is low (33%), and the description doesn't explain individual parameters beyond stating that settings merge. The merge semantics clarify that the settings object is a partial update, but actor_name, unbound, priority, blend_radius, and blend_weight are left to the schema with minimal descriptions.

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 uses a specific verb ('Modify') and resource ('existing PostProcessVolume's settings'), clearly distinguishing from pp_volume_spawn and pp_preset. The phrase 'existing' indicates this acts on already-created volumes, not creating new ones.

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 usage for adjusting an already-created PostProcessVolume, but doesn't explicitly state when not to use it or name alternatives like pp_volume_spawn or pp_preset. The 'merge' hint is useful for partial updates, but no explicit when-to-use guidance is given.

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