Tools

Source: orchestration/mcp-gateway/tool-exec.ts (ExecuteToolSchema, executeTool), orchestration/mcp-gateway/tool-outcome.ts (ToolOutcome, renderOutcome, pauseOutcome, classifyExecutionError), orchestration/mcp-gateway/credential-preflight.ts, orchestration/mcp-gateway/registry-cards.ts, orchestration/mcp-gateway/execution.ts, orchestration/mcp-gateway/execution-do.ts, orchestration/mcp-gateway/conversation.ts, orchestration/mcp-gateway/server.ts, orchestration/mcp-gateway/index.ts (argument pre-screen), core/core-base/tool-contract.ts, core/core-base/call-agent.ts (ALWAYS_GATED), orchestration/cnl-engine/dispatch.ts (gatedDispatchOp); live registry cards read 2026-09-24.

A structured tool-agent is a registry agent whose card has a Parameters table: weather-agent, markitdown, google-gmail, resend, x402-wallet-agent, … It takes typed fields, not a sentence. plungeai_execute_tool runs one operation of one such agent. It uses the same engine pipeline as every other execution tool, so the run lands in your execution history, shows in Studio's sidebar, and can be followed up. Every answer is a structured outcome, never a raw error.

Find      ──►  plungeai_list_agents          the agent id                     (Discovery)
Inspect   ──►  plungeai_get_tool_contract    fields, operations, gates, your credentials
Execute   ──►  plungeai_execute_tool         pre-flight checks → engine → outcome

Base URL https://mcp.plungeai.com/v1. https://api.plungeai.com/v1/mcp is the same server; the One API also has a REST twin of this chapter (https://api.plungeai.com/docs#6-tools-plane (opens in a new tab)). Always pass user_request (Protocol & transport). Parameter types and limits are in the Tool reference.

6.1 Run a tool — plungeai_execute_tool

Your client usually does this for you. It fetches the contract, fills the form, then calls the agent. You just ask.

Try asking: "Give me a five-day weather forecast for Sun Valley, including air quality." The client runs weather-agent with typed fields, by place name, with no coordinates needed. The weather agent covers the full OpenWeather surface: current conditions, hourly and daily forecasts, air quality, geocoding and more. Here that means two calls, forecast and air-quality, or one one-call.

This call runs a real agent and writes an execution to your history (not run by the docs verifier):

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":"Give me a five-day weather forecast for Sun Valley, including air quality.","agent_id":"weather-agent","operation":"forecast","params":{"location":"Sun Valley,ID,US","units":"imperial"}}}}'

A tools/call answers as a text/event-stream: live progress frames first, then the result (4.6). On success the result text is the agent's own output, followed by the execution footer:

…the forecast, as the agent rendered it…

---
execution: `<execution id>` — use this id for plungeai_get_result / plungeai_followup on this run.

structuredContent carries the envelope:

{
  "status": "ok",
  "agent_id": "weather-agent",
  "operation": "forecast",
  "summary": "`weather-agent · forecast` completed.",
  "result": "…",
  "execution_id": "<execution id>"
}

The run appears in your history as weather-agent · forecast. Its title is your user_request (or the prompt, or the params with secrets redacted, at most 500 characters).

6.2 What happens on a call

The order is fixed (executeTool in tool-exec.ts). Steps 1–4 can refuse the call, and a refusal there is not a run: nothing is dispatched and no execution is written.

