Tool Testing

Test context graph tools in isolation without making phone calls. Execute world tools, skills, and integrations with source isolation and dry run mode.

The tool testing endpoints let you resolve all context graph tools (world tools, skills, integrations) for a service and execute world tools in isolation, without making a phone call. Skills and integrations are tested through their own dedicated test/invoke endpoints. This is useful during development for verifying tool behavior, debugging input/output schemas, and validating write operations before wiring tools into a live conversation flow.

Admin/owner only. Tool testing requires the tools:test scope, which is restricted to admin and owner roles.

Safety Guardrails

Tool test executions are isolated from production side effects:

• Source isolation: all writes are tagged source="tool_test", which is excluded from the outbound sync allowlist. No real EHR syncs or SMS deliveries happen.
• Surface delivery blocking: surfaces created during tool tests are blocked from delivery.
• Dry run mode: write tools can simulate execution without persisting results.

Resolve Available Tools

Retrieve the full list of tools available for a given service, including their input schemas, types, tiers, and write classification.

Resolve tools for a service

get

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

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

service_idstring · uuidRequired

Responses

200

Successful Response

application/json

service_idstring · uuidRequired

workspace_idstring · uuidRequired

401

Missing or invalid credentials.

403

Insufficient permissions.

422

Validation Error

application/json

503

Voice agent service unavailable.

get/v1/{workspace_id}/services/{service_id}/tools/resolve

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/services/{service_id}/tools/resolve HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "tools": [
    {
      "tool_name": "text",
      "tool_type": "text",
      "description": "",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "states": [
        "text"
      ],
      "tier": "world",
      "is_write": false,
      "additional_instructions": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}

Execute a Tool

Execute a single tool in isolation with custom input parameters.

Execute a tool in test mode

post

Run an HSM tool outside a live session for testing.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

application/json

tool_typestring · max: 64Required

world_tool — other tool families use their dedicated endpoints

tool_namestring · min: 1 · max: 256Required

Fully qualified tool name

service_idstring · uuidRequired

Service ID that owns the HSM

entity_idstring · uuid · nullableOptional

Optional entity ID for context

dry_runbooleanOptional

If true, write tools are simulated without persistence

Default: false

Responses

200

Successful Response

application/json

resultanyOptional

duration_msnumberOptionalDefault: 0

dry_runbooleanOptionalDefault: false

sourcestringOptionalDefault: tool_test

tool_typestringOptionalDefault: ""

tierstringOptionalDefault: world

is_writebooleanOptionalDefault: false

blocked_side_effectsstring[]Optional

errorstring · nullableOptional

401

Missing or invalid credentials.

403

Insufficient permissions.

422

Invalid request body.

503

Voice agent service unavailable.

post/v1/{workspace_id}/tools/execute

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/tools/execute HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 212

{
  "tool_type": "text",
  "tool_name": "text",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "input_params": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "dry_run": false
}

{
  "result": null,
  "duration_ms": 0,
  "dry_run": false,
  "source": "tool_test",
  "tool_type": "",
  "tier": "world",
  "is_write": false,
  "sub_tool_logs": [
    {
      "tool_name": "",
      "input": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "output": "",
      "duration_ms": 0,
      "succeeded": true
    }
  ],
  "blocked_side_effects": [
    "text"
  ],
  "error": "text"
}

World tools only. This endpoint executes world_tool tools exclusively. The skill, integration, platform function (fn_*), and workspace data query (wsq_*) tool families have their own dedicated invoke/test endpoints. Passing a non-world_tool type returns a validation error pointing at the dedicated endpoint:

• Skills: POST /v1/{workspace_id}/skills/{skill_id}/test
• Integrations: POST /v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}/test (addressed by integration and endpoint ID, not name)
• Platform functions: POST /v1/{workspace_id}/functions/{name}/invoke or /test
• Workspace data queries: POST /v1/{workspace_id}/data_queries/{query_id}/invoke (addressed by query ID, not name)

Rate limited. Tool execute is subject to write rate limits. Use resolve to inspect tools before executing.