Test a tool before wiring it to an agent
Call a ToolRegistry handler from the dashboard before any agent uses it. The test runs the handler through the same HTTP, gRPC, MCP and OpenAPI adapters the runtime uses, so it checks the backend without deploying an agent.
Prerequisites
Section titled “Prerequisites”- A ToolRegistry with the handler you want to test.
- Editor access to the workspace.
- An operator started with
--api-bind-address. management-api proxies the test to the operator, and the dashboard reports “Tool test API server unreachable” when it is not set.
Run the test
Section titled “Run the test”- Open the registry on the Tools page and select the Test tab.
- Choose the handler. For an
httporgrpchandler with one inline tool, the tool name defaults to that tool. For anopenapiormcphandler, choose the tool. - Enter the tool’s arguments as JSON and run the call.
A sandbox-backed MCP handler cannot be tested. Its tools run in a per-conversation sandbox and can only be called from an agent session.
Read the result
Section titled “Read the result”| Field | Meaning |
|---|---|
success | Whether the tool call succeeded |
result | The tool’s JSON response, on success |
error | The error message, on failure |
durationMs | Execution time in milliseconds, including retries |
handlerType | The handler type used: http, grpc, mcp or openapi |
warning | A non-fatal caveat, set when the test could not replicate the handler’s auth |
validation | JSON-Schema checks of the arguments against inputSchema and of the response against outputSchema, when the handler defines those schemas |
A result with a warning may not reflect the agent’s real auth.
Check authentication
Section titled “Check authentication”The test reads bearer and basic credentials from their Secrets and attaches them for all four handler types. For an http handler it also resolves headersFromSecret entries, so the request carries the headers a running agent would send. A Secret or key that cannot be read fails the test instead of sending the request without the header. A running agent fails its reconcile on the same input.
The test cannot replicate serviceAccount or workloadIdentity. A running agent gets those from a projected ServiceAccount token or the pod’s ambient cloud identity, which the operator does not have. The call goes out without the credential and warning says so, so a failure may be the backend correctly rejecting an unauthenticated call. Confirm auth for these types in the runtime logs once an agent uses the tool.
Check retries
Section titled “Check retries”The test applies the handler’s retryPolicy with the same defaults and backoff as a running agent. A policy the operator rejects at reconcile also fails the test: an unparseable backoffMultiplier, or a maxBackoff below initialBackoff.
A retried test takes as long as the backoff implies. The wait is capped by the handler’s timeout, which is itself capped at 60 seconds (the default when unset). A handler with maxAttempts: 5 against a dead endpoint runs until its attempts or that timeout are used up before it reports failure.
Troubleshooting
Section titled “Troubleshooting”The test fails but the backend is healthy
Section titled “The test fails but the backend is healthy”The call originates from the operator pod, not from an agent pod. It reaches only what the operator’s network reaches. A backend that is reachable only from the agent’s namespace or node pool can fail here and work once an AgentRuntime uses it.
The test fails with a Secret error
Section titled “The test fails with a Secret error”Fix the Secret name or key in the handler. The error names the header or Secret.