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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, but the description adds genuinely non-derivable behavior: previews idle-stop on their own, calling stop_preview frees resources sooner, the URL is public HTTPS and pre-pinned to a mock dataset (maker's pick, else vertical's). It does not cover auth/permission needs or concurrency behavior when a preview is already live beyond the parenthetical 'reconcile a running one'.

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 primary action and return value are front-loaded, and the lifecycle guidance follows in sequence with no filler sentences. It is somewhat dense with em-dashed parentheticals (e.g., 'sushi, not restaurant') that add flavor but mild reading overhead.

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?

No output schema exists, yet the description covers the return value (public HTTPS URL), the dataset-pinning rule, the sync trigger, and the resource lifecycle, which is what an agent needs to invoke it correctly. Remaining gaps are the undocumented flowId and the relationship to the sibling preview-status/sync tools.

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% and the single required parameter flowId is never explained in the description. The text refers to 'this flow's mock dataset' and 'the flow's current files' but never states what flowId must contain (ID vs name) or where to get it, so the description does not compensate for the documentation 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?

Specific verb+resource with return value stated: 'Boot the flow's server-side preview sandbox (Vite dev server)... and return its public HTTPS URL'. It names the sibling it is not in the lifecycle case (stop_preview) and the follow-up trigger (call again after write_flow_files). It stops short of disambiguating from flow_sync_preview and flow_get_preview_status, despite the title's '(or sync)' overlapping with a dedicated sync sibling.

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?

Gives clear operational context: open the URL in a browser, call again after write_flow_files to sync, and call stop_preview when done to free resources sooner. That is real when-to-use guidance with one explicit alternative. It omits any routing guidance versus flow_sync_preview/flow_get_preview_status, so the agent must guess which of the overlapping preview tools to pick.

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