set_actor_folder

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

Goes well beyond the annotations (readOnly=false, destructive=true, idempotent=true) by disclosing that the move is undoable, marks the level dirty but is not saved, and that name/label matching takes the first match. These are exactly the operational traits an agent needs before mutating editor state.

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 action and its constraints are front-loaded in the first sentence, with behavior and return shape following. The 'returns the internal actor_name and folder_path as given' clause is then repeated verbatim in the 'Returns:' block, a minor redundancy that keeps it just under top marks.

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?

With no output schema, the description supplies the return shape inline, covers persistence state (dirty, not saved, undoable), the identifier-matching rule, and the root-move edge case. Nothing needed to invoke it correctly 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 coverage is 100%, so the schema already documents both parameters and the empty-path behavior. The description still adds value by noting the 'first match' resolution rule for actor_name, which the schema does not state, but adds nothing new for folder_path 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?

States a specific verb and resource ('Move an editor-world actor ... into an outliner folder') and clarifies the identifier semantics (internal name or label). It also names the sibling that reads the value back (get_actor_folder), letting an agent distinguish set vs. get without opening either 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?

Provides clear operating context: empty folder_path moves the actor to the root, and get_actor_folder is the read-back counterpart. There is no explicit 'when not to use' or alternative-routing statement beyond the read-back hint, so it falls short of a full 5.

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