Tool reference

Source: orchestration/mcp-gateway/server.ts (TOOL_DEFS, StatusOutputSchema, validateToolArgs), orchestration/mcp-gateway/tools.ts (zod schemas and handlers), orchestration/mcp-gateway/tool-exec.ts (GetToolContractSchema, ExecuteToolSchema), orchestration/mcp-gateway/extras.ts (TemplatesSchema, ScheduleSchema, WhoamiSchema), orchestration/mcp-gateway/tools-bots.ts and tools-triggers.ts (the bot, execution-steer and trigger actions), orchestration/mcp-gateway/user-context-arg.ts (user_context), orchestration/mcp-gateway/shared.ts (formatArg, userRequest, length bounds), orchestration/mcp-gateway/tool-outcome.ts (ToolOutcomeSchema, renderAs), orchestration/mcp-gateway/chat.ts, orchestration/mcp-gateway/conversation.ts, orchestration/mcp-gateway/index.ts (argument pre-screen, fenced tools).

Every tool the server exposes, in the order tools/list returns them. You rarely call these by name: your client reads the list when it connects and picks the tool from your request. This chapter is the exact contract behind that choice. The server is https://mcp.plungeai.com/v1; https://api.plungeai.com/v1/mcp is the same server and returns the same list.

How to read the tables.

• Type is the JSON type with the server's bound: string (max 256) is at most 256 characters, integer 1–100 an integer in that range. An enum lists every accepted value.
• Required is what the input schema enforces: "yes" or "no". "For <action>" or "one of" means the schema accepts the call without the key, but that action, or the call, refuses to run without it.
• Default is what happens when you leave the key out: the schema default, or the default the handler applies. "—" means no default.
• A call whose arguments do not match the schema is not run. It comes back as a 📝 NEEDS INPUT outcome naming each bad or missing field, with isError: false (Errors, feedback & limits).

Two parameters recur.

• user_request, on every tool: a string (max 4,000), optional. It carries the user's request verbatim, in their own words, before the client turned it into arguments. The server instructions ask clients to always send it: the platform uses it for request context, routing and support diagnostics. Some tools also show it as the run's title.
• format, on nine tools: markdown (the default) or json. json returns the same answer as a JSON document in the text and the same object as structuredContent (Protocol & transport).

Annotations. Six tools carry readOnlyHint: true: plungeai_get_tool_contract, plungeai_list_agents, plungeai_list_workflows, plungeai_get_result, plungeai_get_workflow_status and plungeai_whoami. Several other tools have read-only actions (for example plungeai_executions list), but the flag is per tool. Seven tools declare an outputSchema: plungeai_execute_workflow, plungeai_execute_agent, plungeai_get_tool_contract, plungeai_execute_tool, plungeai_run_mission and plungeai_learn declare the outcome envelope (Tools), and plungeai_get_workflow_status declares its status object.

Keys can be fenced. A key limited to some tools does not see the others in tools/list, and a call to one answers JSON-RPC -32602 Tool not permitted for this key: <name> (Authentication & keys).

14.1 plungeai_execute_workflow

Execute a CNL workflow: a saved one (workflow_id) or ad-hoc YAML (workflow_yaml). Streams progress. Use mode:"async" for long runs (over 3 minutes): it returns an execution id to poll with plungeai_get_workflow_status. In ad-hoc YAML, write long strings as block scalars (prompt: |) and never hard-wrap a value; structured tool-agents take their card's parameters as task fields next to agent:. Always answers with a structured outcome, never a raw error: follow the remediation instead of retrying the identical call.

• Read-only: no. Output schema: the outcome envelope. Creates an execution: yes.

Returns. ok with the run's output and the execution-id footer. ok with only the execution id for mode:"async". needs_input when neither YAML nor id is given, when the saved id is not on your account (No saved workflow with id `<id>` on this account.), or when the YAML does not parse. unavailable when ad-hoc YAML names an agent that does not exist or is not active, before anything runs. needs_approval / needs_input when the run pauses for you. A failed run is classified into an outcome; an invalid-YAML failure adds a tip on quoting and block scalars.

