> For the complete documentation index, see [llms.txt](https://www.cakewalk.security/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.cakewalk.security/docs/ai-agent-access/concepts/the-tool-call-lifecycle.md). # The Tool Call Lifecycle When an Agent acts, every action is a tool call. Every tool call follows the same six-step lifecycle through the MCP Gateway. The decisions made along this path are what governance is. *** ### 📖 Key Concepts * **Tool call**: A single Agent action against a Connection (read, write, delete, send). Cakewalk evaluates each tool call independently. * **Action type**: Cakewalk's classification of what the tool call does: **Read**, **Write**, **Destructive** or **External**. Derived from MCP annotations or Catalog lookup. See [Policies](/docs/ai-agent-access/concepts/policies.md) for how action types feed the Policy engine. * **MCP elicitation**: The approval channel. When a tool call requires approval, the Agent client (Cursor, Claude Desktop) shows an inline prompt to the User who delegated. They approve or deny without leaving their workflow. * **Decision**: One of three outcomes for every tool call: **Approve**, **Require approval** or **Deny**. :bulb: *Why this matters:* The lifecycle is what makes governance fast in the common case and deliberate in the sensitive case. Auto-approved Reads pass through with millisecond overhead. Sensitive Writes pause for a User to confirm. Destructive actions stop unless a Policy explicitly allows them. *** ### 🔁 The Six Steps Every tool call runs the same sequence at the MCP Gateway. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#F9F9FB","primaryTextColor":"#1E1E1E","primaryBorderColor":"#6B7280","lineColor":"#6B7280","signalColor":"#1E1E1E","signalTextColor":"#1E1E1E","actorBkg":"#F9F9FB","actorBorder":"#6B7280","actorTextColor":"#1E1E1E","noteBkgColor":"#FFFFFF","noteBorderColor":"#E0E0E0","noteTextColor":"#1E1E1E","labelBoxBkgColor":"#F9F9FB","labelBoxBorderColor":"#E0E0E0","labelTextColor":"#1E1E1E","loopTextColor":"#1E1E1E"}}}%% sequenceDiagram participant A as Agent participant G as MCP Gateway participant P as Policy Engine participant U as User participant C as Connection A->>G: Tool call Note over G: 1 · Identify the Agent, the User and the Connection Note over G: 2 · Check the User's Connection is Active G->>P: 3 · Evaluate the Policy against the tool call P-->>G: Auto-approve · Require approval · Deny alt Deny G-->>A: The tool call is denied else Require approval G->>U: 4 · Approval prompt, inline in the Agent client (MCP elicitation) U-->>G: The User approves or denies alt Approved G->>C: 5 · Forward the call with the User's credential C-->>G: Response G-->>A: Response else Denied or no response G-->>A: The tool call is denied end else Auto-approve G->>C: 5 · Forward the call with the User's credential C-->>G: Response G-->>A: Response · the Agent never sees the credential end Note over G,C: 6 · Every outcome is recorded as an audit event ``` #### Step 1: Identify The MCP Gateway extracts the three actors from the inbound tool call: * The Agent (which AI client made the call) * The User (which person delegated this Agent) * The Connection (which downstream app the tool call targets) If no session exists, the MCP Gateway creates one. The session is what links every tool call back to the three actors in the audit trail. #### Step 2: Check the Connection The MCP Gateway checks the User's Connection to the target app. If the Connection is missing or not Active (the User has not connected it yet, or it moved to Error or Paused), the call cannot proceed. The Agent receives a structured signal to surface a connect or reconnect prompt. The real credential is not touched here; it is retrieved and decrypted only at proxy time (Step 5). #### Step 3: Evaluate Policy The MCP Gateway runs the tool call through the Policy engine. Inputs: * **Action type**: Read, Write, Destructive or External * **User attributes**: department, title, location, user category * **Connection attributes**: name, category, risk level Output: one of three decisions. * **Auto-approve** → continue to Step 5. * **Require approval** → continue to Step 4. * **Deny** → return a structured denial. Log and stop. Conflict resolution between overlapping Policies is deterministic: see [Policies](/docs/ai-agent-access/concepts/policies.md). #### Step 4: Pause for Approval (MCP elicitation) When the decision is Require approval, the MCP Gateway suspends the tool call and surfaces an MCP elicitation prompt inside the Agent client. The User who delegated sees the prompt inline (in Cursor, Claude Desktop or whichever Agent they are using) and approves or denies. * **Approved** → continue to Step 5. * **Denied** → return a structured denial. * **Timeout** → the tool call fails closed (denied) after a fixed wait. If the Agent client does not support MCP elicitation, the outcome falls back to a company setting that defaults to Deny. There is no separate notification channel for approvals today. #### Step 5: Proxy the Call The MCP Gateway retrieves the real credential from the vault, injects it into the outbound HTTP request and proxies the call to the Connection. The Connection sees a request as if the User made it directly. The Agent receives the response, never the credential. #### Step 6: Record the Decision Every evaluation produces an [audit event](/docs/ai-agent-access/concepts/audit-log.md): the request payload, the response payload and every triggered Policy with its outcome. Audit events are queryable, exportable and immutable. Admins inspect them through the Sessions tabs and Agent Activity. *** ### ⏩ The Common Path Most tool calls auto-approve. A typical Read of a non-sensitive Connection runs Steps 1, 2, 3, 5 and 6 with millisecond overhead. The Agent feels a normal MCP round-trip. The MCP Gateway is invisible at the protocol level. *** ### Related Concepts * [The MCP Gateway](/docs/ai-agent-access/concepts/the-mcp-gateway.md): the proxy that runs this lifecycle * [Policies](/docs/ai-agent-access/concepts/policies.md): how Step 3 produces a decision * [Audit Log](/docs/ai-agent-access/concepts/audit-log.md): what Step 6 records * [Trust and Security](/docs/ai-agent-access/concepts/trust-and-security.md): how credential mediation works at Step 5 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://www.cakewalk.security/docs/ai-agent-access/concepts/the-tool-call-lifecycle.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.