Tools

The HTTP calls an agent can make while it is on a call.

A tool is a URL, a method, and parameters the model fills in. The agent decides when to call it from the description alone, so the description is the most important field here: it is the only part the model reads.

Tools are described in ordinary terms — a request with parameters that go in the path, the query, a header or the body — rather than in the voice stack's own schema, so which stack executes them is not something an integration has to know or track.

Attaching a tool to an agent is done on the agent, not here: see `PUT /api/v1/agents/{agentId}/tools`.

List tools

Tools the key can reach — created by this user, or shared to them.

GET/api/v1/tools

Responses

{
  "data": {
    "tools": [
      {
        "id": "tool_9a1c…",
        "name": "checkEligibility",
        "description": "Look up whether a member's plan is active on a given date.",
        "request": {
          "url": "https://api.example.com/eligibility/{memberId}",
          "method": "GET",
          "parameters": [
            {
              "name": "memberId",
              "in": "path",
              "schema": {
                "type": "string"
              },
              "required": true
            }
          ]
        },
        "usageCount": 1284
      }
    ]
  },
  "meta": {
    "requestId": "req_…"
  }
}

Request

curl -X GET "https://voice.evryhealth.com/api/v1/tools" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a tool

The name is what the model calls — 1-64 characters, letters, digits, underscores and hyphens. Write the description for the model, not for a person reading documentation.

POST/api/v1/tools

Responses

{
  "data": {
    "id": "tool_9a1c…",
    "name": "checkEligibility"
  },
  "meta": {
    "requestId": "req_…"
  }
}

Request

curl -X POST "https://voice.evryhealth.com/api/v1/tools" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "checkEligibility",
    "description": "Look up whether a member's plan is active on a given date. Call this before discussing coverage.",
    "url": "https://api.example.com/eligibility/{memberId}",
    "method": "GET",
    "parameters": [
      {
        "name": "memberId",
        "in": "path",
        "schema": {
          "type": "string"
        },
        "required": true
      },
      {
        "name": "asOf",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "required": false
      }
    ]
  }'

Get a tool

One tool and the request it makes.

GET/api/v1/tools/{toolId}

Path parameters

Parameter	Type	Description
`toolId`required	`string`	Tool id.

Responses

{
  "data": {
    "id": "tool_9a1c…",
    "name": "checkEligibility"
  },
  "meta": {
    "requestId": "req_…"
  }
}

Request

curl -X GET "https://voice.evryhealth.com/api/v1/tools/{toolId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a tool

Naming any part of the request rewrites the whole definition, from the current values where you did not say otherwise — the definition is one blob underneath, and a partial write would lose whatever the other writer set.

PATCH/api/v1/tools/{toolId}

Path parameters

Parameter	Type	Description
`toolId`required	`string`	Tool id.

Responses

{
  "data": {
    "id": "tool_9a1c…"
  },
  "meta": {
    "requestId": "req_…"
  }
}

Request

curl -X PATCH "https://voice.evryhealth.com/api/v1/tools/{toolId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/v2/eligibility/{memberId}"
  }'

Delete a tool

Removes the tool and takes it off every agent using it — an agent whose prompt still describes a tool that no longer answers is worse than one that lost it.

DELETE/api/v1/tools/{toolId}

Path parameters

Parameter	Type	Description
`toolId`required	`string`	Tool id.

Responses

{
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "req_…"
  }
}

Request

curl -X DELETE "https://voice.evryhealth.com/api/v1/tools/{toolId}" \
  -H "Authorization: Bearer YOUR_API_KEY"