Runs a model and costs credits (not verified here):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_execute_workflow","arguments":{"user_request":"run a one-task pong workflow","workflow_yaml":"name: pong-demo\ntasks:\n  - type: task\n    id: t1\n    agent: one-agent\n    prompt: \"Reply with only the word: pong\"\n"}}}'

14.2 plungeai_execute_agent

Execute a single prompt-driven agent, for example one-agent (call mode; add a persona for a specialist answer). Pass session_id to start or continue a conversational agent. Structured tool-agents (cards with a Parameters table, such as markitdown or weather-agent) take typed fields, not prose: use plungeai_get_tool_contract and plungeai_execute_tool for those. Always answers with a structured outcome, never a raw error: follow the remediation instead of retrying the identical call.

• Read-only: no. Output schema: the outcome envelope. Creates an execution: yes (not for a refusal).

Returns. ok with the agent's output and the execution-id footer. unavailable for an unknown or inactive agent, with live alternatives and no run created. needs_input for a model that is not in the catalog (Unknown model `<id>` … Nothing was executed.) with up to five near matches. needs_approval / needs_input when the agent pauses. Failures are classified into an outcome.

Runs a model and costs credits (not verified here):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_execute_agent","arguments":{"user_request":"ask one-agent what a Durable Object is","agent":"one-agent","prompt":"In one sentence: what is a Cloudflare Durable Object?","model":"claude-sonnet-4-5","max_tokens":80}}}'

14.3 plungeai_get_tool_contract

The exact invocation contract for one registry agent: the JSON Schema of its parameters, its operations (with approval gates), worked YAML examples, its output shape, and your live credential status (platform-managed, or "connect Google first"). Fetch it before the first plungeai_execute_tool call to an unfamiliar agent: the contract is the API docs.

• Read-only: yes. Output schema: the outcome envelope. Creates an execution: no.

Returns. ok, whose contract holds agent_id, name, description, operations[] ({name, description?, required_params?}), inputSchema (JSON Schema for params), examples[] ({title, cnl}), output_type, soleRequiredParam (when exactly one string parameter is required) and credentials[] (per provider: provider, tier = platform / oauth_connector / byok_api_key, required, optional operations, connected, status, accountEmail). The Markdown adds a Credentials section (platform-managed, ✅ connected as …, ⚠️ NOT connected or expired, with where to connect) and a ready plungeai_execute_tool line. unavailable for an unknown or inactive agent, with alternatives. error if the registry did not answer.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_get_tool_contract","arguments":{"user_request":"what does the weather agent need from me?","agent_id":"weather-agent"}}}'

14.4 plungeai_execute_tool

Execute one structured tool-agent directly with typed params: {agent_id, operation?, params}. Runs through the engine with full observability; use mode:"async" for long runs. Always answers with a structured outcome, never a raw error: ok → the result; needs_input → the missing fields and the schema; needs_connection / needs_api_key → tell the user exactly what to connect in our apps, then retry; needs_approval → relay the ⏸ block and use plungeai_continue after the user decides; unavailable → real alternatives. Follow the remediation; do not retry the identical call blind.

• Read-only: no. Output schema: the outcome envelope. Creates an execution: yes (not for a refusal).

Returns. Checks run in this order, and every refusal happens before a run exists: the active-only card check (unavailable), contract validation (needs_input with missing and the contract), the credential pre-flight (needs_connection / needs_api_key). Then the engine runs the task: ok with the result, any warnings, and the execution-id footer; needs_approval when an outward, irreversible operation (send, pay, transfer, buy, withdraw) is stopped by the trust fence, with nothing run, no remediation actions and no paused session: despite the description's plungeai_continue hint, plungeai_continue cannot resume it, and it runs only from Ocean Studio (6.6); needs_approval / needs_input when the agent pauses (⏸ AWAITING USER APPROVAL / ⏸ AWAITING USER), which plungeai_continue does resume; a classified outcome on failure.

