docs: task_completed is named for one question and defined as another #44

Page or section

API Reference, CallTask.task_completed in openapi/calle.openapi.yaml. It is also the field the Quickstart and Webhooks examples print, without explaining it.

Problem

The field is called task_completed. The spec defines it as something else:

Post-summary judgment for whether the task reached a clear end state for the user.

Reaching a clear end state and getting the job done are different questions, and the gap between them is where the trouble is. A call that hits an answering machine reaches a very clear end state. Nothing was asked and nothing was answered.

That is not hypothetical. One of my calls reached a voicemail box. The transcript is one turn from the other side, and it is the machine playing its greeting. The agent asked its question three times into the tone and hung up. It came back:

{ "status": "completed",
  "task_completed": true,
  "completion_confidence": { "score": 0.9, "label": "high" },
  "structured_result": { "open_saturday": "unknown", "evidence": "<the greeting>" } }

task_completed is true. The declared result sitting next to it says the question was never answered. Under the spec's definition the true is arguably correct, which is the point: the definition and the name disagree, and the name is what everybody reads.

The guides make it worse by never surfacing the definition at all. task_completed appears in the Quickstart and the Webhooks payload as example output with no gloss, and the Calls guide only says it "comes from the post-call summary". The one sentence that would warn you is in the OpenAPI description, which is the last place somebody looks.

For comparison I dialled a recorded information line where the task genuinely could be done. The agent heard it, pulled the announced value out of the audio, and got it right. task_completed: true and confidence 0.92. The voicemail call scored 0.90. So completion_confidence does not separate them either.

Suggested improvement

Put the definition where people meet the field. A line in the Calls guide saying task_completed means the call reached a clear end state, and that a clear end state includes an answering machine, would do most of the work.

Worth saying plainly what to pair it with, since the Calls guide already recommends declaring an answered-by field in a result schema. That recommendation reads as optional polish right now. It is the thing that stops a voicemail box being indistinguishable from a person, so it deserves to sit next to task_completed rather than in a different section.