Tools — structured tool-agents and their contracts

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 Schema for inputs, worked examples, and per-operation approval gates. Think of document converters, weather lookups, data-table CRUD, calendar operations, payment actions.

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 — current, generated from the live card, and (over MCP) personalized with the acting user's credential status.

The contract

GET /v1/tools/{id} (One API) or plungeai_get_tool_contract {agent_id} (MCP):

{
  "agent_id": "markitdown",
  "name": "markitdown",
  "description": "Convert a document, image, audio file, or URL to markdown…",
  "operations": [
    {
      "name": "convert",
      "purpose": "Convert a file or URL to markdown",
      "gated": false,
      "required_params": ["file_data", "file_name"]
    }
  ],
  "inputSchema": { "type": "object", "properties": { "…": {} } },
  "examples": [ { "title": "Convert a PDF to markdown", "cnl": "…worked YAML…" } ],
  "output_type": "markdown"
}

Read it in this order:

1. operations — pick the operation whose purpose matches the job. Note gated: true: that operation needs human approval (see fences below).
2. inputSchema — the exact parameter shapes. required_params per operation is the short list; the schema is the authority on types and enums.
3. examples — worked CNL YAML; each example also shows how the tool is used as a workflow task (the same fields go on a task next to agent: — see the plungeai-workflows skill).
4. Credential status (MCP contract only) — LIVE per-user: "platform-managed" means it just works; "connect Google first" means the call will return needs_connection until the user connects that credential in Studio.

Discovery

# List active tool-agents
curl -s "https://api.plungeai.com/v1/tools?limit=50" \
  -H "Authorization: Bearer ozk_YOUR_KEY"
# → {tools: [Card…], count}

Or find by capability with the hybrid search (GET /v1/discovery/search?q=…) / plungeai_list_agents {search} — tools are agents; they appear in the same registry with a Parameters table on their card.

Execution

MCP: plungeai_execute_tool

plungeai_execute_tool {
  agent_id: "markitdown",
  operation: "convert",
  params: { file_data: "<base64 of the file>", file_name: "report.pdf" }
}

Runs through the engine with full observability (an execution id you can trace). Long jobs: mode: "async" → poll plungeai_get_workflow_status → fetch with plungeai_get_result.

Every call answers with a structured outcome envelope over HTTP 200 — a blocked call is guidance, never a protocol error. The complete MCP status vocabulary:

There is no refused MCP status: MCP has an approval surface, so gated operations pause as needs_approval instead of being refused. refused is the One API's REST spelling of the fence (403 below).

One API: POST /v1/tools/{id}/execute

curl -s -X POST https://api.plungeai.com/v1/tools/markitdown/execute \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
    "operation": "convert",
    "params": { "file_data": "<base64 of the file>", "file_name": "report.pdf" }
  }'
# 200 → {"ok": true, "content": "…", "outcome": "ok", "request_id": "…"}

prompt is accepted instead of operation/params for prompt-driven agents reached through this route — but if the card has a Parameters table, use typed params.

HTTP status mapping (same fences, REST spelling):

Why the fences exist

Gated operations are the ones with real-world blast radius: money movement, outbound messages, irreversible mutations. The platform's trust model is that an unattended caller never fires them — a human must be in the loop. 403/409 are therefore correct behavior, not errors to engineer around. Surface them, get the human decision, continue through the approval mechanism. Also remember: a retried tool call re-fires the FULL operation — if the side effect completed before the failure was reported, a retry duplicates it. When in doubt, check execution history (plungeai_executions) before re-firing anything non-idempotent.

Tools inside workflows

A structured tool-agent is used in CNL by putting its typed fields directly on the task, next to agent::

- type: task
  id: convert
  agent: markitdown
  operation: convert
  file_data: "{input}"
  file_name: report.pdf

The contract's examples[].cnl show the canonical per-tool shapes. Everything else about composition is in the plungeai-workflows skill.

Checklist

1. Contract fetched (first use) — operation picked by purpose, gates noted.
2. Params match inputSchema exactly — no extra prose fields.
3. Credential status green (MCP) or the user warned.
4. Gated op → plan for the approval pause; unattended REST cannot serve it.
5. Outcome remediation followed; no blind retries; no duplicate side effects.