# 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, skill, or integration"},"tool_name":{"$ref":"#/components/schemas/NameString","description":"Fully qualified tool name"},"service_id":{"type":"string","maxLength":64,"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","maxLength":64},{"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."}}}}}}
```

## 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","title":"Service Id"},"workspace_id":{"type":"string","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":"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."}}}}}}
```