Tools

The Tools screen lets you list the tools of the registry, change their description, owner and lifecycle status, delete them, invoke a tool through the Tool Gateway (scopes, policy, DLP, approval and cost) and read the recent invocations. Portal path: /capabilities/tools. Developers register and test tools; tenant administrators and security officers decide their status. The screen is drawn by portal/src/screens/capabilities.tsx.

What the screen shows

The page has four blocks, from top to bottom:

Tools table, read with GET /v1/tools (every tool in one call). Columns: Name, Version, Owner, Risk, Status, Updated. A click on a row, or View details, opens a side panel with GET /v1/tools/{name}. Empty: No tool registered, hint Apply a Tool manifest below to register a tool.
Invoke a tool tester: Name (required), Arguments (JSON, required), Data classification (public, internal, confidential, restricted), Purpose, Run id, the button Run and a Result area (Run the request to see the result here. before the first call).
Recent invocations table, read with GET /v1/tools/invocations (50 rows per call, cursor paging). Columns: Tool, Tool version, Actor, Status, Decision id, Duration (ms), Created. Filters Tool, Status (succeeded, failed, denied, pending_approval, rate_limited, blocked) and Run id. View details shows the row. Empty: No invocation yet.
Apply a manifest panel prefilled with a Tool manifest sample (portal/src/samples/tool-manifest.json), with Reset example and Apply.

Actions

Button or action	What it does	API call	Roles
Refresh (icon, each table)	Reloads the table.	`GET /v1/tools` / `GET /v1/tools/invocations`	Any tenant member
Row click or View details (tools)	Opens the tool record.	`GET /v1/tools/{name}`	Relation `viewer` on the tool
Row menu Edit	Form Description, Owner, Status (draft, approved, restricted, deprecated, blocked). A move to `approved` opens a promotion approval; the other statuses apply at once.	`PATCH /v1/tools/{name}`	Status: `tenant_admin`, `security_officer`; other fields: `tenant_admin`, `developer`, `application_owner`; relation `editor`
Row menu Delete	Opens Confirm a destructive action; type the tool name, then Confirm.	`GET /v1/lineage/graph`, then `DELETE /v1/tools/{name}`	`tenant_admin` and relation `owner`
Run (Invoke a tool)	Calls the tool through the Tool Gateway and shows the answer in Result.	`POST /v1/tools/{name}/invoke`	`tenant_admin`, `developer`, `agent` and relation `can_invoke`
Filter (invocations)	Applies the Tool, Status and Run id filters.	`GET /v1/tools/invocations`	Any tenant member
Row menu View details (invocations)	Shows the invocation row.	None	Any tenant member
Reset example / Apply	Restores the sample / applies the Tool manifest.	`POST /v1/manifests/apply`	`tenant_admin`, `developer`
Retry (error state)	Sends the failed read again.	Same call	Same roles

The tester sends this body; empty optional fields are left out:

{"arguments": {"po_number": "PO-2026-0042"}, "data_classification": "internal", "purpose": "invoice check", "run_id": "<run-id>"}

<run-id>: optional id of the run the call belongs to.

The Tool Gateway checks in order the status of the tool, the scopes, the arguments against the tool schema, the data classification, the policy, the DLP and the approval. When an approval is needed, the answer is 202 with status: pending_approval and an approval_id; the request shows in the Approvals inbox. The tester has no approval_id field: once approved, the call is sent again with approval_id from the SDK or the API.

Roles

The portal hides no button. In services/control-plane/src/eai/domains/tools/routes.py: the list and the invocations need a tenant; a status change needs tenant_admin or security_officer, the other changes WRITE_ROLES (tenant_admin, developer, application_owner); delete needs tenant_admin; invoke needs OPS_ROLES (tenant_admin, developer, agent). Each route also checks the relation on the tool (viewer, editor, owner, can_invoke). platform_admin passes every role check.

Typical tasks

Register a tool and test it

Apply the manifest. A tool exists only once its manifest is applied. In Apply a manifest, paste your Tool manifest, then click Apply. Expected result: Manifest applied; after Refresh the tool is in the table with its version and status. If it fails: fix the errors listed under the editor.
Invoke it. The tester goes through the same gateway as agents. In Invoke a tool, type the Name, the Arguments in JSON, choose a Data classification, then click Run. Expected result: the answer of the tool in Result, and a new row in Recent invocations. If it fails: read the error code in Result (tool_blocked, invalid_arguments, policy_denied, dlp_blocked).
Check the invocation. Each call is logged with its policy decision. Filter Recent invocations on the tool. Expected result: the row shows Status, Decision id and Duration (ms). If it fails: click Refresh of the table.

Approve a tool for production use

Ask for the promotion. Moving to approved needs a second person. In the row menu, click Edit, choose Approved in Status, then click Edit. Expected result: the toast Done; the status stays the same and a promotion request appears in the Approvals inbox. If it fails: forbidden means you are neither tenant_admin nor security_officer.
Have it approved. Separation of duties applies. Ask another approver to approve the request. Expected result: the tool shows Approved. If it fails: the promotion may be refused by the risk check or a blocking evaluation suite.

Block a dangerous tool at once

Set the status. Retirements apply without approval. In the row menu, click Edit, choose Blocked, then click Edit. Expected result: the status Blocked; every new invocation answers tool_blocked. If it fails: check your role (tenant_admin or security_officer).

Troubleshooting

Symptom	Cause	Fix
`tool_not_found` (404): "Tool ... not found."	The name is wrong or the tool was deleted.	Copy the name from the Tools table.
`tool_blocked` (403)	The tool status is `blocked`.	Ask a security officer to change the status.
`invalid_arguments` (422)	The arguments do not match the input schema of the tool.	Read `errors` in the answer and fix the paths it names.
`classification_exceeded` (403)	The data classification exceeds what the agent may handle.	Use a lower classification or an agent allowed for it.
`insufficient_scope` (403)	The credential lacks a scope the tool requires.	Use a credential that carries `required_scopes`.
`policy_denied` (403) with `decision_id`	A policy refused the call.	Read the decision on the Decisions log screen with the `decision_id`.
`dlp_blocked` (403)	The arguments hold sensitive data the DLP blocks.	Remove or mask the data.
Answer `202` with `pending_approval`	The call needs a human approval.	Approve it in the Approvals inbox, then call again with `approval_id`.
`upstream_unavailable` or `upstream_error` (502)	The service behind the tool does not answer or failed.	Check the endpoint of the tool.

What the screen shows​

Actions​

Roles​

Typical tasks​

Register a tool and test it​

Approve a tool for production use​

Block a dangerous tool at once​

Troubleshooting​

Related pages​