| name | tool-governance |
| description | Govern Wiii tools, sandbox execution, capability registration, and artifact streaming. Use when adding, changing, reviewing, or debugging tools; deciding between deterministic file-generation tools, OpenSandbox code execution, browser automation, or MCP-style integrations; updating role gates and capability registry; or wiring generated files into previews/artifacts. |
Tool Governance
Use the smallest execution surface that can solve the task.
- Use native deterministic tools for exportable deliverables such as
.html, .xlsx, .docx, structured reports, or data transforms that do not need untrusted code execution.
- Use OpenSandbox Python for dynamic computation, plotting, dataframe work, or code that must run in an isolated runtime.
- Use browser sandbox only for navigation, screenshots, DOM extraction, or agent-visible web interaction.
- Avoid turning every endpoint into a separate tool. Prefer a small number of broad capabilities with clear arguments.
Keep tool changes aligned across the stack.
- Register the tool in the runtime registry and set category/access rules.
- Add or update capability metadata in capability_registry.py.
- Bind the tool only in the agent paths that should actually use it.
- Emit user-visible outputs as
preview or artifact bus events instead of burying them in plain text.
- Add focused tests for registration, permissioning, and runtime behavior.
Treat artifacts as first-class outputs.
- Stream raw HTML only when the user needs a renderable page or landing page preview.
- Stream chart/image artifacts as base64-backed
chart artifacts.
- Stream JSON/CSV tables as
table artifacts when possible.
- Stream binary office files (
.xlsx, .docx, .pdf) as document-style artifacts with stable metadata (file_path, file_url, content_type) even when inline preview is not possible.
Preserve operational safety.
- Keep privileged execution behind explicit role gates.
- Propagate
request_id, session_id, organization_id, user_id, and tool_call_id into sandbox metadata and artifact events.
- Do not rely on raw chain-of-thought to explain tool work. Use concise action text plus inspectable artifacts.
- Prefer capability-level descriptions over implementation details in prompts and selectors.
When reviewing a tool design, challenge four things before shipping.
- Can this be a deterministic tool instead of sandbox code?
- Is the tool broad enough to avoid tool explosion?
- Does the output appear as a first-class artifact or preview?
- Are role gates, telemetry, and tests in place?
