Hosted AI agents and locked workflows on connected apps, with human approval gates and a run ledger. Docs: https://docs.flowra.dev/guides/mcp
Scored across 6 tools
The six tools generally target distinct stages: discovery, schema lookup, connection management, bulk execution, JS sandbox, and bash sandbox. The descriptions explicitly clarify the JS/Bash sandbox boundary, but DISCOVER_TOOLS can optionally return schemas and the JS sandbox can run bulk tool calls, creating mild overlap with GET_TOOL_SCHEMAS and MULTI_EXECUTE_TOOL.
Every tool uses the same FLOWRA_ uppercase snake_case prefix and underscore-separated naming convention. Although the stems mix verbs and noun phrases, the overall naming is highly consistent and predictable.
Six tools are well-scoped for a meta-server that handles discovery, schema loading, connection management, parallel execution, and two sandboxed execution environments. Each tool appears to earn its place, with no obvious redundant or trivial entries.
The surface covers the core lifecycle: discover tools, inspect schemas, connect accounts, execute actions, and script in a remote sandbox. Minor gaps remain, such as no exposed workflow creation/update tool despite descriptions referencing workflow validation, but these are workarounds rather than blocking omissions.
Find the exact tool slugs for an app or integration. Returns mainToolSlugs, relatedToolSlugs, per-toolkit hasActiveConnection, a short plan, pitfalls, and notFoundToolkitSlugs. If you already have the exact ACTION slug and only need its input schema, use FLOWRA_GET_TOOL_SCHEMAS instead.
When the result includes a catalog app that covers the job, use that app's tool instead of a generic web search, fetch, or HTTP tool.
Toolkit tools are not direct function calls. Once you have a slug: FLOWRA_GET_TOOL_SCHEMAS for its arguments (or set includeInputSchemas=true here and skip that step), FLOWRA_MANAGE_CONNECTIONS if hasActiveConnection is false, then FLOWRA_MULTI_EXECUTE_TOOL to run it. Use only slugs that came back from this call.
mode "select" (default): queries are one atomic English useCase per item, with the app name in it. Any schedule or recurrence goes in intentSummary only, never in useCase — recurring work is a workflow, not a tool argument. toolkitSlugs pins that app's important tools into candidates. Pass toolkitSlugs, queries, or both — at least one is required. select returns only the tools needed for one action, never a full catalog.
mode "inventory": one page of tools in a known app. Requires toolkitSlugs. Optional query is a whole-word match on slug, name, or description (issue matches issues, not issued; for example query "issue" with toolkitSlugs ["github"]). No selection model and no native Flowra tools unless that toolkit was requested. mainToolSlugs is this page only; relatedToolSlugs is empty. toolSchemas include name and a one-line description. If inventory.truncated is true, call again with the same toolkitSlugs and query and offset=inventory.nextOffset. Do not use the workbench to browse a toolkit catalog.
toolkitSlugs: exact catalog toolkit slugs (lowercase app id such as gmail or github). Do not pass ACTION slugs here (GMAIL_SEND_EMAIL).
Reuse the returned session.id on GET_TOOL_SCHEMAS, MANAGE_CONNECTIONS, and MULTI_EXECUTE_TOOL so auth and workbench state stay on one session.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | select (default): smallest set of tools for one action. inventory: one page of tools in toolkitSlugs, optional query filter, no selection model. Use inventory to list or search an app catalog (for example GitHub issue tools). | |
| limit | No | Inventory page size. Default 40, max 50. Ignored in select mode. | |
| query | No | Inventory only. Whole-word match on slug, name, or description (issue matches issues, not issued). Omit for the first page of the toolkit. Ignored in select mode. | |
| offset | No | Inventory page start. When inventory.truncated is true, pass inventory.nextOffset. Default 0. Ignored in select mode. | |
| queries | No | Use cases to search in parallel. Required in select mode unless toolkitSlugs is set. Ignored in inventory mode. | |
| session | No | Chat: omit. MCP/new: { generate_id: true }. Continue: { id }. Not both. | |
| userMessage | Yes | Exact user request (any language) | |
| toolkitSlugs | No | Exact catalog toolkit slugs (gmail, github). select: pins important tools. inventory: required, lists that app. Not ACTION slugs. | |
| intentSummary | Yes | One-sentence intent; include scheduling here if any | |
| includeInputSchemas | No | When true, toolSchemas include inputSchema so you can skip GET_TOOL_SCHEMAS. Default false |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | Error if any occurred during the execution of the action |
| message | No | |
| successful | No | Whether or not the action execution was successful or not |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing the full result shape, the truncation/nextOffset pagination loop for inventory, that inventory excludes native Flowra tools, and the session-handoff requirement so auth and workbench state persist across calls. These are operational behaviors the annotations cannot convey.
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?
Front-loaded with purpose and the key routing decision, then organized by mode and by parameter notes; each section is scannable. It is fairly long and some parameter detail (query matching) duplicates the schema, but no sentence is pure filler.
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 10-parameter, mode-branching discovery tool with an output schema, the description supplies everything needed: session continuity rules, the follow-up call chain, pagination handling, and slug-type constraints. Nothing an agent needs to invoke it correctly is missing.
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 coverage is 100% so the baseline is 3, but the description adds cross-parameter logic the schema cannot express: select requires toolkitSlugs OR queries, inventory requires toolkitSlugs, schedules belong in intentSummary and never in useCase, and toolkitSlugs must be app ids, not ACTION slugs. It also gives a concrete whole-word match example ('issue' matches 'issues', not 'issued').
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?
Opens with a specific verb+resource: 'Find the exact tool slugs for an app or integration,' and immediately enumerates the return payload (mainToolSlugs, relatedToolSlugs, hasActiveConnection, plan, pitfalls). It explicitly separates itself from the sibling FLOWRA_GET_TOOL_SCHEMAS, so an agent can route correctly without opening schemas.
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?
States explicit when/when-not and alternatives: use GET_TOOL_SCHEMAS if you already have the slug and only need a schema; use MANAGE_CONNECTIONS if hasActiveConnection is false; use MULTI_EXECUTE_TOOL to run. Mode guidance (select vs inventory) is spelled out with the condition that selects each, plus 'do not use the workbench to browse a toolkit catalog.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load the input schema and tool type for exact tool slugs, so you can build correct arguments before running them with FLOWRA_MULTI_EXECUTE_TOOL. These slugs are NOT bound functions — never emit them as a tool_call name. Call FLOWRA_DISCOVER_TOOLS first if you do not have the slug. Set includeOutputSchema=true only when you need a trigger or webhook payload shape. Pass session.id from DISCOVER to stay in the same session.
Workflow action nodes flatten tool data into the node state: after an action node "fetch", use fetch.content / fetch.title in prompts and inputMapping — not fetch.data.content. GET_TOOL_SCHEMAS may show an envelope with properties.data; CREATE_OR_UPDATE_WORKFLOW validation uses the flattened field names only.
| Name | Required | Description | Default |
|---|---|---|---|
| session | No | Optional meta session.id from DISCOVER | |
| toolSlugs | Yes | Exact slugs from Known tools, pins, or DISCOVER — never invent | |
| includeOutputSchema | Yes | Include outputSchema (trigger payloads). Default false |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | Error if any occurred during the execution of the action |
| message | No | |
| successful | No | Whether or not the action execution was successful or not |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, but the description goes further: slugs are NOT bound functions and must never be emitted as a tool_call name, and it discloses the workflow action node behavior where `data` is flattened into node state (fetch.content vs fetch.data.content). That is non-obvious behavioral context an agent could not get from structured fields.
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?
Front-loaded with the core purpose, prerequisite, and the critical 'not a tool_call name' warning. The second paragraph about workflow flattening is dense but relevant, though it drifts toward workflow-authoring guidance rather than this tool's own invocation and could be tightened.
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?
An output schema exists so return values need no explanation, yet the description still clarifies the envelope-vs-flattened distinction that directly affects how the output is consumed and validated by CREATE_OR_UPDATE_WORKFLOW. Nothing needed to call it correctly is missing.
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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema descriptions: session.id is tied to DISCOVER for session continuity, and includeOutputSchema is scoped to trigger/webhook payload shapes rather than a generic boolean.
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 — load input schema and tool type for exact slugs — and names the downstream consumer (FLOWRA_MULTI_EXECUTE_TOOL). It also explicitly distinguishes itself from the discovery sibling by requiring slugs rather than producing them.
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 explicit when-to-use rules: call FLOWRA_DISCOVER_TOOLS first if the slug is unknown, set includeOutputSchema=true only when a trigger or webhook payload shape is needed, and pass session.id from DISCOVER to stay in the same session. Alternatives and conditions are spelled out rather than implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Process REMOTE FILES or script BULK TOOL EXECUTIONS using JavaScript code in a REMOTE SANDBOX. If you can see the data in chat, DON'T USE THIS TOOL.
ONLY use this when processing data stored in a remote file or when scripting bulk tool executions.
BOUNDARY WITH FLOWRA_REMOTE_BASH
Both tools share one sandbox per session.id and the same /home/user/files files.
This tool runs JavaScript and keeps variables between calls. Only this tool has run_tool (app tools), invoke_llm, proxy_execute, and upload_local_file.
FLOWRA_REMOTE_BASH runs one shell command with a fresh shell each call and none of those helpers. Use it for jq, grep, sort, unzip, or listing files.
Neither tool can call FLOWRA_MULTI_EXECUTE_TOOL or any other FLOWRA_* meta tool.
DO NOT USE
When the complete response is already inline/in-memory, or you only need quick parsing, summarization, or basic math.
USE IF
To parse/analyze tool outputs saved to a remote file in the sandbox or to script multi-tool chains there.
After FLOWRA_MULTI_EXECUTE_TOOL with syncResponseToWorkbench: true and the same session.id: the snapshot is at /home/user/files/multi_execute.json and as FLOWRA_WORKBENCH_SNAPSHOT. FLOWRA_REMOTE_BASH sees the same file.
For bulk or repeated executions of known Flowra tools (e.g., add a label to 100 emails).
To call APIs via proxy_execute when no Flowra tool exists for that API.
OUTPUTS
Returns a compact result or, if too long, artifacts for download.
IMPORTANT CODING RULES:
Stepwise Execution: Split work into small steps. Save intermediate outputs in variables or temporary storage. Call FLOWRA_JS_REMOTE_WORKBENCH again for the next step. This improves composability and avoids timeouts.
Session Persistence: This is a persistent JavaScript execution context: variables, functions, and in-memory state from previous and future code executions are preserved in the sandbox session and available for reuse. Do not import or redeclare the helpers below.
Parallelism & Timeout (CRITICAL): There is a hard timeout of 4 minutes. Prioritize PARALLEL execution using Promise.all() with suitable concurrency for bulk operations (e.g., call run_tool or invoke_llm in parallel across items). 3.1 If the data is large, split into smaller batches and call the workbench multiple times to avoid timeouts.
Checkpoints: Implement checkpoints (in memory or variables) so that long runs can be resumed from the last completed step.
Schema Safety: Never assume the response schema for run_tool if not known already from previous tools. To inspect schema, run a simple request via MULTI_EXECUTE_TOOL or use invoke_llm helper.
LLM Helpers: Always use invoke_llm helper for summary, analysis, or field extraction on results. Prefer batching items into smaller groups to stay within token limit.
Avoid Meta Loops: Do not use run_tool to call MULTI_EXECUTE_TOOL or other FLOWRA_* meta tools to avoid cycles. Only use it for app tools.
Pagination: Use when data spans multiple pages. Continue fetching pages with the returned next_page_token or cursor until none remains. Parallelize fetching pages if the tool supports page_number.
No Hardcoding: Never hardcode data in code. Always load it from files or tool responses, iterating to construct intermediate or final inputs/outputs.
Code Correctness (CRITICAL): Code must be syntactically and semantically correct and executable (ES5-friendly; avoid ?? or ?. if targeting older runtimes).
GLOBALS (when workbench snapshot loaded)
FLOWRA_WORKBENCH_SNAPSHOT: full JSON from MULTI_EXECUTE sync, or null if load failed / skipped.
HELPERS (already in sandbox – do not redeclare):
run_tool(toolSlug, args) -> [result, error]: Execute a known Flowra app tool (from DISCOVER_TOOLS). Match the tool's input schema. Returns (data, "") on success; ({}, "error_message") on failure. Check error before using result.
invoke_llm(query) -> [text, error]: Invoke an LLM for semantic tasks. Pass MAX ~400k characters. Returns (response_text, "") on success; ("", "error_message") on failure.
proxy_execute(method, endpoint, toolkit, query_params?, body?, headers?) -> [data, error]: Call a connected toolkit API. endpoint is a path on that toolkit's base URL. Credentials stay on the host. Returns (response_data, "") or (null, "error_message").
upload_local_file(filePath) -> [fileUrl, error]: Upload a file from /home/user/files and return a public download URL.
All helpers return [result, error]. Always check error before using result.
Error-first pattern: const [res, err] = await run_tool("SOME_TOOL_SLUG", { key: "value" }); if (err) { return { error: err }; } const data = res.data != null ? res.data : res; // use data
Parallelize (4-min timeout): const CONCURRENCY = 10; const items = [/* ... */]; const results = []; for (let i = 0; i < items.length; i += CONCURRENCY) { const batch = items.slice(i, i + CONCURRENCY); const out = await Promise.all(batch.map(async (item) => { const [r, e] = await run_tool("TOOL_SLUG", item); return e ? { status: "failed", error: e } : { status: "ok", data: r }; })); results.push(...out); } return results;
| Name | Required | Description | Default |
|---|---|---|---|
| session | No | ALWAYS pass session.id from DISCOVER (never invent; never mint here). | |
| thought | No | Concise objective and high-level plan (no private chain-of-thought). 1 sentence describing what the cell should achieve and why the sandbox is needed. | |
| codeToExecute | Yes | JavaScript to run inside the persistent remote JavaScript sandbox. State (imports, variables, files) is preserved across executions. Keep code concise to minimize tool call latency. Avoid unnecessary comments. | |
| workbenchArtifactId | No | Pin a specific snapshot from MULTI_EXECUTE (workbenchArtifactId); omit to use the latest for this session. | |
| useWorkbenchSnapshot | No | When true (default), fetch the latest Flowra workbench JSON for this session (from MULTI_EXECUTE + syncResponseToWorkbench) before your code runs; exposed as FLOWRA_WORKBENCH_SNAPSHOT. Set false to skip. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | Error if any occurred during the execution of the action |
| message | No | |
| successful | No | Whether or not the action execution was successful or not |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this destructive/openWorld/non-idempotent, and the description adds substantial context beyond them: shared per-session sandbox, persistent variables across calls, a 4-minute hard timeout, the error-first return convention, available helpers, and parallelization guidance. This is exactly the extra behavioral context an agent needs before writing code.
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?
Front-loaded with the core rule and a clean boundary section, then outputs and coding rules. Dense and mostly earned, though the numbered coding rules and helper examples make it long enough that some repetition (e.g., 'always check error') appears more than once.
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 complex code-execution tool with nested session objects and an output schema, the description covers routing, persistence, timeout, helpers, error handling, and snapshot loading. Nothing an agent needs to invoke it correctly is missing.
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 coverage is 100%, so the baseline is 3; the description still adds value by explaining session.id sharing with FLOWRA_REMOTE_BASH, the workbenchArtifactId pinning semantics, and the FLOWRA_WORKBENCH_SNAPSHOT global populated by useWorkbenchSnapshot. These inter-tool semantics go beyond the schema text.
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+resource (execute JavaScript in a remote persistent sandbox) and explicitly distinguishes itself from its nearest sibling FLOWRA_REMOTE_BASH, including what each can and cannot call. An agent can route between them without opening either schema.
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?
Provides explicit USE IF and DO NOT USE sections plus a named alternative with its own use cases (jq/grep/sort/unzip/listing go to FLOWRA_REMOTE_BASH), and a hard routing rule ('if you can see the data in chat, don't use this tool'). This is unusually complete guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect the user to an app, or check whether an app is already connected. Pass the toolkit slugs you need; connections are per end user and several toolkits can be checked in one call.
mode:
"connect" (default): if not already active, start the normal connect flow (may return redirectUrl / requires_parameters).
"status": read-only. Never mint OAuth/consent links or create INITIATED rows. Returns active / not_connected / no_auth_required / needs_setup only.
Each toolkit comes back with a status you must handle:
active / no_auth_required: ready — go execute the app's tools.
not_connected: only when mode is "status" — no active connection; call again with mode "connect" (or omit mode) when the user wants to connect.
initiated: redirectUrl is set. Show that one markdown link and stop. Do not call this tool again until the user says they finished connecting in the browser. Then call with the same toolkits to confirm it is active. A verify call must not mint a second link (wasReinitiated stays false).
requires_parameters: the user must supply credentials. Ask for exactly the fields listed in requiredParameters, showing each field's description, then call again with specifyCustomAuth.
requires_challenge: only when this status is returned. Ask for exactly the fields in requiredParameters, then call again with challengeResponse: { connectionId, plus those field names }. Do not invent a verification step when this status is absent.
needs_setup: a secondary end user cannot connect yet because project App credentials are missing. Tell them the app is not ready; never ask them for client_id, client_secret, or other app-level secrets. (Project default / owner instead gets requires_parameters for those App credential fields.)
failed: read errorMessage before retrying.
When talking to the user, use the label field (email, username, or app name). Never show a connection UUID.
Use specifyCustomAuth to activate an API key, bearer token, basic auth, or pasted cookies directly, without opening a browser. Pass session.id from FLOWRA_DISCOVER_TOOLS when you are continuing the same discovery session.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | connect (default): may start OAuth/consent when not active. status: read-only check — never mint redirectUrl or INITIATED rows. | connect |
| session | No | Optional meta session.id from DISCOVER for correlation (not required for OAuth). | |
| toolkits | Yes | List of toolkit slugs (base like 'gmail' or project-scoped like 'gmail:abc123') to check or connect. Prefer base slugs from CREATE_OR_UPDATE_TOOLKIT / DISCOVER_TOOLS — project suffix is resolved automatically. Never invent slugs. | |
| reinitiateAll | Yes | Force reconnection for ALL toolkits in the `toolkits` list, even if they already have active connections. DEFAULT: false (preserve existing active connections). Ignored when mode is status. | |
| challengeResponse | No | Continue a pending challenge only after status is requires_challenge. Pass connectionId plus the field names from requiredParameters. Do not send this unless that status was returned. | |
| specifyCustomAuth | No | Agent-friendly way to provide per-toolkit credentials and connection fields. Outer object: keys are toolkit names (must match entries in `toolkits`). Inner object: credentials for that toolkit. Supported patterns: API Key {"apiKey": "YOUR_KEY"}, Bearer Token {"bearerToken": "YOUR_TOKEN"}, Basic Auth {"username": "USER", "password": "PASS"}, Cookie {"cookies": "..."}, email/password {"email":"...","password":"..."}, Custom OAuth {"client_id": "...", "client_secret": "..."}, plus any field names from the toolkit authConfigDetails. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | Error if any occurred during the execution of the action |
| message | No | |
| successful | No | Whether or not the action execution was successful or not |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only carry readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true; the description adds substantial behavior beyond that: read-only mode never mints redirectUrl/INITIATED rows, verify calls must not re-issue a link, app-level secrets must never be requested from secondary users, and failed requires reading errorMessage first.
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?
It is long, but front-loaded with the core purpose and organized as a scannable mode block plus a status-handling list, so no section is filler. A few lines (e.g. the parenthetical about project default/owner) could be tightened, keeping it just under maximum marks.
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 complex 6-parameter tool with nested objects and an output schema (which the description rightly doesn't duplicate), it covers the full operating loop: modes, every return status, the exact follow-up action per status, and secrets/error handling. An agent has everything needed to invoke and recover correctly.
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 coverage is 100% so the baseline is 3, but the description meaningfully enriches parameter use: it explains mode semantics and status outcomes, how requiredParameters maps to a follow-up call with specifyCustomAuth or challengeResponse, and when to pass session.id from DISCOVER. It stops short of documenting every field (e.g. reinitiateAll behavior is largely left to the schema).
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 first sentence states a precise dual verb+resource: connect a user to an app, or check whether an app is already connected. It also names the scope (per end user, multiple toolkits per call), allowing an agent to distinguish this from discovery/execution siblings like FLOWRA_DISCOVER_TOOLS or FLOWRA_MULTI_EXECUTE_TOOL.
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?
Explicit when-to-use rules for both modes ('status: read-only, never mint links'; 'connect: may start OAuth/consent'), plus a per-status playbook telling the agent exactly what to do next (show one link and stop, ask for requiredParameters fields, never invent a challenge). Alternatives and sequencing with FLOWRA_DISCOVER_TOOLS are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run up to 50 action tools in parallel and return every result inline. Only type="action" tools — triggers and webhooks cannot be executed here.
This is how you run any tool that is not already bound as a direct function. Get the exact slug from FLOWRA_DISCOVER_TOOLS or a Known tools list, load its input schema with FLOWRA_GET_TOOL_SCHEMAS (or set includeInputSchemas on DISCOVER and reuse those), and call FLOWRA_MANAGE_CONNECTIONS first if the toolkit has no active connection. Never invent a slug or an argument. Never emit an unbound slug as a tool_call name — only this function runs those slugs, via tools[].toolSlug.
tools must be a non-empty array of { toolSlug, arguments }. Never pass tools: [] or omit tools. If you only have a JSON string, parse it into that array first.
Batch only independent calls; keep a dependent step in a later call so you can read the previous result first. When a result implies more pages, keep going until you have everything.
Never wrap a tool that waits for the user (for example a choice prompt) here. If one is bound, call it directly and wait.
| Name | Required | Description | Default |
|---|---|---|---|
| tools | Yes | Action tools to run in parallel (max 50). Not triggers. Must contain at least one { toolSlug, arguments } — never []. | |
| memory | No | Durable facts worth reusing later, as {app: ["fact"]} — ids and mappings, not "sent/fetched" logs. Pass {} when there are none. | |
| session | No | Meta session.id from DISCOVER (workbench correlation; auth is user-scoped) | |
| thought | No | One-sentence rationale | |
| syncResponseToWorkbench | Yes | Store a workbench snapshot for REMOTE_BASH / JS_REMOTE_WORKBENCH (results still return inline). Needs session.id. Only set true when a sandbox tool is available and the output is large or worth scripting over. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | Error if any occurred during the execution of the action |
| message | No | |
| successful | No | Whether or not the action execution was successful or not |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive/openWorld/non-idempotent, but the description adds meaningful operational behavior: parallel execution, inline return of every result, slug-validity enforcement, pagination continuation, and the prohibition on invoking unbound slugs as tool_call names. It stops short of describing partial-failure or error semantics when some of the 50 calls fail, which keeps it from a 5.
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?
Front-loads the core action in the first sentence, then layers prerequisites, batching rules, and exclusions in short, self-contained paragraphs. Despite the length, every sentence carries a distinct actionable constraint.
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 complex meta-execution tool with nested objects, an output schema, and full annotation coverage, the description supplies everything the agent needs to construct a valid call: slug sourcing, schema loading, connection prerequisites, batching, pagination, and wait-tool exclusions. Return values are covered by the output schema, so omitting them is correct.
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 coverage is 100%, so the baseline is 3, but the description earns extra by reinforcing the tools contract (non-empty array of {toolSlug, arguments}, never [], parse JSON strings first) and the rule that toolSlug must come from DISCOVER/pins and never be invented. It leaves memory/session/thought/syncResponseToWorkbench to the schema, which already documents them well.
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 (run), resource (action tools), and scope (up to 50, in parallel, inline results) in the first sentence. It immediately distinguishes itself from siblings by excluding triggers and webhooks and by naming DISCOVER, GET_TOOL_SCHEMAS, and MANAGE_CONNECTIONS as the supporting flow.
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?
Explicit when-to-use (any tool not bound as a direct function), how to prepare (get slug from DISCOVER, load schema, ensure a connection), and when-not (triggers/webhooks, waiting tools that must be called directly). It even gives sequencing rules: batch only independent calls, keep dependents in later calls, and continue paging until complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run bash on the same remote sandbox as FLOWRA_JS_REMOTE_WORKBENCH for this session.id. Files under /home/user/files stay between calls. The shell itself starts fresh each time.
With session.id and useWorkbenchSnapshot (default true), the latest FLOWRA_MULTI_EXECUTE_TOOL snapshot is at /home/user/files/multi_execute.json (also FLOWRA_WORKBENCH_JSON). That snapshot only exists if the earlier call set syncResponseToWorkbench: true.
Use this for shell work on those files: jq, grep, sort, unzip, wc, listing directories. It has no run_tool, invoke_llm, or proxy_execute helpers and keeps no variables between calls. To call app tools, an LLM, or a connected API from the sandbox, or to keep state across steps, use FLOWRA_JS_REMOTE_WORKBENCH. Neither tool can call FLOWRA_MULTI_EXECUTE_TOOL or any other meta tool.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The bash command to execute | |
| session | No | ALWAYS pass session.id from DISCOVER when provided (or omit in chat — threadId is used). | |
| workbenchArtifactId | No | Specific snapshot id returned as workbenchArtifactId by MULTI_EXECUTE; omit to use the latest snapshot for this session. | |
| useWorkbenchSnapshot | No | When true (default), inject the latest Flowra workbench JSON for this session (from MULTI_EXECUTE + syncResponseToWorkbench) before your command. Set false to run raw bash only. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | Error if any occurred during the execution of the action |
| message | No | |
| successful | No | Whether or not the action execution was successful or not |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive/openWorld/non-idempotent, and the description goes well beyond them: file persistence under /home/user/files, shell state resetting each call, no run_tool/invoke_llm/proxy_execute helpers, no variables kept, and the syncResponseToWorkbench:true prerequisite for snapshot existence.
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?
Front-loads the core purpose and persistence model before the snapshot mechanics and sibling routing. Dense but every sentence carries operational weight; only slightly long.
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?
Covers persistence semantics, prerequisites, sandbox limitations, and the sibling alternative. An output schema exists, so return values need not be explained, and nothing an agent needs to invoke it correctly is missing.
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 coverage is 100%, so baseline is 3, but the description adds real meaning: it ties useWorkbenchSnapshot (default true) to the snapshot file path and the syncResponseToWorkbench prerequisite, explaining why the injected file may be absent.
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 ('Run bash on the same remote sandbox... for this session.id') and explicitly contrasts with the sibling FLOWRA_JS_REMOTE_WORKBENCH. An agent can distinguish it from the JS workbench without opening either schema.
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 concrete when-to-use examples (jq, grep, sort, unzip, wc, directory listing) and an explicit alternative rule: use FLOWRA_JS_REMOTE_WORKBENCH for app tools, LLM calls, connected APIs, or cross-step state. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
FLOWRA_DISCOVER_TOOLS1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "guidance": {},
+ "inventory": {
+ "description": "Set in inventory mode. Omitted in select mode.",
+ "properties": {
+ "limit": {},
+ "nextOffset": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Pass as offset to continue; null on the last page"
+ },
+ "offset": {},
+ "total": {
+ "description": "Tools matching toolkitSlugs and query"
+ },
+ "truncated": {
+ "description": "True when another page exists"
+ }
+ }
+ },
+ "mainToolSlugs": {
+ "items": {}
+ },
+ "notFoundToolkitSlugs": {
+ "description": "Requested toolkitSlugs that did not resolve",
+ "items": {}
+ },
+ "pitfalls": {
+ "items": {}
+ },
+ "reasoning": {},
+ "relatedToolSlugs": {
+ "items": {}
+ },
+ "session": {
+ "properties": {
+ "id": {},
+ "instructions": {}
+ }
+ },
+ "timeInfo": {
+ "properties": {
+ "currentTime": {},
+ "message": {}
+ }
+ },
+ "toolSchemas": {
+ "propertyNames": {}
+ },
+ "toolkitConnectionStatuses": {
+ "items": {
+ "properties": {
+ "description": {},
+ "hasActiveConnection": {},
+ "message": {},
+ "toolkit": {}
+ }
+ }
+ },
+ "toolkits": {
+ "items": {}
+ },
+ "validatedPlan": {
+ "items": {}
+ }
+ }
+ },
+ "error": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Error if any occurred during the execution of the action"
+ },
+ "message": {},
+ "successful": {
+ "description": "Whether or not the action execution was successful or not"
+ }
+ },
+ "type": "object"
+}FLOWRA_GET_TOOL_SCHEMAS1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "executionHint": {
+ "description": "How to run these slugs — they are not bound functions"
+ },
+ "notFound": {
+ "description": "Slugs not found",
+ "items": {}
+ },
+ "session": {
+ "description": "Echoed session — never minted here",
+ "properties": {
+ "id": {
+ "description": "Meta session id (empty if none)"
+ },
+ "instructions": {
+ "description": "How to reuse session.id"
+ }
+ }
+ },
+ "success": {
+ "description": "True when every requested slug was found"
+ },
+ "toolSchemas": {
+ "description": "Definitions keyed by toolSlug",
+ "propertyNames": {}
+ }
+ }
+ },
+ "error": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Error if any occurred during the execution of the action"
+ },
+ "message": {},
+ "successful": {
+ "description": "Whether or not the action execution was successful or not"
+ }
+ },
+ "type": "object"
+}FLOWRA_JS_REMOTE_WORKBENCH1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "error": {
+ "default": "",
+ "description": "Error message if any"
+ },
+ "results": {
+ "anyOf": [
+ {
+ "propertyNames": {}
+ },
+ {
+ "items": {}
+ },
+ {},
+ {},
+ {},
+ {}
+ ],
+ "description": "The parsed result of the code execution (object, array, or primitive)"
+ },
+ "results_file_path": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Path to file containing full results if output was truncated"
+ },
+ "session": {
+ "anyOf": [
+ {
+ "properties": {
+ "id": {
+ "description": "Meta session identifier"
+ },
+ "instructions": {
+ "description": "Instructions for session reuse"
+ }
+ }
+ },
+ {}
+ ],
+ "description": "Meta session echoed back to reinforce reuse: { id: string, instructions: string }"
+ },
+ "stderr": {
+ "description": "The standard error output from the command"
+ },
+ "stderr_file_path": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Path to file containing full stderr if output was truncated"
+ },
+ "stdout": {
+ "description": "The standard output from the command"
+ },
+ "stdout_file_path": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Path to file containing full stdout if output was truncated"
+ }
+ }
+ },
+ "error": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Error if any occurred during the execution of the action"
+ },
+ "message": {},
+ "successful": {
+ "description": "Whether or not the action execution was successful or not"
+ }
+ },
+ "type": "object"
+}FLOWRA_MANAGE_CONNECTIONS1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "message": {
+ "description": "Overall status message"
+ },
+ "results": {
+ "description": "Connection results for each toolkit",
+ "propertyNames": {}
+ },
+ "summary": {
+ "description": "Summary of results by status type",
+ "propertyNames": {}
+ }
+ }
+ },
+ "error": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Error if any occurred during the execution of the action"
+ },
+ "message": {},
+ "successful": {
+ "description": "Whether or not the action execution was successful or not"
+ }
+ },
+ "type": "object"
+}FLOWRA_MULTI_EXECUTE_TOOL1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "errorCount": {
+ "description": "Failures"
+ },
+ "results": {
+ "description": "Results in input order",
+ "items": {
+ "properties": {
+ "error": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Error message when failed"
+ },
+ "index": {
+ "description": "Index in the request tools array"
+ },
+ "response": {
+ "anyOf": [
+ {
+ "propertyNames": {}
+ },
+ {}
+ ],
+ "description": "Payload { data, error, logId, successful } on success and failure"
+ },
+ "success": {
+ "description": "Whether execution succeeded"
+ },
+ "toolSlug": {
+ "description": "Executed tool slug"
+ }
+ }
+ }
+ },
+ "successCount": {
+ "description": "Successes"
+ },
+ "totalCount": {
+ "description": "Tools executed"
+ },
+ "workbenchArtifactId": {
+ "description": "Snapshot id when syncResponseToWorkbench; pass to REMOTE_BASH or omit for latest"
+ }
+ }
+ },
+ "error": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Error if any occurred during the execution of the action"
+ },
+ "message": {},
+ "successful": {
+ "description": "Whether or not the action execution was successful or not"
+ }
+ },
+ "type": "object"
+}FLOWRA_REMOTE_BASH1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "sandbox_id_suffix": {
+ "description": "Last 4 digits of the sandbox ID for easier reference"
+ },
+ "session": {
+ "anyOf": [
+ {
+ "properties": {
+ "id": {},
+ "instructions": {}
+ }
+ },
+ {}
+ ],
+ "description": "Meta session echoed back to reinforce reuse: { id: string, instructions: string }"
+ },
+ "stderr": {
+ "description": "The standard error output from the command, possibly truncated for brevity."
+ },
+ "stderrLines": {
+ "description": "Total number of lines in original stderr, even if truncated"
+ },
+ "stderr_file_path": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Path to file containing full stderr if output was truncated"
+ },
+ "stdout": {
+ "description": "The standard output from the command, possibly truncated for brevity."
+ },
+ "stdoutLines": {
+ "description": "Total number of lines in original stdout, even if truncated"
+ },
+ "stdout_file_path": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Path to file containing full stdout if output was truncated"
+ }
+ }
+ },
+ "error": {
+ "anyOf": [
+ {},
+ {}
+ ],
+ "description": "Error if any occurred during the execution of the action"
+ },
+ "message": {},
+ "successful": {
+ "description": "Whether or not the action execution was successful or not"
+ }
+ },
+ "type": "object"
+}FLOWRA_DISCOVER_TOOLS5 fields changedInput schema / allOfAdded value: +[
+ {
+ "else": {
+ "anyOf": [
+ {
+ "required": [
+ "queries"
+ ]
+ },
+ {
+ "required": [
+ "toolkitSlugs"
+ ]
+ }
+ ]
+ },
+ "if": {
+ "properties": {
+ "mode": {
+ "const": "inventory"
+ }
+ },
+ "required": [
+ "mode"
+ ]
+ },
+ "then": {
+ "required": [
+ "toolkitSlugs"
+ ]
+ }
+ }
+]Input schema / properties / queries / minItemsAdded value: +1Input schema / properties / query / descriptionPrevious value: -"Inventory only. Case-insensitive match on slug, name, or description. Omit for the first page of the toolkit. Ignored in select mode."New value: +"Inventory only. Whole-word match on slug, name, or description (issue matches issues, not issued). Omit for the first page of the toolkit. Ignored in select mode."Input schema / properties / toolkitSlugs / minItemsAdded value: +1Input schema / requiredPrevious value: -[
- "userMessage",
- "intentSummary",
- "includeInputSchemas"
-]New value: +[
+ "userMessage",
+ "intentSummary"
+]FLOWRA_DISCOVER_TOOLS6 fields changedInput schema / properties / limitAdded value: +{
+ "description": "Inventory page size. Default 40, max 50. Ignored in select mode.",
+ "maximum": 50,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / modeAdded value: +{
+ "description": "select (default): smallest set of tools for one action. inventory: one page of tools in toolkitSlugs, optional query filter, no selection model. Use inventory to list or search an app catalog (for example GitHub issue tools).",
+ "enum": [
+ "select",
+ "inventory"
+ ],
+ "type": "string"
+}Input schema / properties / offsetAdded value: +{
+ "description": "Inventory page start. When inventory.truncated is true, pass inventory.nextOffset. Default 0. Ignored in select mode.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / queries / descriptionPrevious value: -"Use cases to search in parallel. Required unless toolkitSlugs is set."New value: +"Use cases to search in parallel. Required in select mode unless toolkitSlugs is set. Ignored in inventory mode."Input schema / properties / queryAdded value: +{
+ "description": "Inventory only. Case-insensitive match on slug, name, or description. Omit for the first page of the toolkit. Ignored in select mode.",
+ "type": "string"
+}Input schema / properties / toolkitSlugs / descriptionPrevious value: -"Exact catalog toolkit slugs (gmail, slack). Pins important tools from those apps. Not ACTION slugs."New value: +"Exact catalog toolkit slugs (gmail, github). select: pins important tools. inventory: required, lists that app. Not ACTION slugs."FLOWRA_DISCOVER_TOOLSFLOWRA_GET_TOOL_SCHEMASFLOWRA_JS_REMOTE_WORKBENCHFLOWRA_MANAGE_CONNECTIONSFLOWRA_MULTI_EXECUTE_TOOLFLOWRA_REMOTE_BASH
Add one secure layer between your agents and this server.