# Investigations, drafts & escalation

> Run Clad's AI-agent workflow over MCP: investigate tickets, review grounded reply drafts, approve or deny them, and escalate to the tracker.

Product: Clad MCP
Source: https://docs.useclad.ai/mcp/agents

---

Beyond the inbox tools, the server exposes Clad's AI-agent workflow itself, so
an external agent can run the same playbook a human runs in the Clad panel.

**Check the connection first.** `get_helpdesk_connection` reports the provider
(Pylon/Zendesk), status, and operating mode. In **Observe** mode Clad never
writes to the helpdesk — drafts can still be generated and reviewed, but
`approve_draft` (and `reply_to_issue`) will return `FORBIDDEN` until an admin
switches the connection to **Assist**.

**Investigations.** `start_investigation` kicks off an asynchronous dig into
the root cause of a ticket: `kind: "code"` works through the connected GitHub
repo, `kind: "billing"` works through Stripe for the customer's billing state.
Runs take a few minutes — poll `get_investigation` until `status` is
`complete` (or `failed`), then read `output` (markdown findings), `summary`,
and `answerFound`. Per-workspace in-flight and daily caps protect spend; when
you hit one the tool returns `RATE_LIMITED`.

**Drafts.** Clad auto-drafts a suggested reply when a customer message comes
in and the knowledge base has a confident answer. `get_latest_draft` reads the
newest attempt for an issue — its `status` tells you whether it's `generating`,
`pending` (awaiting review), `discarded_*` (the gate declined), `approved`, or
`rejected` — and its `sources` list the knowledge-base articles and resolved
tickets the answer was grounded in, so you can verify it before acting.
`generate_draft` produces one on demand through the same gated pipeline
(optionally steered with `instructions`); a declined gate returns
`withheld: true` with the reason, not an error.
`generate_draft_from_investigation` turns a completed investigation's findings
into a pending draft.

**Review.** `approve_draft` sends the draft to the customer;
`deny_draft` rejects it with a reason (which feeds regeneration and quality
analytics). Approving requires a **human-authorized credential** — an OAuth
grant from a signed-in teammate — because the send is attributed to the
approving person; headless API keys can generate and deny drafts but not
approve them. v1 delivers approvals on helpdesk-mirrored issues
(Pylon/Zendesk); other channels approve in the Clad app.

**Escalation.** When a ticket needs engineering, `file_tracker_ticket` files a
Linear ticket from the issue and links it — the Clad issue moves to On hold
and the tracker ticket gets a back-link comment with the customer context.
`get_linked_tickets` reads the linked tickets' live state and comment threads,
and `comment_on_linked_ticket` posts follow-up context for the engineers.
Check `get_linked_tickets` before filing to avoid duplicates.

A typical loop for a helpdesk ticket: `get_issue` → `get_latest_draft` (is
there already a reviewed answer?) → if not, `start_investigation` → poll →
`generate_draft_from_investigation` → review the body and sources →
`approve_draft` — and `file_tracker_ticket` when the root cause needs a code
fix. Everything is scope-gated (`investigations:read` / `investigations:run` /
`drafts:read` / `drafts:write`), so a key can be limited to exactly the steps
you want automated.