# Tool Testing

## Execute a tool in test mode

> Run an HSM tool outside a live session for testing.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ToolExecuteRequest":{"properties":{"tool_type":{"type":"string","maxLength":64,"title":"Tool Type","description":"world_tool — other tool families use their dedicated endpoints"},"tool_name":{"$ref":"#/components/schemas/NameString","description":"Fully qualified tool name"},"service_id":{"type":"string","format":"uuid","title":"Service Id","description":"Service ID that owns the HSM"},"input_params":{"additionalProperties":true,"type":"object","title":"Input Params","description":"Parameters to pass to the tool handler"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"Optional entity ID for context"},"dry_run":{"type":"boolean","title":"Dry Run","description":"If true, write tools are simulated without persistence","default":false}},"type":"object","required":["tool_type","tool_name","service_id"],"title":"ToolExecuteRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"ToolExecuteResponse":{"properties":{"result":{"title":"Result"},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"dry_run":{"type":"boolean","title":"Dry Run","default":false},"source":{"type":"string","title":"Source","default":"tool_test"},"tool_type":{"type":"string","title":"Tool Type","default":""},"tier":{"type":"string","title":"Tier","default":"world"},"is_write":{"type":"boolean","title":"Is Write","default":false},"sub_tool_logs":{"items":{"$ref":"#/components/schemas/SubToolLogItem"},"type":"array","title":"Sub Tool Logs"},"blocked_side_effects":{"items":{"type":"string"},"type":"array","title":"Blocked Side Effects"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","title":"ToolExecuteResponse"},"SubToolLogItem":{"properties":{"tool_name":{"type":"string","title":"Tool Name","default":""},"input":{"additionalProperties":true,"type":"object","title":"Input"},"output":{"type":"string","title":"Output","default":""},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"succeeded":{"type":"boolean","title":"Succeeded","default":true}},"type":"object","title":"SubToolLogItem"}}},"paths":{"/v1/{workspace_id}/tools/execute":{"post":{"tags":["Tool Testing"],"summary":"Execute a tool in test mode","description":"Run an HSM tool outside a live session for testing.","operationId":"execute-tool-test","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolExecuteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolExecuteResponse"}}}},"401":{"description":"Missing or invalid credentials."},"403":{"description":"Insufficient permissions."},"422":{"description":"Invalid request body."},"503":{"description":"Voice agent service unavailable."}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Resolve tools for a service

> List all tools available for a service's HSM with metadata.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ToolResolveResponse":{"properties":{"tools":{"items":{"$ref":"#/components/schemas/ResolvedToolItem"},"type":"array","title":"Tools"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"}},"type":"object","required":["tools","service_id","workspace_id"],"title":"ToolResolveResponse"},"ResolvedToolItem":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"tool_type":{"type":"string","title":"Tool Type"},"description":{"type":"string","title":"Description","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"states":{"items":{"type":"string"},"type":"array","title":"States"},"tier":{"type":"string","title":"Tier","default":"world"},"is_write":{"type":"boolean","title":"Is Write","default":false},"additional_instructions":{"additionalProperties":{"type":"string"},"type":"object","title":"Additional Instructions"}},"type":"object","required":["tool_name","tool_type"],"title":"ResolvedToolItem"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/services/{service_id}/tools/resolve":{"get":{"tags":["Tool Testing"],"summary":"Resolve tools for a service","description":"List all tools available for a service's HSM with metadata.","operationId":"resolve-service-tools","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"service_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Service Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResolveResponse"}}}},"401":{"description":"Missing or invalid credentials."},"403":{"description":"Insufficient permissions."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Voice agent service unavailable."}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/tool-testing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.