Runs a tool agent and creates an execution (not verified here):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_execute_tool","arguments":{"user_request":"current weather in Sun Valley, Idaho","agent_id":"weather-agent","operation":"current","params":{"location":"Sun Valley, Idaho"}}}}'

14.5 plungeai_run_mission

Run a bounded autonomous agent mission (a loop agent): a goal, an optional tool fence and an iteration cap. Recalls and writes long-term memory automatically. Defaults to async: poll plungeai_get_workflow_status. Always answers with a structured outcome, never a raw error: follow the remediation instead of retrying the identical call.

• Read-only: no. Output schema: the outcome envelope. Creates an execution: yes. There is no format parameter.

Returns. Async: ok with Started mission `<id>` (async). … and the execution id. Sync: ok with the mission's output (also when it stopped at max_iterations: a sync mission never reports incomplete, 7.7), needs_approval / needs_input when it pauses, or a classified outcome on failure.

Runs an agent loop and costs credits (not verified here):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_run_mission","arguments":{"user_request":"what is notable about Sun Valley, Idaho?","goal":"Three sourced bullets on what is notable about Sun Valley, Idaho.","max_iterations":6,"success_criteria":["three bullets","a source URL per bullet"]}}}'

14.6 plungeai_learn

Manage your private skill library. action: learn (the default) distills a URL, PDF text or a past workflow into a reusable skill with the learn pre-built agent (needs source; defaults to async, poll plungeai_get_workflow_status). action: list returns your learned skills (id and summary). action: forget deletes one by name (the id from list). Always answers with a structured outcome, never a raw error: follow the remediation instead of retrying the identical call.

• Read-only: no. Output schema: the outcome envelope. Creates an execution: learn only.

Returns. learn: ok with the execution id to poll (async), or the run's result (sync). list: ok with N learned skill(s). and one line per skill, or No learned skills yet.. forget: ok Forgot skill `<name>`., or needs_input (no name), error (no such skill), unavailable (not yours). See Skills.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_learn","arguments":{"user_request":"what skills have I learned?","action":"list"}}}'

14.7 plungeai_list_agents

Discover platform building-block agents in the live registry, the capability catalog. These are registry agents, not the user's own agents: for "show me my agents / workflows" use plungeai_list_workflows. search is a hybrid semantic and keyword query: describe the capability in natural language (for example "web search", "pdf to markdown"). Prefer search / category filters; an unfiltered list returns the whole catalog (about 90 agents, large). The catalog is active-only and execution refuses any id that is not active, so take ids from here, not from memory. Fetch one full card with agent_id. With format:"json" the result is {content: <markdown>}: its source is rendered registry markdown, and typed rows are a follow-up.

• Read-only: yes. Output schema: none. Creates an execution: no.

Returns. Registry Markdown: the matching cards, or one full card for agent_id. The active-only filter applies to kind: "agents". An agent_id that does not exist, or is not active, gets an explanation and the closest live matches instead of the card. Registry unavailable — try again shortly. (isError: true) when the registry does not answer.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_list_agents","arguments":{"user_request":"which agents can search the web?","search":"web search"}}}'

14.8 plungeai_list_workflows

List your saved workflows, which is what users usually mean by "my agents". With no filters it shows your folders (rubrics) and your most recent workflows; filter with folder, search and/or kind.

• Read-only: yes. Output schema: none. Creates an execution: no.

Returns. Without filters: # Your Workflows (N most recent), a Folders: line with every non-empty folder and its count, and a table: Name, Kind, Folder, ID, Description. With filters: # Your Workflows (N) and the same table. No workflows found. … / No workflows matched. … when empty. JSON: {"workflows": [{id, name, description, kind, folder}]}.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_list_workflows","arguments":{"user_request":"show me my workflows in the Finance folder","folder":"Finance","format":"json"}}}'

