prepare_review_workspace

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

No annotations exist, so the description carries the full behavioral burden and largely fails. It implies a write side effect ('create the separate edit store') but does not say where files are written, whether existing stores are overwritten, whether it requires an initialized run, or what the returned launch command is for. Only the barest hint of mutability is conveyed.

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?

A single front-loaded sentence with no filler, which is structurally clean. But the sentence is so terse that it omits key qualifying information rather than packing it efficiently, verging on under-specification.

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?

The output schema covers the return value, so that need not be described. Still, for a three-parameter mutation-adjacent setup tool with no annotations and zero schema coverage, the description is far too thin to call correctly — it never explains the required run_dir or the effect of workspace_dir.

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 0%, so the description must compensate, yet it explains none of run_dir, workspace_dir, or port. At best, 'separate edit store' faintly gestures at workspace_dir and 'launch command' at port, but no format, default behavior, or relationship is stated.

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 verb 'Create' and object 'separate edit store' identify the action, and 'return a local review launch command' hints at output. However, 'edit store' and 'review launch command' are internal jargon with no explanation, and the boundary versus siblings like start_review_server or prepare_cad_bundle_workspace is not made explicit. An agent can guess it is a setup step preceding the review server, but only by inference.

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?

No when-to-use, prerequisites, or when-not guidance is given. With siblings such as start_review_server, build_qgis_review, and prepare_cad_bundle_workspace present, the description never clarifies which of these should be called first or instead. Usage must be inferred entirely from the name.

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