End-to-end MCP agent handoff: publish, review, correct, and continue

What proves an MCP agent handoff worked end to end?

A complete test proves connectivity, workflow completion, and continuity as separate properties. Connectivity proves the host can call the server. Workflow completion proves an authenticated actor created a retrievable revision with intact source artifacts. Continuity proves a different authenticated actor can inspect that revision, contribute attributable review or work, and leave the record ready for the next actor.

• The server resolves each person or service agent independently.
• The publisher preserves Markdown, SQL, and JSON as original artifacts.
• The reviewer reads the exact immutable revision before commenting.
• The correction becomes a later revision instead of replacing the reviewed file.
• The resolved annotation links to the revision that addressed it.
• A successor retrieves the latest canonical revision without the original chat.

What is the complete MCP tool sequence?

Use ten explicit checkpoints and save the returned identifiers at each write boundary. Search before create prevents duplicate records, read-back proves artifact integrity, and expectedRevisionId prevents one collaborator from silently overwriting another.

Principal A
1. handover.whoami
2. handover.search
3. handover.create with context.md, query.sql, and evidence.json
4. handover.get + handover.read_artifact

Principal B
5. handover.whoami
6. handover.get + handover.read_artifact
7. handover.annotate + handover.assign

Principal A or C
8. handover.continue with expectedRevisionId

Principal B
9. handover.get + handover.update_comment with resolvedRevisionId

Successor
10. handover.get + handover.annotations, then continue from the current revision

Why should the workflow publish files instead of only a summary?

A summary helps discovery, but the next actor needs the original evidence to verify and continue the work. Publish the operating brief in Markdown, executable analysis in SQL or code, and structured claims in JSON so each artifact remains inspectable, downloadable, and independently usable.

• context.md records objective, state, decisions, constraints, and next action.
• query.sql preserves executable analysis instead of paraphrasing it.
• evidence.json gives agents structured claims, provenance, and verification state.
• Credentials, hidden reasoning, and unrelated personal data never belong in an artifact.

How does review stay attached to the evidence?

The reviewer first reads the immutable artifact, then creates an annotation containing the handover ID, artifact ID, revision ID, exact selected text, surrounding context, and actionable feedback. Mentions and assignments can notify authorized collaborators, but they do not grant access or approve consequential actions.

handover.annotate({
  handoverId,
  body: "The denominator must exclude cancelled trials. Correct the SQL and evidence.",
  target: {
    revisionId,
    artifactId,
    targetKind: "text",
    selector: {
      exact: "COUNT(*) AS trial_count",
      prefix: "SELECT\n  ",
      suffix: ",\n  SUM(converted)",
      startOffset: 9,
      endOffset: 32
    }
  },
  mentionPrincipalIds: [resolverPrincipalId]
})

How is the correction verified and resolved?

The resolver rereads the current revision, publishes corrected artifacts with that revision as expectedRevisionId, and receives a new immutable revision. The reviewer then reads the corrected file and resolves the annotation with resolvedRevisionId set to that new revision. Resolution is evidence about a completed correction, not a substitute for publishing one.

• Do not resolve against the original revision.
• Do not resolve before reading the corrected artifact.
• Keep unrelated findings open.
• Record what changed in the continuation note and brief.

Which failure paths must the test include?

A production test should deliberately exercise authorization and concurrency failures. A principal outside the workspace must be unable to retrieve the record, and a continuation using an obsolete expectedRevisionId must return a revision conflict. Those failures prove that continuity does not weaken access control or overwrite protection.

• Denied identity: search or get does not reveal protected context.
• Read-only identity: retrieval succeeds but create, annotate, or continue is refused.
• Stale revision: continue fails and the actor must reread before retrying.
• Revoked credential: subsequent protected calls fail without exposing the credential.

What are the pass criteria?

The workflow passes only when all actors are server-attributed, all source files round-trip intact, every revision is immutable, the review remains anchored to the reviewed revision, the correction is a later revision, resolution names that correction, the successor can state the objective and next action without the original conversation, and denied or stale operations fail as designed.