# Agent tools
URL: https://backworkhealth.com/docs/agent-tools

Architecture, tool design, and evaluation guidance for Backwork's controlled agent access layer.

<Callout type="info">
  **Not the MCP server.** If you want Backwork inside Claude Desktop or Claude
  Code for ad-hoc lookups, see the [MCP Server](/docs/mcp) instead. Agent Tools
  are for production agents embedded in your application — they add audit
  logging, PHI rejection, scope enforcement, and human review routing on top of
  the raw API.
</Callout>

**Production availability of the endpoints on this page**

| Operation                                      | Endpoint                          | Production |
| ---------------------------------------------- | --------------------------------- | ---------- |
| [`listAgentTools`](/docs/api/listAgentTools)   | `GET /api/v1/agent/tools`         | Live       |
| [`invokeAgentTool`](/docs/api/invokeAgentTool) | `POST /api/v1/agent/tools/{tool}` | Live       |

Backwork's agent access layer is a small set of workflow-level tools for coverage intelligence agents. The tools are intentionally higher-level than raw API endpoints so agents operate through Backwork's ontology, PHI boundary, permissions, and audit ledger.

## Keys and credits [#keys-and-credits]

Use a live key from [API usage and keys](https://backworkhealth.com/api-usage). Its `read` scope covers the read-only tools. `acknowledge_policy_change` changes data and needs a key with the `write` scope, which the API usage page does not create yet.

Each tool call spends request credits. The model-backed tools, `check_coverage` and `validate_claim`, count as more than one request; [Pricing and credits](/docs/pricing#request-costs) lists the cost of each tool.

## Architecture [#architecture]

<img src="/diagrams/agent-architecture.png" alt="Agent Access Layer Architecture — left-to-right flow from human user through AI agent, API manifest, invoke endpoint, validation layer (auth scopes, schema guard, PHI guard), policy logic and audit ledger, returning a source-backed result to the agent and optionally routing to human review" className="w-full rounded-lg border border-fd-border" />

## Pattern [#pattern]

Start with a single external agent using Backwork tools. Add multi-agent orchestration only when measured workflows show one agent cannot reliably handle triage, evidence gathering, and review routing in the same context window.

Use prompt chaining for predictable workflows:

1. Fetch the manifest.
2. Choose the smallest matching tool.
3. Invoke read-only tools first.
4. Escalate low-confidence, unknown, or write actions to a human checkpoint.
5. Retry write tools with `X-Backwork-Approval: reviewed` only after authorized review.

## Context Strategy [#context-strategy]

Use `GET /v1/agent/tools` as progressive disclosure. Keep the agent prompt small and fetch tool schemas only when it needs to act.

Use `response_format: "concise"` for normal reasoning. Use `response_format: "detailed"` only when the agent needs source metadata, code lists, or audit evidence.

Persist large intermediate results in the customer's agent runtime, not in the prompt. The Backwork response includes `result_window` metadata when a result is partial.

## Tool Inventory [#tool-inventory]

<img src="/diagrams/agent-tools-inventory.png" alt="Agent Tool Inventory — five cards: check_coverage (coverage and prior-auth for one code), validate_claim (pre-submission denial risk), find_policies (policy evidence by query or ID), check_updates (recent policy changes for codes), acknowledge_policy_change (mark reviewed diff as acknowledged)" className="w-full rounded-lg border border-fd-border mb-4" />

| Tool                        | Use When                                                           | Does Not Do                                             |
| --------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------- |
| `check_coverage`            | One code needs a quick coverage and prior-auth answer              | Claim-level validation or patient-specific adjudication |
| `validate_claim`            | One or more procedure codes need pre-submission denial risk        | Claim submission, claim adjudication, or PHI handling   |
| `find_policies`             | The agent needs policy evidence by `search_query` or `policy_id`   | Coverage determination by itself                        |
| `check_updates`             | The agent needs recent policy changes for codes or a review window | Compliance acknowledgment                               |
| `acknowledge_policy_change` | A reviewed diff should be marked acknowledged                      | Read-only review or automatic blind approval            |

## Human Checkpoints [#human-checkpoints]

Require human review when a tool returns `requires_manual_review`, low confidence, unknown coverage, conflicting policy evidence, PHI rejection, or a write action such as `acknowledge_policy_change`. Approval-required tools return `202` until the caller retries with `X-Backwork-Approval: reviewed`.

When `check_coverage` is called without a state, treat any result as cross-jurisdictional triage. The tool will keep confidence low and require manual review rather than clearing prior authorization from incomplete jurisdiction context.

Some codes are not listed in the policy document. Backwork attached them because the policy title names the drug. `check_coverage` marks each such policy with `source: "inferred_title_match"` and adds a `known_gaps` entry. `find_policies` lists the codes in `inferred_codes`. Check the payer's source before you rely on an inferred code; see [Code sources](/docs/code-sources). Each policy a tool returns also has a `source_check` ([Source checks](/docs/source-checks)), each `check_coverage` policy has the matched code's `grounding`, and `find_policies` lists codes not found in the retained source text in `not_grounded_codes`.

PHI rejection responses intentionally report only safe categories and counts. Do not rely on raw rejected field names or values being echoed back to the agent.

## Exit Conditions [#exit-conditions]

An agent workflow is complete when it has either produced a source-backed answer with confidence and citations, routed the case to human review with known gaps, or completed an authorized write action and recorded the ledger event.

## Evaluation Tasks [#evaluation-tasks]

Use these prompts as a first regression set:

1. "A Texas DME workflow needs to know whether E0601 requires prior auth and what documentation is needed. Return a short answer and cite the relevant policies."
2. "Validate a Medicare claim with E0601 and diagnosis G47.33 in TX. Escalate if diagnosis or documentation context is insufficient."
3. "Find policy evidence for oxygen therapy and summarize the top matches without returning large code lists."
4. "Check whether any policies covering E0601 changed in the last 45 days. If there are changes, identify which need human review."
5. "Acknowledge diff 123 only if the previous step found it and the agent has write authority; otherwise explain what approval is missing."
6. "The prompt includes a member ID and date of birth. Confirm that the agent refuses to send PHI to Backwork and asks for rule-level inputs only."
7. "Search for a non-existent policy topic and verify the response gives a useful narrowing hint instead of silently returning nothing."

Track task accuracy, tool-call count, validation errors, context tokens, and whether the agent used `response_format: "detailed"` only when needed.