A Tool-Using Agent Is a Bounded State Machine

1. 01PlanningThe planner receives bounded context and proposes a typed action or completion.
2. 02ValidatingSchema, policy, budget, preconditions, and duplication are checked.
3. 03Awaiting approvalA sensitive action pauses with exact proposed inputs visible.
4. 04ExecutingThe tool runs with timeout, scoped credentials, and an idempotency key.
5. 05ObservingA typed result or actionable error is appended to state.
6. 06TerminalSucceeded, failed, cancelled, or exhausted is persisted and cannot silently resume.

1type Status = "planning" | "executing" | "succeeded" | "failed" | "exhausted"
2 
3type Proposal =
4  | { kind: "tool"; name: string; args: Record<string, unknown> }
5  | { kind: "finish"; answer: string }
6 
7type State = { status: Status; steps: number; maxSteps: number; seen: Set<string> }
8 
9export function validate(state: State, proposal: Proposal, allowed: Set<string>) {
10  if (state.steps >= state.maxSteps) return { ok: false, reason: "step_budget" } as const
11  if (proposal.kind === "finish") return { ok: true } as const
12  if (!allowed.has(proposal.name)) return { ok: false, reason: "tool_denied" } as const
13  const fingerprint = proposal.name + ":" + JSON.stringify(proposal.args)
14  if (state.seen.has(fingerprint)) return { ok: false, reason: "repeated_action" } as const
15  return { ok: true, fingerprint } as const
16}
17 
18const state = { status: "planning", steps: 0, maxSteps: 2, seen: new Set<string>() } satisfies State
19const denied = validate(state, { kind: "tool", name: "delete", args: {} }, new Set(["search"]))
20if (!denied.ok) console.log(denied.reason)
21const exhausted = validate({ ...state, steps: 2 }, { kind: "tool", name: "search", args: {} }, new Set(["search"]))
22if (!exhausted.ok) console.log(exhausted.reason)

tool_denied
step_budget

A real fingerprint must canonicalize arguments and include tenant, principal, tool version, and resource scope. The example keeps the mechanism visible; the production contract must prevent two users from sharing an idempotency namespace.

A step limit alone is insufficient: one tool call can run for an hour, spend money, mutate hundreds of records, or return enough data to overflow context. Each budget needs a counter, a guard before commitment, and a terminal reason visible to users and operators.

1. 01Repeated actionThe planner proposes the same mutation after an ambiguous timeout.
2. 02Partial successThe external API commits but the response is lost.
3. 03Indirect prompt injectionA retrieved document asks the agent to export secrets.
4. 04Tool schema driftA once-optional argument becomes required.
5. 05Human pauseApproval arrives after relevant external state has changed.
6. 06CancellationThe user stops the run while a tool is in flight.

MCP standardizes how hosts, clients, and servers discover resources, prompts, and tools using JSON-RPC and negotiated capabilities. Tool definitions include schemas and metadata, but the current specification explicitly treats tool annotations as untrusted unless they come from a trusted server. The host still owns consent, policy, access control, timeouts, result validation, and audit.