Docs

Patterns

Call sequences that work: optimize before send, check before you query, cohort then voice, optimize before it ships, evaluate two versions, evaluations as a trend, and keep two verdicts apart.

Each pattern below is a short sequence of Amdahl's calls, with the field that makes it safe. GTM engineers use them to put Amdahl into the agents they build. They assume you have read Evidence and trust.

PatternCallsBuys you
Optimize before sendThe optimize call, between the code that knows the recipient and your send queueEvery message written from your context, with no data connected and nothing waiting on Amdahl
Check before you queryGET /search/overview, then SearchAn empty result you can explain
Cohort, then voiceSearch (filter), then Search (semantic)A population with its own words attached, no agent run
Optimize before it shipsThe optimize call with mode: "grade", read on passes_barA send or hold decision on copy an agent wrote
Evaluate two versionsSeveral evaluations of each version, or a prompt runA difference you can attribute to the edit
Evaluations as a trendMany evaluations, logged by youA week-over-week measure of writing quality
Keep two verdicts apartAny two evaluatorsA well-written claim nobody made stays visible

Optimize before send

Code that sends outbound gathers what it knows about each recipient. Amdahl then writes the message before it is queued.

  1. Gather the context: who the recipient is, a reason to write now, what you offer, and the ask.
  2. POST /messages/optimize with that context (the facts and rules in context), in a background job with a 310 second timeout. It usually answers in 1 to 2 minutes.
  3. On ok: true, queue message exactly as returned, and log omitted: what the message left out because your context could not back it.
  4. On ok: false or a timeout, there is no message: queue your own fallback (or hold the send) and log reason. Send no on_missing_input here: the default, best_effort, always writes a message, while ask returns questions that a send queue cannot answer.

Never post-process message with another model: the checks that kept your facts exact ran on that text. With no data connected, Amdahl runs the evaluation without your data, so it does not evaluate claims against your customers' conversations. Add evidence: "workspace" once your conversations sync. Where claims matter, also optimize before it ships. The full recipe is Optimize before you send.

Check before you query

A workspace that has not synced yet answers every search with an empty, well-formed result. GET /search/overview returns the row count and time span for each surface of your processed customer data, with null meaning the read failed rather than zero rows.

  1. GET /search/overview. If every row_count is 0, stop and say the workspace has no data yet.
  2. Run the search. An empty result is now a real "nothing matched".

The onboarding skill runs this check first for the same reason.

Cohort, then voice

Find the population with typed filters, then read what it said, without starting an agent.

  1. POST /search/query with surface: "deals" and filters such as deal_stage_status = "won". Collect the company_id values.
  2. POST /search/query with mode: "semantic", filters: [{ "field": "company_id", "op": "in", "value": [...] }] and hydrate: true. You get the utterances from those accounts, ranked by meaning, with quotable text.

Both calls are synchronous, so the whole sequence finishes in two round trips. Semantic search reads customer-side speech only (corpus.speaker_scope: "external_only"), which is what you want here.

Optimize before it ships

Your agent writes the outbound copy. Amdahl evaluates it against your customers' own conversations before anything ships.

  1. Your agent writes the message.
  2. POST /messages/optimize with { "mode": "grade", "message": "…", "evidence": "workspace" } (MCP optimize_message). It writes nothing and returns the evaluation (grade) on the same call.
  3. Branch on grade.passes_bar: true sends, false holds, null means nothing could be evaluated, so pass it through and show grade.not_applicable_reason to a person.

Without evidence: "workspace", only cta_clarity is evaluated, so a pass says only that the ask is clear. On a hold, fix the criteria that failed (each has a reason) and evaluate again, or have Amdahl write the message from your context. Evaluate the copy exactly as it will be sent: a change after the evaluation is a change Amdahl never read. For what a pass means, see What an evaluation measures.

Evaluate two versions

You edit a draft and want to know whether the edit helped. Two things move besides your edit. Each evaluation reads your conversations at the time of the call, and one evaluation is one reading.

  1. Evaluate version A and version B one after the other, with the same evidence and context, so both read the same state of the workspace.
  2. Evaluate each version several times. Check that each response has its own optimize_id: two responses with the same optimize_id are one evaluation.
  3. Compare the medians of passed of total, criterion by criterion. A difference of one criterion on one evaluation is inside what a repeat can move.

For the prompt behind the drafts, POST /messages/optimize_prompt in improve mode runs this comparison itself: it evaluates the original and the revised prompt on recipients held out from the revision, and reports lift only when lift_reportable is true. Send the same recipients to every run you compare. See Improve a prompt.

Evaluations as a trend

One evaluation is a reading. The trend over many evaluations is the metric.

  1. Evaluate every draft that matters, or a fixed sample each week, with the same evidence setting.
  2. Log passed, total, score, the evaluation model (grade.judge.model and judge_version) and the date in your own store.
  3. Report the weekly pass rate per criterion. Leave out evaluations whose score is null: nothing was evaluated, and a zero would be a false measurement.

Compare two windows only when the same evaluation model, at the same judge_version, evaluated both.

Keep two verdicts apart

A message can be well written and assert something no customer ever said. A single blended number hides that.

When you combine Amdahl's evaluation with any other evaluator, a house style check, or a person's opinion, report each verdict on its own. Within one evaluation, read grade.lines criterion by criterion: grounding and verified_specifics answer "can we back this up", and cta_clarity answers something else.

See also