Lesson 03

A tool advertisement is not permission.

A dashed card labeled untrusted hint, and a signed manifest card that holds reversibility, compensation, and the schema.
Annotations travel with the catalog. The manifest is what the engine obeys.

tools/list returns transactional metadata under _meta["org.agenttxprotocol/transaction"]. Catalogs may also carry the alias x-atp-transaction. The proxy copies the signed definition into _meta. It does not authorize a call from either annotation. If the manifest does not name the tool, the call does not run.

The inventory example

The compatibility shape lives in spec/examples/transfer-inventory.tool.json. The forward call moves stock. The compensation calls the same tool with the warehouses swapped and a new transfer id.

{
  "reversibility": "COMPENSATABLE",
  "idempotencyKeyPath": "$.input.transfer_id",
  "compensation": {
    "tool": "transfer_inventory",
    "argumentMapping": {
      "transfer_id": "'comp_' + input.transfer_id",
      "sku": "input.sku",
      "qty": "input.qty",
      "source_wh": "input.target_wh",
      "target_wh": "input.source_wh"
    },
    "maxRetries": 5,
    "onCompensationFailure": "ESCALATE_HITL"
  }
}

Mapping values are expressions. They can read input, output, and tx.id. There is no I/O. A COMPENSATABLE tool with an empty mapping is rejected when the manifest is opened.

The idempotency key is not your business key

After the caller’s arguments pass schema validation, the engine injects:

idempotency_key = txId + ":" + stepIndex + ":" + sha256(canonical(arguments)).substring(0, 32)

The hash covers the arguments before the key is added, so a schema with additionalProperties: false still accepts the payload the agent sent. idempotencyKeyPath is stored beside that key as a business identifier. A dotted path deeper than one field is ignored. Compensation uses comp: plus the forward key plus the attempt number, and that value overwrites any mapped idempotency_key.

The client supplies txId, 1 to 80 characters from [A-Za-z0-9_.:-]. The same id and the same plan hash returns the recorded result. The same id with a different plan is AtpIdempotencyConflict (−31807).

Sign the manifest

The document is { payload, signature }. The signature is Ed25519 over the canonical JSON of payload. Canonical form sorts object keys, emits no insignificant whitespace, and writes 10 rather than 1E+1.

java -jar mcp-tx-proxy/target/tx-engine.jar keys
java -jar mcp-tx-proxy/target/tx-engine.jar sign --kid admin --private <base64> --payload manifest.json

The payload needs manifestId, a non-empty tools array, and optional rules. Each tool has name, an object inputSchema, and a transaction object. The adapter is oltp, lakehouse, or api. An API tool with dry-run left on must include a dryRunExample object. Dry-run defaults to true unless the boolean false is set.

Unknown kid, a bad signature, a duplicate tool name, a missing compensation, or a rule whose onFail is neither DENY nor PAUSE rejects the whole manifest. The engine does not start with a half-trusted catalog.

Next: stop a plan that touches too much.