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.
| Pattern | Calls | Buys you |
|---|---|---|
| Optimize before send | The optimize call, between the code that knows the recipient and your send queue | Every message written from your context, with no data connected and nothing waiting on Amdahl |
| Check before you query | GET /search/overview, then Search | An empty result you can explain |
| Cohort, then voice | Search (filter), then Search (semantic) | A population with its own words attached, no agent run |
| Optimize before it ships | The optimize call with mode: "grade", read on passes_bar | A send or hold decision on copy an agent wrote |
| Evaluate two versions | Several evaluations of each version, or a prompt run | A difference you can attribute to the edit |
| Evaluations as a trend | Many evaluations, logged by you | A week-over-week measure of writing quality |
| Keep two verdicts apart | Any two evaluators | A 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.
- Gather the context: who the recipient is, a reason to write now, what you offer, and the ask.
POST /messages/optimizewith that context (thefactsandrulesincontext), in a background job with a 310 second timeout. It usually answers in 1 to 2 minutes.- On
ok: true, queuemessageexactly as returned, and logomitted: what the message left out because your context could not back it. - On
ok: falseor a timeout, there is no message: queue your own fallback (or hold the send) and logreason. Send noon_missing_inputhere: the default,best_effort, always writes a message, whileaskreturns 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.
GET /search/overview. If everyrow_countis0, stop and say the workspace has no data yet.- 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.
POST /search/querywithsurface: "deals"and filters such asdeal_stage_status = "won". Collect thecompany_idvalues.POST /search/querywithmode: "semantic",filters: [{ "field": "company_id", "op": "in", "value": [...] }]andhydrate: 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.
- Your agent writes the message.
POST /messages/optimizewith{ "mode": "grade", "message": "…", "evidence": "workspace" }(MCPoptimize_message). It writes nothing and returns the evaluation (grade) on the same call.- Branch on
grade.passes_bar:truesends,falseholds,nullmeans nothing could be evaluated, so pass it through and showgrade.not_applicable_reasonto 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.
- Evaluate version A and version B one after the other, with the same
evidenceandcontext, so both read the same state of the workspace. - Evaluate each version several times. Check that each response has its own
optimize_id: two responses with the sameoptimize_idare one evaluation. - Compare the medians of
passedoftotal, 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.
- Evaluate every draft that matters, or a fixed sample each week, with the same
evidencesetting. - Log
passed,total,score, the evaluation model (grade.judge.modelandjudge_version) and the date in your own store. - Report the weekly pass rate per criterion. Leave out evaluations whose
scoreisnull: 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
- Use cases: GTM jobs mapped to these patterns.
- Optimize before you send: Amdahl in a send pipeline, with code.
- Evaluate a cold email: one evaluation, read end to end.
- The learning loop: the full write, ground, evaluate, fix loop.