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

With no annotations, the description must carry the full behavioral burden. It does disclose the output (draft + builder URL) and the deprecated status, which adds context. However, it does not state whether the tool mutates state, requires any permissions, or has side effects. The description only hints at behavior through the draft/URL mechanism, leaving the safety and state-change profile ambiguous.

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 overall, but it contains redundant deprecation text: '[DEPRECATED — migrate to a non-deprecated version of generate_flow] DEPRECATED — use generate_flow@2.0.0...' repeats 'DEPRECATED' unnecessarily. Otherwise, the structure is front-loaded with the critical deprecation note, and each sentence contributes to the usage decision. Minor redundancy costs a point.

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 description covers the primary purpose and the deprecation alternative, which is essential. However, it does not explain the four parameters beyond the natural-language description, nor does it describe any prerequisites or permissions. Given the tool's simplicity and the fact that it is deprecated, the description is adequate but not thorough—an agent might need additional context on how to properly supply the account and platform identifiers.

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 should compensate. It only mentions the 'natural-language description' input, which maps to the `description` parameter, but says nothing about accountId, platformUserId, or platform. The description does not explain the purpose or constraints of the other three parameters, leaving the agent to infer their meaning from the schema alone.

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 tool generates a complete automation flow from a natural-language description and returns a draft plus a builder URL. It also differentiates itself from the successor version by explaining it is for MCP synchronous clients, which is a specific purpose that distinguishes it from other generation tools like generate_multiple_flows.

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?

Explicitly tells the agent to use generate_flow@2.0.0 instead, and defines the exact condition under which this version should be used ('for MCP synchronous clients that can't consume two-phase tool resolution'). This is a clear when-to-use and when-not-to-use directive with an explicit alternative.

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