14.9 plungeai_get_result

Retrieve the result of one of your executions by execution_id. For conversational runs it includes the full conversation thread (all follow-up turns), as Studio shows it. Pass task_id to read one task's output (for example one branch of a workflow) instead of the final result. The output is final, user-ready Markdown: show it verbatim and complete, never summarize or re-type it. With format:"json" the result is the GET /v1/executions/{id}/output body (execution_id, status, content, final_task_id, steps, continuation), not the rendered thread; with task_id it is {execution_id, task_id, result}.

• Read-only: yes. Output schema: none. Creates an execution: no.

Returns. The full result: an identity line, the final output, a Steps in this run index for multi-step runs, the Conversation thread when there are follow-up turns, and a ⏸ block when the run is paused. When there is no output it says why: failed, still running, or no longer stored. An unknown or foreign id is needs_input. Details: 9.2.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_get_result","arguments":{"user_request":"show me the result of that last run","execution_id":"<execution_id>"}}}'

14.10 plungeai_get_workflow_status

Check the status of one of your executions (it self-heals stuck runs). It also returns structured content, including continuation when the run is paused awaiting the user's approval or answer: relay that to the user and use plungeai_continue.

• Read-only: yes. Output schema: the status object. Creates an execution: no. There is no format parameter; structuredContent is always present.

Returns. A Markdown status block and structuredContent with execution_id, status (running, completed, incomplete, failed, cancelled; incomplete only for async runs, since a sync call stamps its run ok, which then reads completed), error_message, workflow_name, started_at, duration_ms, final_task_id and continuation ({status, agent, question, pending_action} or null). A running row with a stored result is healed to completed; one with no heartbeat for more than 960 seconds is marked failed (Interrupted (run did not complete); the reason shows from the next read on). Details: 9.3.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_get_workflow_status","arguments":{"user_request":"is that still running?","execution_id":"<execution_id>"}}}'

14.11 plungeai_workflow

Manage your saved workflows: action create, get, update, delete, save_version, list_versions, get_version, restore_version or a2a_door. Create, update and delete sync live to Studio, iMini and the other apps. a2a_door manages the workflow's Agent2Agent door (see 8.6). The bot actions work on a saved bot you own: permissions_get / permissions_set (class presets, admin locks, spend caps), files / file (its persistent workspace), inbox, bindings / bind / unbind (paired chats) and, by group name, groups / group_set / group_delete / group_thread.

• Read-only: no (get, list_versions and get_version only read). Output schema: none. Creates an execution: no.