1. Argument check. The gateway validates the arguments against the tool's inputSchema before the tool runs (validateToolArgs, index.ts). A missing agent_id or an out-of-range value returns needs_input ("plungeai_execute_tool was not called — its arguments do not match the tool's schema.") with the fields named.
2. Card fence (active-only). An unknown id returns unavailable ("No registry card with id <id> exists — agent ids cannot be guessed or carried over from other platforms. Nothing was executed."). An inactive card returns unavailable ("<id> is registered but not status:active — only active agents are callable over MCP."). Both include up to three live alternatives. If the registry itself does not answer, the call proceeds (fail-open) with a thin contract, and the engine is the backstop.
3. Contract validation. Params whose names belong to the task envelope (agent, type, id, operation, depth, user_id, executor_user_id, workflow, execution_id) are rejected with needs_input "These params collide with task-envelope fields and cannot be passed". Missing required fields (global, plus the chosen operation's required_params) are rejected with needs_input "Required parameters are missing. Nothing was executed.", with the full contract attached. The missing-field check is skipped when you send a prompt.
4. Credential pre-flight. If the agent needs one of your connected accounts or your own key and it is not connected, expired or in error, the answer is needs_connection or needs_api_key with the exact thing to connect (6.7). This check fails open: if the status lookup fails, the call proceeds.
5. Selector fill and prose mapping (6.3).
6. Execution row. A row opens in your history (workflow_executions, status running).
7. Dispatch. mode: "async" hands the run to its execution Durable Object and returns at once (6.8). Sync runs the engine and streams progress.
8. Engine fence. An outward, irreversible operation is refused here, before the agent is called (6.6).
9. Outcome. A failure is classified into the outcome vocabulary (6.4). A success is checked for a pause (approval or question), then returned. The classified status is also written to the execution's outcome column, so dashboards and D1 agree with what your client saw.

6.3 Typed params, prose and operations

Cards are written by people and under-document. The gateway smooths five things. All but the first add a ⚠️ warning line to a successful answer (warnings[] in structuredContent):

• Operation selector. The envelope carries operation, but many agents read their operation from a param named action, op or operationType, and silently run their default when it is absent. If the card declares one of these params and you did not set it, operation is copied into it. For example, resend reads action.
• Prose onto the one required field. If you send only a prompt (no params), and the card's requireds come down to exactly one free-text string field, the prompt is passed as that field. A report generator whose only required field is content is one example. You then get the warning "prose mapped: your prompt was passed as <field> (this card's only required parameter). If that is not what you meant, retry with typed params." The prompt is never mapped into an operation selector, an enum field, or a URL field (action, op, operation, operationtype, function, endpoint, url, uri, link): a sentence is not an action name and not a URL.
• Prose on a multi-operation card. A structured agent does not interpret a prompt. Without operation it runs its default operation, which reads as success while ignoring the request. So you get the warning "structured agent: the prose prompt is not interpreted — without operation it ran its default operation. For anything else, pick an operation from the contract and pass typed params."
• Unknown operation. An operation that is not on the card is not rejected; the call proceeds with a warning, because cards can under-document.
• Extras and aliases. Params not on the card are passed through verbatim (params not on the card (passed through verbatim): …). When a card marks two alternative fields both required (query and prompt), filling one is enough (card also marks … required — likely alias/alternative fields; proceeding with what you provided.).

If a form is still missing something, the answer names the exact fields and shows the form. It never comes back as a bare error, so "do what it suggests" is always enough.

6.4 The outcome vocabulary

Every plungeai_execute_tool answer, and every other execution tool's answer, is one ToolOutcome (tool-outcome.ts). It is sent as Markdown text plus the same object as structuredContent, and the tool's outputSchema declares it:

{
  "status": "ok | needs_input | needs_connection | needs_api_key | needs_approval | unavailable | error",
  "summary": "…",
  "agent_id": "…", "operation": "…",
  "result": "…", "execution_id": "…",
  "missing": ["…"], "warnings": ["…"],
  "remediation": { "message": "…", "actions": [ { "action": "…" } ] },
  "contract": { }
}

isError is true only for error. The guidance statuses are answers your client acts on, not protocol failures (MCP Tools → Error Handling). JSON-RPC protocol errors are kept for the edge: authentication, rate limits, unknown tools and malformed requests (Errors, feedback & limits).

A non-ok answer is rendered in this order (renderOutcome):

📝 NEEDS INPUT — `weather-agent` air-quality-history

Required parameters are missing. Nothing was executed.

Missing required: `start`, `end`

**To proceed:** Fill the missing fields (contract below) and retry the same call.
- Provide `start` — Unix start time — (operation: air-quality-history, required there) and retry the same call.
- Provide `end` — Unix end time — (operation: air-quality-history, required there) and retry the same call.

