save_scene

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses an important safety behavior: it refuses to overwrite a scene open in another inactive tab, and clarifies the save-as option. However, it does not mention what happens on success, whether it overwrites the current file when no path is given, or any error conditions, leaving some gaps in transparency.

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 description is a single, well-structured sentence that front-loads the core purpose ('Save the currently edited scene') and then adds the optional save-as and refusal behaviors. Every word earns its place; there is no verbosity or repetition.

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 simple tool with one optional parameter and no output schema, the description is largely complete. It covers the main action, the optional save-as mode, and a key safety constraint. It lacks details like return values or error handling, but these may not be critical for a save operation given the simplicity of the 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?

The input schema defines a single 'path' parameter with a default value but no description, giving 0% schema coverage. The description compensates by explicitly explaining the parameter: 'optionally to a new res:// path (save-as)'. This clarifies that the path is for save-as and is optional, but it doesn't elaborate on what happens when path is empty, which is implied. Overall, strong compensation for a single parameter.

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's function: 'Save the currently edited scene'. It specifies the exact resource (currently edited scene) and action (save), and distinguishes it from sibling tools like open_scene, create_scene, and delete_scene by its focus on saving rather than creating, opening, or deleting scenes.

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 gives clear context: it is for saving the currently edited scene, with an optional save-as behavior via a new res:// path. It also mentions a constraint (refuses to overwrite a scene open in another inactive tab), which helps the agent avoid errors. However, it does not explicitly mention when not to use this tool or name alternatives, so it falls short of a 5.

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