Returns. create: Created workflow **<name>** (`<id>`). … Synced to all apps., with Filed under **<folder>**. or a ⚠️ note when the folder did not match (then it is created without a folder). get: the name, description and YAML, or needs_input when not found. update: Updated workflow `<id>`. Synced to all apps. with folder and kind notes; an unknown folder refuses the whole update. delete: Deleted workflow `<id>`. …; a bot's memory namespace <you>:bot:<id> and scheduler jobs, or a campaign's jobs and ledger, are cleaned up after the row is gone (best effort; update with a kind that leaves bot or campaign does the same for the old kind). save_version: Saved version V<n> (`<version id>`).. list_versions: a table of Version, ID, When, Note. get_version: that version's YAML. restore_version: Restored — new version V<n>.. a2a_door mint: A2A door **<url>** minted for **<name>**. with the token (shown once; minting again rotates it), the agent-card URL and a curl SendMessage recipe; get: the door's URL, status and kind, or No A2A door for **<name>** yet.; pause/resume: A2A door of **<name>** is now paused|active.; revoke: A2A door of **<name>** revoked — …. permissions_get / permissions_set: the classes, locks and caps as a list and a JSON block; permissions_get also lists effective, the preset each of the four classes runs under (the stored one, else allow). files: a table of path, size, type and update time; file: the file name, type and size and the bytes as a base64 block (a file over 5 MB is refused file_too_large with its One API download path). inbox and group_thread: a table of the queued messages. bindings: the chats bound to the bot, or a note when channel bindings are not enabled yet; bind / unbind: a confirmation. groups, group_set, group_delete: the groups and the change. Every bot refusal is Error: <message> (<code>) with the same codes as the One API (workflow_not_found, lock_admin_required, invalid_params, file_not_found, not_paired, name_taken, …). A workflow you do not own answers Workflow not found. on update / delete and the version actions (get returns a needs_input outcome), but Error: no saved workflow with that id for this account (workflow_not_found) on the bot actions above (and a group you do not own, addressed by name, answers Group "<name>" not found.). CNL validation and kind-lint warnings are appended; a validation or kind-lint error (for example memory_owner in the YAML) refuses the save (Workflow YAML failed CNL validation: …). A missing required field answers Error: <field> is required for action "<action>".

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_workflow","arguments":{"user_request":"show me my Acquisition Scanner workflow","action":"get","workflow_id":"<workflow_id>"}}}'

14.12 plungeai_executions

Browse your execution history: action list, get, output, conversation, files, delete, cancel or steer. cancel stops a running execution cooperatively: it stops at its next turn or tool boundary. steer queues a message for a running execution, delivered at its next turn; files lists the files the run wrote. Outputs are final, user-ready Markdown (tables, threads): show them verbatim and complete, never summarize or re-type them.

• Read-only: no (delete and cancel change state). Output schema: none. Creates an execution: no.

Returns. list: # Executions (N), newest first (ID, Question, Workflow, Status, Source, When); JSON {"executions": [{id, input, workflow_name, status, start_time, duration, source}]}. get: the status answer of plungeai_get_workflow_status. output: the full result of plungeai_get_result. conversation: the follow-up thread; JSON {execution_id, messages}. cancel: Cancelling execution `<id>` — … (running runs only). steer: Queued your message to running execution `<id>` …, or an error when the run already finished (use plungeai_followup). files: a table of the files the run wrote. delete: Deleted execution `<id>`.; this cannot be undone. Details: 9.4.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_executions","arguments":{"user_request":"show me my last 5 executions","action":"list","limit":5,"format":"json"}}}'

14.13 plungeai_followup

Ask a follow-up about a completed execution: it continues the run's agent session, or researches with the prior context. If the execution is still running, the message is queued and injected at its next turn (steering); if it has finished, the conversation continues.

• Read-only: no. Output schema: none. Creates an execution: no; the turn is added to the run's conversation thread.

Returns. Running: Queued your message to running execution `<id>` (delivered at its next turn). Finished: the answer as Markdown, plus a ⏸ block if the agent pauses again. Errors (isError: true): Execution not found., Followup agent call failed, Failed to retrieve follow-up response. Details: 9.5.

Runs a model and costs credits (not verified here):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_followup","arguments":{"user_request":"now focus on the competitive landscape","execution_id":"<execution_id>","prompt":"Do the same analysis, but focus on the competitive landscape."}}}'

14.14 plungeai_continue

Continue a paused conversation: answer a question (message) or approve a pending action (approve: true). Pass approve: true only after the user explicitly confirmed; never approve on your own. To deny or change course, pass the user's words as message.

• Read-only: no. Output schema: none. Creates an execution: no; the agent runs again inside the paused run.

Returns. The agent's reply, then either a new ⏸ block or ✅ Conversation resolved (no further input needed). It resumes an agent pause (⏸ AWAITING USER APPROVAL / ⏸ AWAITING USER); a trust-fence ⏸ NEEDS APPROVAL with no actions has no session and answers No conversation session… (6.6). Errors (isError: true): Provide `message` or `approve: true`, Execution not found, No conversation session for this execution (expired or not a conversational agent), This run isn't paused — it already completed. Use plungeai_followup …, Agent continuation failed. Details: 9.6.

