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

Annotations already indicate idempotent (true), destructive (false), and read-only (false). The description adds valuable behavioral nuance: the difference between leaving empty (keep current) and 'none' (detach), and the role-matching constraint. This goes beyond what annotations provide and clarifies the exact effect of each parameter value.

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 tightly-packed sentences with zero redundancy. The purpose is front-loaded, then the value semantics, then the constraint. Every sentence earns its place and no space is wasted on 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 mutation tool with no output schema and annotations covering safety, the description provides everything needed: the action, the parameter semantics, the special values, and the constraint. It even points to list_crew for getting valid member IDs. Nothing essential is missing.

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%, and each parameter's schema description already lists the same value options. However, the description adds the global constraint that a member can only take the step matching their own role, and it clarifies the overall semantics of batch assignment. This supplements the schema with missing business logic.

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 verb 'Set who edits, clips and posts' and the resource 'one or more assignments', explaining the production chain context. It distinguishes this from siblings like list_crew (which only lists) and update_assignment (which likely handles other assignment fields) by focusing specifically on crew roles.

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 gives clear instructions on how to use each parameter (empty, name/member_id, 'none') and references list_crew for valid IDs, plus a constraint about role matching. However, it does not explicitly state when to use this tool versus alternatives like update_assignment, nor does it describe when not to use it, leaving that differentiation implied.

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