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

Annotations already declare a non-read-only but non-destructive, idempotent write, so the safety profile is covered; the description adds real value beyond that by disclosing the side effect (flow steps materialize as tasks with deadlines) and by advising idempotency_key reuse on retry. Auth requirements and behavior when a flow is already running on the thread are not covered.

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?

Three compact sentences, front-loaded with the effect of the call and followed by the parameter guidance. "label is optional" is mildly redundant with the schema's required list, but nothing else is wasted.

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 four-parameter mutation with no output schema, the description covers what the call does, where the flowId comes from, and retry semantics. It does not describe what is returned (e.g., created tasks) or failure modes such as an inactive or already-applied flow, which is a modest remaining gap.

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?

With only 25% schema description coverage, the description has to carry the load, and it does for the two non-obvious fields: flowId is explained as naming an active flow discovered via entity flows, and label as optional. conversation_id and the idempotency_key semantics are left to the schema/field name, but the key ambiguity is resolved.

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?

States a specific verb and resource ("Starts a flow on a conversation") and grounds it in a familiar analogue ("as the thread's flow picker does"), plus the concrete consequence that the flow's steps become tasks with deadlines. It does not explicitly differentiate itself from nearby siblings such as set_flow_on, set_flow_start, or remove_conversation_flow, so an agent still has to infer the boundary.

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?

Implied usage is clear enough for the happy path, and the description points the agent at reading entity flows to obtain a valid flowId. However, there is no explicit when-to-use/when-not guidance relative to the several other flow-related siblings, nor any stated prerequisite such as the flow being active.

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