Docs

Evaluate claims against your customers

Once your conversations are connected, send evidence: workspace and Amdahl also evaluates every claim in the message it writes against your customers' own conversations. It lists the claims nothing backs and keeps them unless you say otherwise. When to turn it on, how to read it, and when an evaluation alone is the better call.

Level: once your data is connected. Call: messages.optimize with "evidence": "workspace". You need: a Customer agent key or the Amdahl MCP connector, and a workspace with synced conversations.

Everything in the other outreach cookbooks works with nothing connected: by default, Amdahl evaluates how a message reads and how clearly it asks. This is the step after. Connect your CRM and call recorder, and the same call can also evaluate every claim in the message against your customers' own conversations. It tells you which claims nothing backs.

Check there is something to read

Evidence needs synced conversations. GET /search/overview returns a row count per surface; anything above 0 on interactions means there is something to evaluate against:

bash
curl -s "https://app.amdahl.ai/api/platform/v1/search/overview" -H "X-API-Key: $AMDAHL_KEY" | jq '.data.surfaces[] | {surface, row_count}'

If the counts look low, check that your sources are still syncing. GET /setup/status (over MCP, the get_setup_status tool) lists every connection that needs attention, under needs_attention in its connections section, for example one that needs you to sign in to the source again. See Check your setup.

On a workspace with nothing synced yet the call below still succeeds. It is evaluated without your data, and the response says so in evidence.reason.

The call

The same request as always, plus one field:

json
{
  "message": "Hi Priya,\n\nSaw Ledgerline moved invoicing in-house last quarter. Most finance teams we work with lose a week at every month-end close after a move like that.\n\nTallyworks reconciles every invoice as it lands, and teams like yours close 60% faster in the first month.\n\nWorth 15 minutes on Thursday?\n\nJordan",
  "channel": "email",
  "evidence": "workspace"
}

It is slower than the evaluation without your data, because each evaluation reads quotes from your conversations. Keep the 180-second client timeout.

What changes

Default (evidence off)evidence: "workspace"
Evaluated onHow the message reads and how clearly it asksThat, plus four dimensions against your customers' own words: relevant_positioning, grounding, verified_specifics and differentiation
ClaimsNot evaluated. unsupported_claims is null.Each claim nothing in your conversations backs is listed in unsupported_claims, and kept in the message unless you say otherwise
The messageWritten from your contextAlso reads up to 8 customer quotes, to ground what it says. It never quotes them or presents them as the recipient's words.
Before and afterNo score: the evaluation model re-evaluates the message on yes/no questionslift, on a run that improves a draft. A message written from context has no before, with or without a draft.
SpeedUsually 1 to 2 minutesSlower

Read evidence first

json
"evidence": { "requested": "workspace", "used": true }

Say a draft was evaluated against your customers only when used is true. When it is false, reason says why, and none of these is an error (the rewrite still came back):

reasonWhat happened
corpus_emptyThe workspace has no conversations to read yet.
evidence_unavailableThis environment does not read customer conversations, so the run was evaluated without your data.
evidence_read_failedThe read failed and the four evidence dimensions were not evaluated. A retry may succeed.

Claims nothing backs

This response is illustrative: the company and its claims are made up. Its shape is exactly what the live API returns, trimmed to the claim fields and two notes.

