# Invoke an agent tool
URL: https://backworkhealth.com/docs/api/invokeAgentTool

Invokes one high-level Backwork tool through the controlled agent access layer.

**Endpoint:** `POST /api/v1/agent/tools/{tool}`

**Availability:** Live in production.

**Authentication:** API key in `Authorization: Bearer <key>` with the `read` scope.

Invokes one high-level Backwork tool through the controlled agent access layer. Use `GET /agent/tools` first to fetch the exact input schema for each tool. Read tools accept `read`, `admin`, `agent:tool:*`, or the tool-specific `agent:tool:<tool_id>` scope; write tools require `write`, `admin`, `agent:tool:*`, or the tool-specific scope. A key that holds any `agent:tool:` scope is limited to its agent scopes. `acknowledge_policy_change` also requires a plan with compliance dashboard access. Requests containing patient-identifying field names are rejected with `PHI_NOT_ALLOWED`.

**Parameters**

* `tool` (path, required): Agent tool ID
* `X-Backwork-Agent` (header): Optional agent name recorded in the invocation ledger. Must not contain PHI.
* `X-Backwork-Approval` (header): Set to `reviewed` only after authorized review for tools that return approval\_required=true.

**Example request**

```bash
curl -X POST "https://backworkhealth.com/api/v1/agent/tools/check_coverage" \
  -H "Authorization: Bearer $BACKWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string"
}'
```

**Example response** (`200`)

```json
{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "string",
    "timestamp": "2026-01-15T10:30:00Z",
    "tool": "check_coverage",
    "actor_type": "api_client",
    "actor_name": "string",
    "approval_status": "not_required"
  }
}
```