---
# Weather Agent (`weather-agent`)
…the full contract…

_This is structured guidance, not a crash — do not retry the identical call. Follow the remediation, or relay it to the user._

That is the real answer for {"agent_id":"weather-agent","operation":"air-quality-history","params":{"location":"Sun Valley,ID,US"}} (rendered from the live card, 2026-09-24). It is refused before dispatch, so it is free and writes no execution. When the outcome carries an execution id, an _(execution: …)_ line comes before the last line. Warnings follow at the end as ⚠️ lines.

A refusal is not a run. The argument check, the card fence, contract validation and the credential pre-flight all answer before an execution exists, so your history stays clean. From step 6 on, an execution row exists, even when the outcome is needs_input (the agent rejected its inputs), needs_approval (the engine fence) or error.

Classification of run failures

When a run fails inside the engine, classifyExecutionError maps the raw error, in this priority order:

1. An explicit [outcome:<status>] tag from the agent or engine wins. The tag is stripped from the text.
2. A declared needs_approval becomes the trust-fence answer (6.6).
3. "requires a valid license" → needs_connection (an external license constraint: the connected tenant needs a license from its admin; not a wrong call).
4. ACCESS_TOKEN_SCOPE_INSUFFICIENT / "insufficient authentication scopes" → needs_connection: reconnect in Studio to grant more scopes.
5. A named missing key ("… API key not configured", "No … API key available") or developer_token → needs_api_key.
6. 401, "invalid authentication", UNAUTHENTICATED → needs_connection, or needs_api_key when the agent declares a bring-your-own key and no OAuth connector. The provider is named when the agent declares one (only plungeai_execute_tool passes the declared credentials to the classifier).
7. "service binding … not found" → unavailable ("registered but not deployed … a platform-side gap").
8. Bad-input phrasing ("missing", "invalid parameters", "please provide", "unknown operation", …) → needs_input with the contract attached.
9. A timeout → error with Retry with {"mode":"async"} — then poll plungeai_get_workflow_status.
10. Anything else → error: Execution failed: <the real message, up to 800 characters>.

Two guarantees come with it. Limits are told to you, never silently applied: search agents declare their maximum query length on the card (for example brave-agent: "Maximum: 400 characters — over-limit queries refused"), and an over-limit query comes back as needs_input instead of being truncated. Provider failures surface with the real reason: a provider stream that fails leaves an error record, so the run reports the provider's error instead of waiting out a streaming timeout (execution.ts).

6.5 Remediation actions

remediation.actions[] is machine-readable. Each action also renders as one bullet under To proceed::

The rule for clients, which the server also sends in its initialize instructions: follow the remediation, never retry the identical call blind, and never approve a gated action on your own. For needs_connection and needs_api_key, the step needs the user's browser. Relay it, wait for them to confirm, then retry the identical call. Your client usually self-corrects on needs_input: "do what it suggests" is enough.

6.6 The trust fence — NEEDS APPROVAL

Some operations are outward and irreversible: they move money or cause real-world side effects. The platform will not run them unattended. Two mechanisms produce needs_approval.

1. The engine floor refuses outright. The floor list is fixed in code and no YAML, prompt or card can remove it (ALWAYS_GATED, core/core-base/call-agent.ts):

buy · purchase · fetch_paid · send · transfer · pay · send_payment · withdraw · shop

At every deployed-agent dispatch, the engine reads the task's operation (or action). If it is on the list, the engine refuses before the agent is called (gatedDispatchOp, orchestration/cnl-engine/dispatch.ts). The MCP answer:

⏸ NEEDS APPROVAL — `resend` send

This operation is outward and irreversible (it can move money or cause real-world side effects) and will NOT run unattended. operation "send" on resend is gated (outward/irreversible) and requires human approval — it cannot run unattended.

**To proceed:** Relay this to the user and get their explicit go-ahead before it runs. Never approve it on your own. To perform it, run it from an interactive session (Ocean Studio) where a human can approve the action.

_(execution: `<execution id>`)_

_This is structured guidance, not a crash — do not retry the identical call. Follow the remediation, or relay it to the user._