Runs the held action, which may spend money; send it only after the user said yes (not verified here):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_continue","arguments":{"user_request":"yes, go ahead","execution_id":"<execution_id>","approve":true}}}'

14.15 plungeai_chat

Persistent chat with the PlungeAI assistant (platform tools and web search): action send, new, list_sessions or history. Conversations appear in Studio and the CLI.

• Read-only: no (list_sessions and history only read). Output schema: none. Creates an execution: no.

Returns. send: the assistant's reply and _(conversation: `<id>`)_. new: Created conversation `<id>`. …. list_sessions: # Your conversations (N) (Title, ID, Messages) for the 20 most recent, or No conversations yet.. history: # <title> and every turn. Details: 10.1.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_chat","arguments":{"user_request":"list my conversations","action":"list_sessions"}}}'

14.16 plungeai_build_workflow

Generate a new workflow from a goal, or refine an existing one (workflow_id + instruction), with the platform builder. The result is saved, so it appears everywhere (live sync).

• Read-only: no. Output schema: none. Creates an execution: no; it creates or updates a saved workflow.

Returns. New: Created workflow **<name>** (`<id>`). Synced to all apps. Run it with plungeai_execute_workflow. and the YAML. The name is the builder's own generated name, or the first 60 characters of the goal when the YAML has no plain name: line. Refine: Updated workflow **<name>** (`<id>`). Synced to all apps. and the YAML; the YAML is replaced in place, so save a version first if you may want to roll back. A generated workflow that fails CNL validation is not saved; the answer shows the errors and the YAML. Other errors (isError: true): Provide either `goal` (new) or `workflow_id` + `instruction` (refine)., Workflow not found: <id>, Workflow builder did not return a workflow section. It reports generating, validating and saving on the progress channel while it works (30–60 seconds).

Runs a model, costs credits and saves a workflow (not verified here):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_build_workflow","arguments":{"user_request":"build me a workflow that scans a company for acquisition news and writes a briefing","goal":"Scan a company for acquisition news and write a one-page briefing with sources."}}}'

14.17 plungeai_memory

Long-term memory scoped to you: action recall, remember, search_runs, get_run or forget. remember writes the durable store that recall reads (target user or memory, operation add, replace, remove or read); use it when the user asks to remember something. Past-run history is separate: search_runs / get_run read the run journal, which recall deliberately does not include.

• Read-only: no (remember writes, except operation: "read"; forget deletes). Output schema: none. Creates an execution: no.

Returns. recall: both stores (memory, then the user profile), or No memory recorded yet.. remember: Saved to memory (<usage>). recall will see it immediately., or for read the entries under # Memory (<target>); a write over the budget is refused with the current entries. search_runs: # Matching runs with `<run id>` — <goal> lines. get_run: the stored run, or Run not found.. forget: Forgot <n> memory entries., or Memory entry not found. for an id your stores do not hold. Details: 10.2.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_memory","arguments":{"user_request":"what do you remember about our fiscal year?","action":"recall"}}}'

14.18 plungeai_templates

Workflow templates: action list, get or use. use creates a workflow in your account from the template (optional name and folder).

• Read-only: no (list and get only read; use creates a workflow). Output schema: none. Creates an execution: no.

Returns. list: # Workflow Templates (N) with Name, Kind, Category, Difficulty, Used, ID and Description, featured templates first, or No active workflow templates.. get: the template's name, description, category, difficulty, use count and YAML. use: Created workflow **<name>** (`<id>`) from template **<template>**. … Run it with plungeai_execute_workflow.; the template's use count goes up by one. Errors (isError: true): template_id is required for this action., Template not found: <id>, Template content missing from storage..

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_templates","arguments":{"user_request":"what workflow templates are available?","action":"list","limit":10}}}'

