Skip to content

Tools & MCP — Workflows

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Descriptor activation

A tool is a Published asset (BC-04) with a descriptor; ToolAdapterService consumes AssetReleasePublished and activates the descriptor version; deprecation and revocation retire it with the release's in-flight policy. Agents reference tool ids and versions through their release closure; the model rule that an agent's tools may not exceed its policy's maximum class is enforced at publication, not at call time.

Invocation

Stage Who Outcome if it fails
Schema validation executor Denied (validation)
Agent permission policy engine (agent release closure) Denied
Tenant policy policy engine (tenant and project policy, environment class) Denied
Side-effect classification executor effective class; may raise to production (Frozen environments refuse writes)
Approval Run Control approval bound to the request hash and tool version AwaitingApproval → Denied on rejection or expiry
Credential broker Secret Broker, short-lived fail closed
Sandbox Execution Capacity lease with limits and egress allow-list queued within budget, then transient failure
Execute native, MCP, shell, HTTP, browser, computer-use Failed (before effect), Uncertain (unconfirmed), Observed
Sanitize executor secrets stripped, size bounded, provenance tagged
Audit and receipt executor → AuditService, ArtifactService the receipt is the evidence

Gated calls

sequenceDiagram
    participant A as Attempt
    participant X as ToolAdapterService
    participant RC as RunControlService
    participant R as Reviewer
    A->>X: Invoke propose-change-set (shared-write)
    X->>X: validate, permission, policy, class = shared-write
    X-->>A: AwaitingApproval (invocation id, request hash)
    A->>RC: RequestApproval bound to request hash and tool version
    R->>RC: approve
    RC-)A: ApprovalDecided
    A->>X: Invoke again with approvalId (same idempotency key)
    X->>RC: validate approval binding
    X->>X: broker credential and sandbox, execute, receipt
Hold "Alt" / "Option" to enable pan & zoom

A regenerated proposal has a new request hash and needs a new approval; the earlier one is stale.

Sandboxes

Leases come from Execution Capacity (BC-26) per invocation, or per attempt when a workspace is shared across calls (an isolated git worktree per run, original handoff §34). Limits: CPU, memory, GPU, timeout, process restrictions, read-only mounts, egress allow-list (github.com, dev.azure.com, api.nuget.org by default), temporary credentials. The reaper releases leases of terminal invocations and expired leases.

Uncertain effects

When the sandbox, the host or the connection is lost after a call may have had an effect, the invocation ends Uncertain, ToolEffectUncertain reaches the runtime and the Studio, and an Operator confirms or denies the effect from the receipt and external evidence before any retry is allowed (XL-06).

MCP servers

Registered → Verified → Active → Degraded → Retired: handshake and discovery produce tool, resource and prompt bindings; an Asset maintainer binds tools to descriptors with a declared class and a Platform admin or maintainer activates the server (publication-class action). A changed schema unbinds until re-approved; the handshake probe degrades unhealthy servers and the executor marks their descriptors unhealthy.