Nothing reached the agent. plungeai_execute_tool and plungeai_execute_agent refuse a floor operation before a run exists, so no execution row is written; a floor operation that only appears at run time (a templated operation in a workflow task) is refused by the engine and leaves a failed execution with outcome needs_approval. There is no paused session behind either, so plungeai_continue cannot resume it (it answers "No conversation session for this execution (expired or not a conversational agent)"). The operation can only run from an interactive session where a human approves it: Ocean Studio. The same floor applies to any task in a workflow you run with plungeai_execute_workflow.

This request is refused by design (not run by the docs verifier):

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":"Email the report to the team","agent_id":"resend","operation":"send","params":{"from":"reports@example.com","to":"team@example.com","subject":"Weekly report","text":"…"}}}}'

2. An agent stages the action and pauses. Agents with their own approval step (the x402 broker, the concierge, bots) stop before spending and store a pending action. The run comes back as:

⏸ NEEDS APPROVAL — `x402-broker`

⏸ AWAITING USER APPROVAL: <the staged action> (<its price>). Relay this to the user verbatim and ask them to decide — NEVER approve on your own.

…the agent's own message so far (what it found, what it proposes)…

**To proceed:** User approval required before the action runs.
- Ask the user to approve, then call plungeai_continue {execution_id: "<id>", approve: true}. NEVER approve on your own.

_(execution: `<id>`)_

_This is structured guidance, not a crash — do not retry the identical call. Follow the remediation, or relay it to the user._

Here plungeai_continue is the way forward, and only after the user said yes (Runs, results & follow-ups).

Card-level gates. A card can mark more operations with gated:<op> tags (for example x402-broker → gated:execute). The contract shows them as ⚠️ GATED. The MCP gateway checks card tags itself before the run: a typed call that names a gated: operation comes back ⏸ NEEDS APPROVAL. A prompt-only call to the broker carries no operation, so it reaches the agent, which stops for approval before it pays. For the broker, the agent itself always stops for approval before paying (its card: "execute (pay-and-call in USDC — always stops for user approval, never auto-runs)").

Payment and blockchain categories. Agents in the payment and blockchain categories are not callable over MCP unattended, whatever the operation, exactly as on the One API's tools plane (https://api.plungeai.com/docs#6-tools-plane (opens in a new tab)). plungeai_execute_tool, plungeai_execute_agent and every task of plungeai_execute_workflow come back ⏸ NEEDS APPROVAL with nothing run. Today that is crossmint-agent, x402-wallet-agent, circle-agent and circle-wallet-agent, read operations included. Run them from Ocean Studio, where a human approves. Inside a mission, the loop's call_agent refuses gated operations and payment/blockchain agents unattended.

6.7 Connected accounts and your own keys

Some agents act as you: your Gmail, your OneDrive, your wallet. They need a credential only you can provide. The requirement comes from one ladder (resolveCredentialRequirements, credential-preflight.ts):

1. cred:<tier>:<provider> tags on the card (authoritative, for example x402-wallet-agent → cred:byok_api_key:x402-wallet);
2. else a curated map of 40 agents (frozen; new agents declare credentials on their card);
3. else platform-managed: nothing for you to connect.

Where you connect: Ocean Studio, https://studio.plungeai.com (opens in a new tab) → Connectors. Connect once. Every surface (MCP, Studio, the apps, the One API) then uses the same connection. For how accounts flow into calls, see https://api.plungeai.com/docs#7-connectors--connected-accounts (opens in a new tab).

When it is checked:

• plungeai_get_tool_contract shows the live status: "✅ connected as you@…", "⚠️ NOT connected", or "expired — reconnect" (5.4).
• plungeai_execute_tool checks before anything runs. A missing, expired or errored required credential returns needs_connection (if any unmet requirement is OAuth) or needs_api_key (if all are bring-your-own-key). The summary names the state (not connected, expired — reconnect it, in error state — reconnect it) and ends "Nothing was executed." The remediation says: "This needs the user, not you: relay the connect step to them, wait for confirmation, then retry the identical call." A connect_provider action includes up to eight OAuth scopes.
• plungeai_execute_agent and plungeai_execute_workflow do not pre-flight. A missing credential surfaces when the run fails (401 → needs_connection), and the answer asks you to connect "the required service", because those paths do not pass the agent's declared provider to the classifier.