14.19 plungeai_schedule

Scheduled (cron) jobs: action stats, list, get, create, update, pause, resume, delete, run_now, runs or wake. create needs name, job_type (agent, query, workflow or heartbeat), target and schedule; create also takes mission_ref to schedule a pre-built agent card, ends_at to stop the job at a time, and schedule: "@once" with run_at for a one-time run. wake fires the job's saved workflow once with a note. The triggers of a job are the actions webhook_mint / webhook_list / webhook_delete / webhook_rotate, email_mint / email_list / email_delete / email_rotate and hooks_mint / hooks_list / hooks_delete. A rotate mints a successor with the same settings, then revokes the old trigger.

• Read-only: no (stats, list, get and runs only read). Output schema: none. Creates an execution: run_now and every scheduled tick do, except for heartbeat jobs (11.3).

Returns. Markdown text per action: tables for list and runs, the job as JSON for get, a one-line confirmation for the writes, and for run_now the execution id to poll. wake: the time the woken run starts. The trigger actions answer with the scheduler's JSON in a block: a mint or a rotate shows its secret once and never again. Errors are isError: true text that names the cause. Details: Scheduling.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_schedule","arguments":{"user_request":"what do I have scheduled?","action":"stats"}}}'

14.20 plungeai_whoami

Show the authenticated identity: user id, tier, key label and rate-limit window.

• Read-only: yes. Output schema: none. Creates an execution: no.

Returns. # Who am I with User, Auth (type and tier), Key (label and key id), Rate window (<n>/min used · <n>/day used, left out when the counter cannot be read) and Server. JSON: {"user", "auth_type", "tier", "key_label", "key_id", "rate_window": {"minute_used", "day_used"} or null, "server"}. Details: Authentication & keys.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_whoami","arguments":{"user_request":"who am I?"}}}'

14.21 plungeai_companies

Your companies, action for action the One API's /v1/companies: a campus compiled from your saved campus, building and office documents (kind: campus / building workflows), its items, the gates at its door, its mode and its clock. Every rule lives in company-service; the tool calls it as you. A campus you do not own is the same not_found as one that does not exist.

• Read-only: no (list, layout, snapshot, events, slice and approvals only read). Output schema: none; every answer also carries structuredContent. Creates an execution: decide with approve on a tool permission continues the paused execution once; the company's clock starts office runs after start.

Returns. A heading line and the One API's response body as a JSON block, the same body as structuredContent. A refusal is isError: true text <word>: <message> (<code>) with structuredContent.error = {status, code, message}, the word standing for the REST status: invalid (400/422), forbidden (401/403), not_found (404), conflict (409), unavailable (5xx). delete of a running campus is conflict (stop it first). Details: Companies.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_companies","arguments":{"user_request":"which companies do I have?","action":"list"}}}'

14.22 plungeai_connections

Your connected accounts, action for action the One API's /v1/connections: list, add (an API key for a key-based provider), remove, link (a signed single-use Studio link to connect a provider). on_behalf_of acts on one of your customers instead of you.

• Read-only: no (list only reads; every list is written to the secrets audit log). Output schema: none; every answer also carries structuredContent. Creates an execution: no.

Returns. A heading line and the One API's response body as a JSON block, the same body as structuredContent: list {connections: [{provider, on_behalf_of, method, status, connected_at}]} (never key material), add {provider, on_behalf_of, status: "connected"}, remove {…, status: "disconnected"}, link {url, expires_at} (15 minutes, single use). Refusals use the same <word>: <message> (<code>) shape as plungeai_companies: not_found unknown_provider / connection_not_found, invalid missing_api_key / credential_rejected / invalid_on_behalf_of / invalid_return_url, forbidden owner_not_found, unavailable connections_unavailable. Details: Connections.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_connections","arguments":{"user_request":"what accounts have I connected?","action":"list"}}}'