> ## Documentation Index > Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # plungeai-tools-connectors > Call PlungeAI structured tool-agents with typed parameters against a published invocation contract: fetch the contract (`plungeai_get_tool_contract` / `GET /v1/tools/{id}`), execute with typed `params` (`plungeai_execute_tool` / `POST /v1/tools/{id}/execute`), see which credential a tool runs on… Call PlungeAI structured tool-agents with typed parameters against a published invocation contract: fetch the contract (`plungeai_get_tool_contract` / `GET /v1/tools/{id}`), execute with typed `params` (`plungeai_execute_tool` / `POST /v1/tools/{id}/execute`), see which credential a tool runs on (the card's `credential` tier), connect an account over the API (`/v1/connections`, `on_behalf_of` for your customers) and pair chat channels (`/v1/channels`), and handle the trust fence (gated/money operations refuse unattended — `403 refused` on REST, `needs_approval`/`needs_connection` outcomes on MCP). Use when a card has a Parameters table (document conversion, weather, data-table CRUD, calendar, payments, posting), before the first call to an unfamiliar tool, or when fixing a `422 invalid_params` / `403 refused` / `424 connection_required` response. For prompt-driven agents use `plungeai-agents`; for finding a tool id or contract use `plungeai-discovery`; for the model catalog use `plungeai-models`. [Download zip](https://skills.plungeai.com/plungeai-tools-connectors.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-tools-connectors/SKILL.md) A **tool** is a structured agent: instead of free-text prompts it takes **typed parameters** against a published contract — named operations, a JSON Schema for inputs, worked examples, per-operation approval gates, and (over MCP) the acting user's live credential status. The rule that prevents almost every tool failure: **fetch the contract before the first call to an unfamiliar tool — the contract IS the API documentation.** ## Prerequisites - Self-service `ozk_` key from **Dashboard → One API → Keys** (`https://dashboard.plungeai.com`). - MCP: `https://mcp.plungeai.com/v1`. REST: `https://api.plungeai.com`. ## Discovery first Find the tool (`plungeai_list_agents {search}` / `GET /v1/discovery/search`, see `plungeai-discovery`), then fetch its contract: ```json plungeai_get_tool_contract {agent_id: "markitdown"} ``` ```bash curl -s https://api.plungeai.com/v1/tools/markitdown -H "Authorization: Bearer ozk_YOUR_KEY" ``` Read it in order: `operations` (pick by `purpose`; note `gated: true`), `inputSchema` (exact param shapes), `examples` (worked CNL), then — MCP contract only — the **Credentials** section (see below). ## Execute — MCP ```json plungeai_execute_tool { agent_id: "markitdown", operation: "convert", params: { file_data: "", file_name: "report.pdf" } } ``` Answers a structured outcome envelope over HTTP 200, always — `ok` \| `needs_input` \| `needs_connection` \| `needs_api_key` \| `needs_approval` \| `unavailable` \| `error`. Full parameter table and the outcome table — [`references/mcp-execute-tool.md`](/skills/plungeai-tools-connectors/references/mcp-execute-tool). ## Execute — REST ```bash curl -s -X POST https://api.plungeai.com/v1/tools/brave-agent/execute \ -H "Authorization: Bearer ozk_YOUR_KEY" -H "Content-Type: application/json" \ -d '{"operation": "search", "params": {"query": "cloudflare workers pricing"}}' ``` Same fences, REST spelling: `403 refused` (fence — never retry), `404 unknown_tool`, `424 connection_required` (carries `connect`), `409 approval_required` (a dispatched run's own outcome paused for approval — approve out-of-band in Studio, then re-issue the identical request; REST has no continuation token like MCP's `plungeai_continue`), `422 invalid_params` (body carries `missing` + the full contract — self-correct and retry once). Full error catalogue, the 403 fence-vs-lifecycle distinction, streaming/format — [`references/rest-tools-plane.md`](/skills/plungeai-tools-connectors/references/rest-tools-plane) and [`references/contract-and-execution.md`](/skills/plungeai-tools-connectors/references/contract-and-execution). ## Connected accounts (credential status) Every card carries a `credential` tier (REST: `GET /v1/tools`, `GET /v1/tools/{id}`, `GET /v1/discovery/search`): `{"tier": "platform"}` runs on our keys, `{"tier": "connection", "provider", "method": "oauth" | "api_key" | "wallet"}` acts as the caller (or the caller's customer) and needs that provider connected first. Over MCP the contract's Credentials section is LIVE per acting user: - `🔐 platform-managed` — nothing to connect. - `✅ connected as ` — call away. - `⚠️ NOT connected` / `expired — reconnect` — execution answers `needs_connection`/`needs_api_key` (MCP) or `424 connection_required` / `credential_required` (REST) until the account is connected. Relay exactly what to connect; retry the identical call after. ## Over the One API — tools, connections, channels One `ozk_` key (`Authorization: Bearer`; setup: `plungeai-api-setup`). | Job | REST | MCP | CLI `ocean-cli …` | |---|---|---|---| | list tools | `GET /v1/tools?limit=&offset=` (≤ 100) → `{tools: [card + credential], count}` | `plungeai_list_agents` | `tools list` | | contract | `GET /v1/tools/{id}` → `{agent_id, operations, inputSchema, examples, credential, …}`; `404 unknown_tool` | `plungeai_get_tool_contract` | `tools get ID` | | execute | `POST /v1/tools/{id}/execute {operation?, params?, prompt?, format?}` → `200 {ok, content, outcome, execution_id, request_id}` | `plungeai_execute_tool` | `tools call ID [OP] --params JSON` | | connect | `POST /v1/connections/{provider} {api_key, api_secret?, on_behalf_of?}` → `201 {provider, on_behalf_of, status: "connected"}`; `POST /v1/connections/{provider}/link {on_behalf_of?, return_url?}` → `201 {url, expires_at}` | — | `connections add-key` (Studio session) | | status | `GET /v1/connections?on_behalf_of=` → `{connections: [{provider, on_behalf_of, method, status, connected_at}]}` (never a secret) | the contract's Credentials section | `connections list` (Studio session) | | disconnect | `DELETE /v1/connections/{provider}?on_behalf_of=` → `204`; `404 connection_not_found` | — | `connections remove` (Studio session) | | paired chats | `POST /v1/channels/pair {channel}` → a 10-minute code; `GET /v1/channels` → your paired chats | — | — | What builders get wrong: - **A `424` tells you where to connect.** `error.connect` is `{provider, method, link}`, and `link` is a route (`POST /v1/connections//link`), not a URL: call it to mint the one-use, 15-minute hosted page. `oauth` providers connect through that page; `POST /v1/connections/{provider}` takes a key and is checked live (`400 credential_rejected`; `404 unknown_provider`). - **`on_behalf_of` is for your customers and lives on `POST /v1/execute` only.** The per-id routes (`/v1/tools/{id}/execute`, `/v1/agents/{id}/execute`, `/v1/workflows/{id}/execute`) answer `400 invalid_body` rather than quietly run as you. Read such a run back with `GET /v1/executions/{id}/output?on_behalf_of=`. - **Operation fields can sit bare at the body root** (`POST /v1/tools/calculator-tool-agent/execute` with `{"expression": "7*6"}`); `params` still works and wins on a clash. - Connection routes and `/v1/channels` are tenant-scoped like everything else: another account's ids answer the same as missing ones. A paired chat is then bound to a bot with `POST /v1/workflows/{id}/bindings` (`plungeai-api-setup`, `references/bots-and-door.md`). ## Why the fences exist Gated operations are the ones with real-world blast radius: money movement, outbound messages, irreversible mutations. **An unattended caller never fires them** — a human must be in the loop. `403`/`409`/`needs_approval` are correct behavior, not errors to engineer around: surface them, get the human decision, continue through the approval mechanism (`plungeai_continue` on MCP). A retried tool call re-fires the FULL operation — check execution history before re-firing anything non-idempotent. ## Gotchas - **Reserved param names** (`agent`, `type`, `id`, `operation`, `depth`, `user_id`, `executor_user_id`, `workflow`, `execution_id`) collide with the task envelope and are never forwardable — `needs_input`/`422` names them. - **A lone `prompt` on a multi-operation card runs the DEFAULT operation** and warns about it — if that's not what the user meant, re-call with an explicit `operation` + typed `params`. - **`gated: true` is refused regardless of operation wording** — rephrasing the prompt or switching styles to sneak past a fence never works. - **`409 approval_required` IS real on REST** — it fires when a dispatched run's own outcome comes back `needs_approval`, not from the pre-dispatch gated-verb/guarded-category fence (that fence runs in unattended mode on this route and always resolves to `403 refused` instead). Approve out-of-band, then re-issue the identical request. ## Related skills - `plungeai-discovery` — search, full cards, the contract fetch itself. - `plungeai-agents` — prompt-driven execution, `plungeai_get_result`. - `plungeai-models` — model/provider overrides, the money plane. - `plungeai-workflows` — put a tool's typed fields directly on a CNL task. - `plungeai-results-traces` — tracing an `execution_failed`/`upstream_error`. ## Reference pages A tool on PlungeAI is a structured agent: instead of free-text prompts it takes typed parameters against a published contract — named operations, a JSON… Structured tool-agents (cards with a Parameters table — posting, document conversion, weather, data-table CRUD, calendar operations, payment actions) take… Every active agent is also callable as a tool with a machine-checkable invocation contract.