Create scene

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

Annotations indicate readOnlyHint=false, so the description correctly implies mutation. It adds behavioral context beyond annotations by detailing side effects: templateName copies settings but not map contents or id, folderPath creates missing folders, and journalIdentifier links a journal. However, it doesn't disclose potential side effects like what happens to existing scenes or whether the scene is activated by default (though 'activate' parameter exists). With no output schema, some return behavior is opaque, but the description covers the main behavioral traits.

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 concise and front-loaded: the first sentence states the core purpose, followed by short, specific behavior notes for key parameters. Every sentence adds value, covering revealing details about templateName, folderPath, and journalIdentifier without unnecessary verbosity. It's well-structured for an agent to parse quickly.

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 (13 parameters, no output schema, no enums), the description covers many important defaults and behaviors (grid measuring, template copying, folder creation, journal linking). It lacks explicit mention of the return value or confirmation of creation, but the schema and annotations provide basic context. For a complex creation tool, it's nearly complete, with minor gaps around error handling or what happens on invalid paths.

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 has 100% description coverage for all 13 parameters, each with a clear description. The tool description adds extra meaning by explaining how parameters interact: width/height default to measured values, templateName copies settings but not map/id, folderPath creates missing folders, and journalIdentifier links a journal. This goes beyond the schema's individual descriptions, but the schema already provides strong parameter semantics, so this isn't a full compensation need.

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 states that it creates a scene from an image or video in the data directory, with a clear verb and resource. It also explains key behaviors like grid fitting and template copying, which distinguishes it from other scene-related tools (e.g., update-scene, delete-scene). However, it does not explicitly name any sibling tool for contrast, so it doesn't fully differentiate from siblings.

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 clear context on when to use this tool—creating a new scene from media files. It implies usage for battlemaps or location pictures and explains how parameters like templateName and folderPath work. It does not explicitly state when NOT to use it or name alternative tools (e.g., for updating scenes), but the purpose is clear enough for an agent to select it correctly.

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