json
{
  "data": {
    "ok": true,
    "unchanged": true,
    "summary": "Kept your version: the rewrite dropped a claim this request asked to keep, so it was discarded. Nothing in your workspace's conversations backs 3 claims in this message. Check them before you send it.",
    "evidence": { "requested": "workspace", "used": true },
    "on_unsupported": "flag",
    "unsupported_claims": [
      {
        "span": "Saw Ledgerline moved invoicing in-house last quarter",
        "kind": "about_recipient",
        "why": "No conversation with Ledgerline mentions this, and no fact was sent with the draft.",
        "dimension": "grounding",
        "status": "kept",
        "fix": [
          { "action": "add_fact", "how": "if it is true, re-run with context.facts: [\"Saw Ledgerline moved invoicing in-house last quarter\"]" },
          { "action": "add_evidence", "how": "cite a source, or optimize again with evidence \"workspace\"" },
          { "action": "rephrase" }
        ]
      },
      {
        "span": "Most finance teams we work with lose a week at every month-end close after a move like that",
        "kind": "product_or_outcome",
        "why": "Customers describe slower closes after a systems change, but none puts it at a week.",
        "dimension": "grounding",
        "status": "rewrite_rejected",
        "fix": [{ "action": "rephrase" }]
      },
      {
        "span": "teams like yours close 60% faster in the first month",
        "kind": "about_recipient",
        "why": "No quote states a close-time figure.",
        "dimension": "verified_specifics",
        "status": "kept",
        "fix": [{ "action": "add_evidence", "how": "cite a source, or optimize again with evidence \"workspace\"" }, { "action": "rephrase" }]
      }
    ],
    "notes": [
      {
        "code": "unsupported_claims_kept",
        "audience": "developer",
        "says": "3 claims couldn't be matched to your workspace's conversations. See unsupported_claims before sending. They were kept because on_unsupported is flag. Ask the user about each one. If it is true, re-run with it in context.facts. If it has a source, add the evidence. Otherwise, offer to re-run with on_unsupported: \"remove\". Never remove one without asking."
      },
      {
        "code": "rewrite_rejected_for_claim_loss",
        "audience": "developer",
        "says": "A rewrite was discarded because it dropped 1 of the claims this request asked to keep (on_unsupported: flag). The previous version stands. The score played no part in this."
      }
    ]
  }
}

Each entry is one claim, copied exactly from the draft in span, with what happened to it in status:

  • kept: still in the returned message. By default (on_unsupported: "flag") every claim stays, because it may be the one thing the sender knows and the conversations do not.
  • rewrite_rejected: still there because a rewrite that dropped it was thrown away. Here that is why the whole draft came back unchanged.
  • removed: the rewrite cut or softened it. That only happens when you asked for it.

While any claim is still in the message, do not call the draft ready, and neither will summary. Go through them with the sender, one at a time:

  1. True, and they know it first-hand? Re-run with it in facts inside context, in their words. A fact that states the claim clears it; one that says less does not. See Keep your voice, rules and facts.
  2. It has a source (a press release, a public case study)? Cite it in the message, and add what the source states as a fact.
  3. Neither? Offer to re-run with "on_unsupported": "remove", which lets the rewrite soften or cut the listed claims, or let the sender reword it.

Never re-run with remove without asking. And neither mode changes the evaluation: a claim nothing backs still fails grounding.

Reading lift on an evidence run

When a rewrite reaches the blind re-evaluation, lift carries the before and after on a 1 to 5 scale, with what was measured (the numbers here are illustrative):

json
"lift": {
  "before": 3.14,
  "after": 3.71,
  "delta": 0.57,
  "method": "blind_regrade_pinned",
  "dimensions": ["cta_clarity", "differentiation", "grounding", "human_tone", "length_discipline", "relevant_positioning", "verified_specifics"],
  "quotes": 20,
  "returned": "rewrite"
}

The evaluation model, a different model from the one the rewrite was chosen with, evaluates your draft and the rewrite against the same quotes. It makes one call each, and neither call is told which is which. quotes says how many it read. lift is the only before-and-after score in the response, so it is the only one to quote. It is null whenever nothing reached the re-evaluation (as in the kept draft above). Field by field: Reading lift.

To show a person how the draft got there, add "include_tries": true: tries lists every version the run scored, draft first. Those scores are Amdahl's own scoring during the search, so they show the path, not proof. Never quote the first try against the last as an improvement; quote lift. See Reading tries.

Write, evaluate, or improve the prompt

All three read the same conversations with evidence: "workspace". They answer different questions:

You wantUse
A better version of this draft, in the sender's voice, with the claims nothing backs flaggedmessages.optimize, with evidence: "workspace"
Every criterion passed or failed, with the reason for each, and nothing writtenEvaluate a message: the same call with mode: "grade"
A better prompt for the agent or template that writes the draftsImprove a prompt (optimize_prompt)
A send or hold decision for a pipelineAn evaluation, read on whether it meets the bar (grade.passes_bar). See Optimize before it ships.

What an evaluation's score means is on What an evaluation measures.

To use an evaluation and a write on one message, keep the two verdicts apart in whatever you hand back: see Keep two verdicts apart.

Every field is on Optimize a message.