bulk_edit_apply

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

Annotations already declare destructiveHint=false and openWorldHint=false, so the safety profile is partly covered. The description adds real behavioral context beyond that: the preview-then-confirm gating for multi-item edits, and the rationale that root folders are excluded because it would move files. It does not say whether applied changes are reversible or how partial failures are reported.

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?

Front-loaded with purpose, then the required workflow, then the exclusion, then examples. The middle sentence is dense but every clause carries instruction. The trailing example list is mildly decorative but grounds the trigger phrases.

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 16-parameter mutation tool this covers the critical decision path: when a token is needed, what the user must approve, and what is out of scope. Return values need not be described since an output schema exists. Only irreversibility/undo behavior is left unstated.

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%, so the baseline is 3; the description still adds meaning by explaining that confirmation_token is conditionally required depending on items-vs-filter selection and that the payload must match the previewed selection and changes. It does not clarify the filter/change pairing semantics of the 16 parameters beyond that.

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 a specific verb, resource, and scope ('Apply a change to many series or movies at once'), which immediately separates it from the read-only siblings and from bulk_edit_preview. The agent can tell what the tool does without opening the schema.

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?

Explicit when-to-use rules: bulk or filter selections must go through bulk_edit_preview and user agreement first, passing the confirmation_token with the same selection and changes; a single user-named item may be changed directly. It also names a hard exclusion (root folders) and gives worked examples.

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