AI Agent Tooling And HITL
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.
Use When
- Design tool catalogs, tool contracts, action scopes, and approval gates for agents.
- Decide when an agent action requires human review, confirmation, or escalation.
- Integrate agent tools with audit logs, reversibility, tenant policy, and runtime budgets.
Do Not Use When
- The work is not AI-specific or agentic-AI-specific.
- A narrower retained AI parent skill fits the request better.
Required Inputs
- Product, tenant, user, data, risk, and operational context relevant to the AI workflow.
- Target artifact: design, implementation plan, audit, test strategy, UX flow, commercial policy, or runbook.
- Constraints from security, privacy, reliability, billing, support, and compliance stakeholders when relevant.
Workflow
- Read this SKILL.md first.
- Load references/routing.md to select the absorbed child reference that matches the task.
- Load only the selected child reference files needed for the current request.
- Produce execution-oriented output with assumptions, risks, evidence, and next actions where relevant.
Quality Standards
- Keep routing explicit: name which reference files were used when the work depends on absorbed material.
- Preserve tenant isolation, auditability, cost controls, safety gates, and operational evidence when they matter.
- Prefer concrete contracts, checklists, tables, schemas, runbooks, and decision records over broad summaries.
Anti-Patterns
- Loading every absorbed reference by default.
- Treating AI-specific billing, compliance, safety, or UX concerns as generic SaaS work without checking AI failure modes.
- Hiding retired skill names; old slugs must remain discoverable through references/routing.md.
Outputs
- A concrete deliverable matched to the request: architecture, implementation plan, audit, policy, runbook, UX flow, test strategy, or operating model.
- The selected consolidated reference files and any assumptions, risks, evidence requirements, or follow-up actions that affect execution.
References
- references/routing.md maps retired child skill slugs to their consolidated reference folders.
- Load references/least-privilege-tool-and-mcp-security.md when making a tool or MCP server safe to call: typed actions, scoped credentials, strict schemas, MCP threats, tool-call audit fields and mandatory tests.
- Load references/mcp-tool-surface-evaluation.md when proving an MCP server is usable by a model: ten read-only, independent, multi-hop QA pairs on a pinned fixture, frozen answers, excluded mutating tools.
Consolidated Child References
- Load references/routing.md to map retired AI child skill slugs to their reference modules.
Evidence Produced
| Category | Artifact | Format | Example |
|---|---|---|---|
| Security | Tool action and approval matrix | Markdown/YAML | tool, arguments, tenant scope, reversibility, approver, timeout, and denied case |
Inputs
| Artefact | Required? | Purpose |
|---|---|---|
| Tool schemas and side-effect classification | yes | Define callable actions |
| Identity, tenant, approval, and budget policy | yes | Enforce authority |
| Reversal and audit requirements | yes | Bound consequences |
Capability contract
Default to read-only tool design. Tool invocation, approval simulation, and side-effect testing require isolated fixtures and explicit execution authority.
Degraded mode
Fallback without executable tools: validate schemas, permission scopes, approval policy, and reversal design statically; mark runtime enforcement unverified.
Decision rules
| Action class | Gate | Failure avoided |
|---|---|---|
| Read-only, low sensitivity | Policy-scoped automatic call | Approval fatigue |
| Reversible mutation | Confirm policy and log result | Silent unwanted change |
| Irreversible, financial, external, or privileged | Just-in-time human approval | Unauthorised impact |
Domain anti-patterns
- Giving one tool broad multi-action scope. Fix: expose narrow, typed actions.
- Trusting prompt text for authorisation. Fix: enforce identity and policy outside the model.
- Asking approval after execution. Fix: gate before side effects.
- Omitting idempotency and reversal. Fix: define both for every mutation.
- Logging arguments without protecting secrets. Fix: redact and classify audit fields.
