Patch script events

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

No annotations are provided, so the description carries full burden. It explains sequential operation application (indices reflect state after prior ops), atomic persistence to disk, and the dialogue width budget check with force override. Missing details on error handling or permissions, but the level of detail for a mutation tool is good.

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 concise sentences, each adding unique value: operation definition, sequential behavior, persistence and budget constraints. No redundant or unnecessary 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?

Given the tool's complexity (4 params, nested objects, no output schema), the description covers core behaviors: operation types, sequential index interpretation, atomic writes, and budget enforcement. Missing return value info (expected since no output schema) and error handling details, but fairly complete for a patch tool.

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 50%. The description adds meaning for force and widthBudget (skip budget check/override char limit) and explains operation semantics (index state after prior ops). However, the complex locator parameter is not elaborated beyond mentioning it in the context of persisting to a scene or custom event. The operations structure is partially detailed, but the locator remains abstract.

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 tool applies operations (insert/replace/delete) to a ScriptEvent[] array. It specifies what it does, the operation types, and contrasts with unsupported full-array replacement, distinguishing it from sibling tools like read_script or delete_custom_event.

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 provides context on when to use force (skip budget check) and notes that full-array replacement is unsupported (use delete+insert). However, it does not explicitly state when to prefer this tool over alternatives like delete_custom_event, though sibling names imply such distinctions.

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