Plan Workflow Conversion

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

Annotations already declare readOnlyHint=true and openWorldHint=true; the description reinforces this with the concrete guarantee that nothing is written to the instance or to disk, which is useful because the tool otherwise connects to a live instance. It also discloses the return shape (text) and the three artifacts produced, though it does not mention auth requirements or how it behaves if the workflow is untranslatable.

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 a colon that enumerates the three outputs, followed by a short read-only clause. No filler, no restatement of the title, and the most decision-relevant content (what you get back) comes first.

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?

With five well-documented parameters, no output schema, and safety covered by annotations, the description supplies what is still missing: the nature of the output (text) and its contents. The only real gap is sibling differentiation against outline_workflow/export_workflow in a crowded workflow tool family.

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 100%, so version, instance, workflow, directory, and include_fluent are all documented in structured form. The description only implicitly ties include_fluent to the Fluent skeleton and directory to the layout, adding marginal meaning beyond the schema — the baseline 3 applies.

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 gives a concrete verb and resource ("Plan the move of a legacy workflow to Flow Designer") and enumerates exactly what the plan contains: activity-to-step mapping, script-retention analysis, and a Fluent skeleton returned as text. That is far more specific than the sibling outline_workflow or get_workflow, though those siblings are never named, so an agent must infer the boundary itself.

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?

Usage is implied by the conversion framing, and the read-only statement signals it is a safe planning step before any actual change. However, there is no explicit instruction on when to pick this over outline_workflow, export_workflow, or get_workflow, and no stated prerequisites or exclusions.

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