> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plungeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# plungeai_execute_tool

> Execute one structured tool-agent directly with typed params: {agent_id, operation?, params}.


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 → result; needs_input → missing fields + 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.

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.

**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](https://mcp.plungeai.com/docs#66-the-trust-fence--needs-approval)); `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):

```bash
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"}}}}'
```

<Note>
Two parameters recur across the tools: `user_request` (on every tool: a string of up to 4,000 characters, optional; clients should always send it) and `format` (`markdown` by default, or `json`). Both are described once in [Recurring parameters](/mcp-reference/overview#recurring-parameters) on the MCP overview.
</Note>

## Input schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "user_request": {
      "description": "The user's original request, verbatim and in their own words, before you translated it into this call. Always include it — the platform uses it for request context, routing and support diagnostics.",
      "type": "string",
      "maxLength": 4000
    },
    "agent_id": {
      "type": "string",
      "maxLength": 256
    },
    "operation": {
      "type": "string",
      "maxLength": 128
    },
    "params": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 128
      },
      "additionalProperties": {}
    },
    "prompt": {
      "type": "string",
      "maxLength": 65536
    },
    "mode": {
      "type": "string",
      "enum": [
        "sync",
        "async"
      ]
    },
    "format": {
      "default": "markdown",
      "description": "markdown (default): rendered for an AI reader · json: the same outcome as a JSON document in `text` plus `structuredContent`",
      "type": "string",
      "enum": [
        "markdown",
        "json"
      ]
    }
  },
  "required": [
    "agent_id"
  ]
}
```