# 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

- 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

1. Open the registry on the **Tools** page and select the **Test** tab.
2. Choose the handler. For an `http` or `grpc` handler with one inline tool, the tool name defaults to that tool. For an `openapi` or `mcp` handler, choose the tool.
3. 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

| 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

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`](/how-to/tools/advanced-http-tools/#source-a-secret-header) 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

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

### 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

Fix the Secret name or key in the handler. The error names the header or Secret.

## Related pages

- [Build a tool backend](/how-to/tools/build-a-tool-backend/)
- [Authenticate tools](/how-to/tools/authenticate-tools/)
- [ToolRegistry reference](/reference/core/toolregistry/)