Tool Execution Governance

Tool execution governance defines what happens after a tool is visible at runtime. A visible tool still follows tenant context, scope, input validation, risk level, review gate, and audit rules before a result or action is accepted.

Use this page when designing the call path for an Agent workflow, reviewing a blocked tool call, or deciding how confirmations and approvals should be recorded.

Execution flow

Execution outcomes

Outcome	What it means	User-facing handling
Allowed result	The tool can return read-only evidence or reviewed analysis.	Show sources, assumptions, and unresolved gaps.
Confirmation required	The tool prepares a draft or reversible follow-up that needs user confirmation.	Show the draft, evidence, and confirmation choice.
Awaiting approval	The tool affects an operating task, record, or connected system and needs a named reviewer.	Route the request to the reviewer and record pending state.
Blocked	Scope, input, data, tenant boundary, review policy, or guardrail checks stopped the call.	Return the reason, preserve evidence, and avoid partial action.
Recorded no-op	The workflow decides no action is needed after review.	Record the decision and the evidence used.

Each outcome should be visible in the run record. A blocked or pending outcome is still useful because it explains what must be fixed before the workflow can continue.

Tool types

Tool type	Typical examples	Governance expectation
Read-only lookup	Asset context, document retrieval, status summary, source record lookup.	Return evidence with timestamps and source references.
Analysis or compute	Health score, anomaly explanation, simulation comparison, optimization result.	Record assumptions, input boundaries, result summary, and reviewer notes.
Draft generator	Work request draft, inspection note, scenario package, validation note.	Keep the draft separate from an accepted record until confirmation or review.
Action-capable tool	Work-order dispatch, task assignment, controlled update, external-system handoff.	Require the planned confirmation, approval, policy, and audit path.

Use Risk Governance and Safety to align tool type with risk level and review gate.

Assistant response model

An assistant response should expose the execution state rather than hiding it behind a natural-language answer. For operational modules such as CMMS, facility operations, predictive maintenance, and data center operations, the response should include the fields users and reviewers need to continue safely.

Response field	Purpose
Intent	The task the assistant understood.
Tool name	The tool or capability used to produce the result.
Gate verdict	Allowed, confirmation required, awaiting approval, blocked, or no action.
Audit ID	Run or action identifier for later review.
Evidence	Source records, timestamps, and documents used by the answer.
Clarifying prompt	Question to ask when required input is missing.
Blocked reason	Scope, data, tenant, input, or review requirement that stopped execution.
Result card	Draft, created record, assignment result, closeout result, or summary returned to the user.

When a user confirms an action, the assistant should reuse the same action attempt and idempotency key. A changed request should start a new action attempt so the run record can show what changed between the draft and the accepted action.

Before calling a tool

Confirm these items before the workflow calls a tool:

1. The tool appears in runtime discovery for the current client.
2. The endpoint and scopes match the workflow boundary.
3. The user or agent has the intended tenant, site, asset, scene, or record context.
4. Required input fields and controlled options are present.
5. Source data, documents, scenes, or operating records are fresh enough for the task.
6. The workflow states whether the result is evidence, analysis, draft, or action.
7. The review owner and audit location are known.

Use Runtime Tool Discovery before finalizing prompts or automation.

Confirmation and approval

Confirmation and approval should be designed before action-capable tools are used.

Path	Use when	Record
User confirmation	A draft or reversible follow-up is ready for the user to accept.	User, draft content, confirmation time, and scope used.
Reviewer approval	The result affects a work order, inspection task, operating record, or connected system.	Reviewer, decision, reason, final record, and timestamp.
Policy-controlled review	The action is governed by customer operating policy or change-control rules.	Policy owner, rule applied, approval evidence, and audit record.
Blocked path	Required data, scope, input, tenant boundary, or approval is missing.	Blocked reason, missing requirement, and next owner.

Use Workflow Run Record to keep the outcome traceable.

Idempotency and repeated requests

For action-capable workflows, repeated requests should preserve the same operating decision whenever the request represents the same action attempt.

Customer-facing expectations:

• repeated submit or retry should preserve a single work order or task for the same action attempt;
• users should see whether the previous result was accepted, pending, blocked, or rejected;
• retries should preserve the original evidence and approval context where possible;
• changed inputs should create a new reviewable action attempt;
• the final run record should explain whether a retry reused a prior decision or produced a new one.

Audit requirements

Every accepted, pending, or blocked tool outcome should leave enough evidence for later review.

Audit field	Why it matters
Client and tenant context	Shows which environment and access path produced the result.
Visible tool set	Shows what the client could use at the time.
Tool name and purpose	Explains which capability produced the output.
Input summary	Captures boundary, parameters, source records, and assumptions.
Outcome	Records allowed, confirmed, pending approval, blocked, rejected, or no action.
Reviewer decision	Captures who accepted, revised, approved, or rejected the output.
Final record link	Connects the Agent run to work order, inspection, scenario, validation, or feedback records.

Troubleshooting execution

Symptom	Likely cause	Response
Tool was visible but call failed	Scope, input, tenant context, or review gate blocked execution.	Check access package, input requirements, and risk gate.
Draft awaits acceptance	Confirmation or reviewer approval is still pending.	Record pending state and route to the owner.
Action remains paused	Policy, approval, guardrail, or missing data stopped the action path.	Return blocked reason and preserve evidence.
Duplicate result appears likely	A retry may represent the same action attempt.	Check prior run record before creating a new operating record.
Tool output lacks sources	Source data or evidence requirements are incomplete.	Run data readiness review before accepting the answer.

Use MCP Errors and Audit for endpoint, scope, and failure triage.

Related pages

Need	Use
Confirm visible tools	Runtime Tool Discovery
Plan endpoint and scope	Access and Scope Planning
Define review gates	Risk Governance and Safety
Capture evidence	Workflow Run Record
Diagnose tool failures	MCP Errors and Audit