Stage Start

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

With no annotations, the description carries the disclosure burden and does well: it states that an existing server is reused, describes the host default, notes tailscale for headset access, and explains that session files go to <scenes>/_stage/. It does not cover permissions, port conflicts, or process lifecycle details, but it adds substantive behavioral context beyond the schema.

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 front-loaded with the core action and address reply, then adds scoping and parameter context. It is dense but each sentence carries useful information. Slightly more structure or line separation could improve readability, but there is little waste.

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 5-parameter server-start tool with no annotations and no schema descriptions, the description provides substantial completeness: purpose, reuse behavior, host/headset setup, footage location, esbuild bundling, and session file location. The output schema can cover the return address, and the main remaining gap is the port parameter.

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 0%, so the description must explain the parameters. It covers scenes as the folder of scene subfolders, host as defaulting to 127.0.0.1 with tailscale serve for headset use, footage as the location for headset recordings from upload.html, and esbuild as a path to the esbuild package. It omits meaningful explanation of port (default 8862), so it does not fully compensate for the coverage gap.

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 specific action: start the stage server for a song's scenes folder and return the address to open. It also explains that each subfolder with a scene.glb is a scene. It does not explicitly contrast with siblings like stage_restart or stage_status, but the purpose is unambiguous.

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?

It explains the context for use: open the returned address on desktop or in a headset, with host defaulting to 127.0.0.1 and tailscale serve needed for headset access. It also notes that an existing server for the same folder is reused. It does not explicitly state when to use stage_restart or stage_status instead, but the usage context is clear.

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