plungeai-tools-connectors
Executing tools over MCP — execute_tool
Structured tool-agents (cards with a Parameters table — posting, document conversion, weather, data-table CRUD, calendar operations, payment actions) take typed fields against a published contract, not prose.
Structured tool-agents (cards with a Parameters table — posting, document
conversion, weather, data-table CRUD, calendar operations, payment actions)
take typed fields against a published contract, not prose. Always fetch the
contract first (plungeai_get_tool_contract, see plungeai-discovery) — the
contract IS the API documentation, generated live from the card and
personalized with the acting user's credential status.
plungeai_execute_tool
Purpose: run one structured tool-agent directly with typed params, through the same engine pipeline as every other execution (history, results, HITL all included).
Parameters
| Param | Type | Notes |
|---|---|---|
agent_id | string, required | From a live search (plungeai_list_agents). |
operation | string ≤128 | One of the contract's operations. Also auto-filled into the card's selector param (action/op/operationType) when the card reads its operation from a param — so passing operation alone is safe. |
params | object | Typed fields per the contract's JSON Schema. |
prompt | string | Prose fallback. On a card whose requireds resolve to exactly ONE free-text param, a lone prompt is mapped into it (visibly, with a warning). Never mapped into selectors, enums, or URL params. |
mode | sync | async | Async returns an execution id to poll. |
format | markdown | json | Response serialization; default markdown. |
Example
{"user_request": "what's the weather in Lisbon this weekend?",
"agent_id": "weather-agent", "operation": "forecast",
"params": {"location": "Lisbon", "days": 3}}Returns: the outcome envelope, always (never a raw error):
| Status | Meaning → your move |
|---|---|
ok | Result markdown + execution-id footer (+ any ⚠️ warnings, e.g. "prose mapped"). Relay verbatim. |
needs_input | Missing/invalid fields; missing[] + the full contract ride along so you can fix the SAME call without a second lookup. Nothing was executed. |
needs_connection / needs_api_key | The USER must connect a service or save a key in a PlungeAI app. Relay the instructions, wait for them, retry the identical call. Caught pre-flight when possible — before a run exists. |
needs_approval | ⏸ gated operation paused mid-run. Relay verbatim; plungeai_continue after the user decides. |
unavailable | Agent refused (unknown/inactive) or temporarily down — real alternatives included. Nothing was executed. |
error | Terminal failure with a reason; follow the remediation (often retry_with {mode: "async"} for timeouts). |
Failures & fixes
- Reserved param names (colliding with the task envelope) →
needs_inputnaming them; rename/drop those keys. The reserved names:agent,type,id,operation,depth,user_id,executor_user_id,workflow,execution_id. - Prose prompt + no
operationon a multi-operation card → the run executes the card's DEFAULT operation and says so in a warning. If that is not what the user meant, re-call with an explicitoperation+ typed params. - Gated operations are not refused up front — they pause (
needs_approval). That pause is a trust fence: surface it, never bypass it.
Connected accounts (credential status)
The contract's Credentials section (fetched via plungeai_get_tool_contract,
see plungeai-discovery) is LIVE per acting user:
🔐 platform-managed— nothing to connect; just call.✅ connected as <email>— the user's OAuth/API-key connection is live; call away.⚠️ NOT connected/expired — reconnect—plungeai_execute_toolwill answerneeds_connection/needs_api_keyuntil the user connects that credential in a PlungeAI app (Studio → Connectors). Relay exactly what to connect; do not retry until they have.
The credential-status RPC runs speculatively in parallel with the card fetch
on plungeai_get_tool_contract, so the contract call itself carries this
status — no separate lookup needed before your first execute_tool attempt.
Putting it together — the canonical multi-step run
1. plungeai_list_agents {search: "convert pdf to markdown"} → markitdown
2. plungeai_get_tool_contract {agent_id: "markitdown"} → schema; credentials 🔐 platform-managed
3. plungeai_execute_tool {agent_id: "markitdown",
operation: "convert",
params: {file_data: "<base64 of the file>", file_name: "report.pdf",
format: "markdown"},
mode: "async"} → execution_id E
4. plungeai_get_workflow_status {execution_id: E} → running → completed
5. plungeai_get_result {execution_id: E} → relay verbatim (see plungeai-agents)Note how step 3 follows step 2's contract: convert requires file_data
(base64-encoded content) and file_name for uploaded files (a url param
is also accepted for web pages/YouTube/Wikipedia, but a file already in hand
goes through file_data). Skip step 2 only for agents whose contract you
fetched earlier in the same conversation. Skip steps 4–5 in sync mode — the
result comes back in the execute call itself.