The pre-flight fails open. If the status service does not answer, the call runs and the run-time classification (6.4) is the backstop. Ask your client "what does this agent need?" to see the live status before first use.

6.8 Long runs: mode: "async"

mode: "async" returns immediately with an ok outcome and the execution id:

Started `weather-agent · forecast` (async). Poll plungeai_get_workflow_status with execution_id `<id>`, then fetch output with plungeai_get_result. If the status reports ⏸ AWAITING USER APPROVAL or AWAITING USER, relay it to the user and continue with plungeai_continue.

---
execution: `<id>` — use this id for plungeai_get_result / plungeai_followup on this run.

The run is held by its own Durable Object in ten-minute legs that resume from checkpoints (Workflows, 8.4). There is no live feed. Failures, pauses and results are read with plungeai_get_workflow_status and plungeai_get_result (Runs, results & follow-ups). Use async when a run may outlast your client's tool-call limit: Claude Desktop cuts a single call at about 4 minutes. For shorter runs the sync call keeps the stream alive with a heartbeat every 15 seconds.

6.9 Payments

Two agents handle money on the open x402 payment ecosystem. Both are active (live registry, 2026-09-24):

Try asking

• "Check my x402 wallet balance, then use the broker to find and buy access to a weather API." The wallet call is refused over MCP (payment category); the broker handles discovery and asks for your approval before it spends anything.
• "Use the x402 broker to find StablePhone and place a call to [phone number]." The broker discovers and pays for the calling service, asking your approval first, then places the call. Check on it afterwards with the broker (status).

The wallet is a payment agent, so every call to it over MCP comes back ⏸ NEEDS APPROVAL with nothing run, wallet_info included although it only reads. The refusal comes before the credential check, so it is the same with or without a connected wallet. Check your balance in Ocean Studio.

The broker takes a sentence. This runs a model and can lead to a purchase after your approval (not run by the docs verifier):

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":"Find an x402 weather API and tell me the price. Do not pay yet.","agent_id":"x402-broker","prompt":"Find an x402 weather API and inspect its exact live price at the origin. Do not pay anything."}}}'

A direct fetch_paid through plungeai_execute_tool is refused by the floor (6.6). Unattended, it never spends. Pay through the broker's approval flow, or from Ocean Studio.

The other money agents in the active catalog (live registry, 2026-09-24): crossmint-agent (payment, x402-wallet credential), circle-agent and circle-wallet-agent (blockchain, your Circle credentials) are refused over MCP whatever the operation, like the wallet. The shopping agents amazon-shopping-agent and shopping-zinc (ecommerce-agents) follow the floor list: any operation on it (buy, purchase, pay, transfer, withdraw, shop, …) comes back ⏸ NEEDS APPROVAL with nothing run. Check an agent's contract first: its ⚠️ GATED operations and its credential status are both listed there (5.4).

When a run pauses to ask you something

Some agents stop instead of finishing: always before spending money, and sometimes to ask a question ("which wallet?", "what should the call say?"). Your client relays it and waits for you:

1. The run comes back with ⏸ AWAITING USER APPROVAL (a staged action and its cost), as a needs_approval outcome, or ⏸ AWAITING USER (a question), as a needs_input outcome. Nothing has been executed yet.
2. Your client asks you to decide. Reply naturally: "yes" / "approve" to proceed, "no" or any other answer to change course. The client is instructed never to approve on its own.
3. On approve, the client calls plungeai_continue {execution_id, approve: true} and the held action runs exactly once. A stale or repeated approve is harmless: the agent answers that nothing is awaiting approval, and it can never pay twice. To deny or change course, the client passes your words as message.

Background (async) runs surface pending approvals too. plungeai_get_workflow_status returns them as structuredContent.continuation, and plungeai_get_result appends the ⏸ block, so a paused background run is never invisible (Runs, results & follow-ups).