sociahive

generate_flow

Generate a complete automation flow from a natural-language description.

The flow generates server-side in the background (10-30 seconds typical). The user sees an artifact card in chat that flips from "Building flow..." to "Built · →" when generation completes. They click the link to open the canvas with the fully-built flow.

description = what the flow does (trigger + outcome). Keep it tight. businessContext (optional structured fields: industry, product, keyword, offer, tone, dataFields) = who's running it. Fill what you can extract from the user or <page_context>; missing fields are fine.

Ask one short question BEFORE calling only when the request is too vague to determine trigger or outcome AND you have zero context from any source. Otherwise call directly.

Behavior in the SAME turn as your generate_flow call:

OPEN with ONE short, warm line mirroring what the user wants in THEIR words (e.g. "Got it — every 'Price' comment gets an instant reply. Building it now…"), then build silently. Sound like a teammate beside them ("Got it" / "On it" + the outcome), not a robot narrating itself.
Mirror the OUTCOME, never the mechanism. Don't enumerate nodes ("1. Trigger…
1. DM…") or narrate each tool ("let me get your post… now I'll generate…") — you don't know the real nodes; the card shows them.
One warm line is the whole message — no essay — unless the user asks how it works, then explain plainly. Brief by default, deep when invited.
The card IS the completion signal (flips to "Built · · N nodes →" on its own). Don't promise a follow-up you can't deliver this turn. After the line + tool call, stop; don't chain calls referencing the new flowId.

Behavior in FOLLOW-UP turns (the user comes back to edit OR to provide clarification after a failed build):

The system prompt's includes recentlyGeneratedFlows with the live node/edge IDs of flows you generated in the last few turns. Reference those IDs directly when calling update_node / add_node / etc.
If recentlyGeneratedFlows doesn't have the flow you need (e.g., it predates your context window), call get_flow first to load fresh state, then call your mutation tool.
Never trust your previous turn's tool result for node IDs — it was the PENDING shape (empty nodes) at the moment of the call. The flow doc is the source of truth.
Errors arrive as artifacts[i].error.{reason, message, recovery}. Handle by recovery.kind:
- 'ask_user' (e.g. needs_clarification): the builder needs more info from error.message. If the user's CURRENT message provides it (typed or via a clarification chip), re-call generate_flow with an AUGMENTED description (original request + the new context) AND iterateOnFlowId: <that artifact's flowId> so the build lands in the SAME draft instead of orphaning it. If their message didn't address it, surface error.message as a question and wait. Never silently retry with the same description.
- 'retry_same': retry once with the same description.
- else: surface to the user, don't auto-retry.

Use variants: 2-3 for "give me a few options" requests. iterateOnFlowId (id or NAME) REBUILDS that whole flow — only to answer a clarification or reshape a flow you just built; refused once a person edited it. For one change to an existing flow use update_node / add_node / delete_node. OMIT it for anything new; an uncertain reference fails the call.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`platform`	No
`variants`	No
`description`	Yes
`businessContext`	No
`iterateOnFlowId`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 23, 2026

TDQS

A4.7/5.0

Behavior5/5

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

No annotations exist, so the description carries the full burden and does so: server-side async generation with a 10-30s latency expectation, the artifact-card completion signal, stale-ID warnings ("Never trust your previous turn's tool result for node IDs"), and the full error contract with recovery.kind branches. It even discloses that iterateOnFlowId is refused once a person has edited the flow — a non-obvious mutation constraint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence and the body is organized under clear behavioral headings, so it is scannable despite its length. Some space is spent on conversational-tone policy (how to phrase the chat opener) that is arguably agent demeanor rather than tool contract, which makes the block bulkier than strictly required.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

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 still explains what the caller observes after invocation (the card flipping to "Built · <flow name> →" with node count) and how failures surface, which is the right division of labor. With five parameters including a nested object and one enum, the uncovered `platform` parameter is the only material gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it largely does: `description`, `businessContext` (with all six nested fields enumerated: industry, product, keyword, offer, tone, dataFields), `variants`, and `iterateOnFlowId` semantics are all explained beyond the bare schema. The `platform` enum parameter (instagram/whatsapp/messenger/telegram) is never mentioned in the description, leaving one of five parameters undocumented anywhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with an explicit input modality: "Generate a complete automation flow from a natural-language description." It also routes the agent away from itself where appropriate, naming update_node / add_node / delete_node for single-edit cases, so the agent can distinguish it from sibling mutation tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-ask-first rule ("Ask one short question BEFORE calling only when the request is too vague to determine trigger or outcome AND you have zero context"), explicit when-to-call-directly, and explicit instruction for variants ("Use `variants: 2-3` for 'give me a few options' requests"). It also states when iterateOnFlowId applies versus when to use a different tool — genuine when/when-not guidance.

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

All sociahive tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?