# Agent Utility Lab

> Reliability primitives and hard-to-find integration facts for autonomous agents.

## Machine entry points

- Catalog: /v1/catalog
- OpenAPI: /v1/openapi.json
- MCP: /mcp
- MCP server card: /mcp.json
- ARD catalog: /.well-known/ai-catalog.json
- Status: /v1/status
- Health: /v1/health
- Receipt verification keys: /v1/receipts/jwks.json
- Missing capability schema: /v1/capability-requests/schema (never submit credentials, direct contact information, or full conversation history)

## Discoverable tools

### PennyLock (penny-lock)
- Summary: Acquire an opaque distributed lock with a short TTL.
- Use when: One agent must briefly own an opaque resource while peers stand down. | Duplicate work is possible and a bounded distributed lock is sufficient.
- Do not use when: The operation itself must execute exactly once. | The resource identifier contains secrets or personal data.
- State/payment: beta / free
- Describe/execute: /v1/tools/penny-lock
- Idempotency required: true
- Errors: INVALID_INPUT[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]

### Global Seen Stamp (global-seen-stamp)
- Summary: Atomically record whether an opaque content hash has been seen.
- Use when: Agents need to know whether an opaque item was already observed. | A shared expiring deduplication marker is sufficient.
- Do not use when: A durable audit history is required. | The marker must never expire.
- State/payment: beta / free
- Describe/execute: /v1/tools/global-seen-stamp
- Idempotency required: true
- Errors: INVALID_INPUT[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]

### Exactly-Once Baton (exactly-once-baton)
- Summary: Issue and atomically consume a one-use capability token.
- Use when: A coordinator must issue a capability that can be consumed once. | Multiple agents may race to claim the same bounded action.
- Do not use when: A database transaction can directly protect the underlying operation. | The capability must be reusable.
- State/payment: beta / free
- Describe/execute: /v1/tools/exactly-once-baton
- Idempotency required: true
- Errors: INVALID_INPUT[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]

### Negative Cache Ticket (negative-cache-ticket)
- Summary: Record or check a typed, expiring failure state.
- Use when: Agents should share a typed, temporary record of a failed lookup. | Repeated work should pause until an explicit expiration time.
- Do not use when: The failure is permanent or requires a durable incident record. | The request contains raw credentials or personal data.
- State/payment: beta / free
- Describe/execute: /v1/tools/negative-cache-ticket
- Idempotency required: true
- Errors: INVALID_INPUT[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]

### Status-Code Forge (status-code-forge)
- Summary: Create a short-lived URL with controlled HTTP behavior.
- Use when: A client, webhook, or retry policy must be tested against controlled HTTP behavior. | A short-lived endpoint is needed for deterministic integration testing.
- Do not use when: The URL would be used for production traffic. | The response must contain sensitive or unbounded content.
- State/payment: beta / free
- Describe/execute: /v1/tools/status-code-forge
- Idempotency required: true
- Errors: INVALID_INPUT[retry=false,charged=false], NOT_COVERED[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]

### Safe Synthetic Fixture Vault (safe-synthetic-fixture-vault)
- Summary: Generate deterministic test records using reserved non-production values.
- Use when: An agent needs a clearly synthetic fixture for a supported schema. | Tests need deterministic data without copying production records.
- Do not use when: Real customer data or identity verification is required. | The requested fixture type is outside the published schema set.
- State/payment: beta / free
- Describe/execute: /v1/tools/safe-synthetic-fixture-vault
- Idempotency required: false
- Errors: INVALID_INPUT[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]

### Error-Code Cemetery (error-code-cemetery)
- Summary: Map a covered integration-error fingerprint to a tested diagnosis.
- Use when: An agent needs evidence about a deprecated or host-specific error code. | Compatibility behavior must be checked before changing an integration.
- Do not use when: The exact host, version, or error is outside the published dataset. | The answer would be treated as a guarantee about future host behavior.
- State/payment: beta / free
- Describe/execute: /v1/tools/error-code-cemetery
- Idempotency required: false
- Errors: INVALID_INPUT[retry=false,charged=false], NOT_COVERED[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]
- Dataset: 2026.07.24.1; Two deployment and OAuth errors observed during Agent Utility Lab staging setup.; observed 2026-07-24T00:00:00.000Z; valid until 2026-10-24T00:00:00.000Z

### 402 Error Rosetta Stone (x402-error-rosetta-stone)
- Summary: Translate a covered x402 failure fingerprint into a correction.
- Use when: An x402 failure must be mapped to a normalized cause and next check. | A buyer or seller integration needs evidence-linked diagnostic guidance.
- Do not use when: The protocol, host, network, or error is outside the published dataset. | Wallet custody or private-key handling is required.
- State/payment: beta / free
- Describe/execute: /v1/tools/x402-error-rosetta-stone
- Idempotency required: false
- Errors: INVALID_INPUT[retry=false,charged=false], NOT_COVERED[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]
- Dataset: 2026.07.24.1; Four x402 v2 client, header, network, and verification failure fingerprints.; observed 2026-07-24T00:00:00.000Z; valid until 2026-08-24T00:00:00.000Z

### Worked-Once Recipe Vault (worked-once-recipe-vault)
- Summary: Return a covered, empirically verified integration recipe.
- Use when: An agent needs a versioned integration recipe observed to work once. | A minimal host-specific compatibility example can unblock testing.
- Do not use when: The requested host or version is outside the published dataset. | A recipe would be treated as a permanent compatibility guarantee.
- State/payment: beta / free
- Describe/execute: /v1/tools/worked-once-recipe-vault
- Idempotency required: false
- Errors: INVALID_INPUT[retry=false,charged=false], NOT_COVERED[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]
- Dataset: 2026.07.24.1; One TypeScript x402 v2 exact-payment recipe verified end-to-end against Agent Utility Lab staging on Base Sepolia.; observed 2026-07-24T00:00:00.000Z; valid until 2026-08-24T00:00:00.000Z

### Swarm Semaphore (swarm-semaphore)
- Summary: Bound concurrent agent work with an opaque distributed semaphore.
- Use when: A bounded number of agents may work on the same resource concurrently. | Each holder needs an independently expiring permit.
- Do not use when: Exactly one agent must own the resource; use PennyLock instead. | The holder identifier contains secrets or personal data.
- State/payment: beta / free
- Describe/execute: /v1/tools/swarm-semaphore
- Idempotency required: true
- Errors: INVALID_INPUT[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]

### Barrier Bell (barrier-bell)
- Summary: Release a bounded agent phase after enough unique participants arrive.
- Use when: A workflow phase should release after enough unique agents arrive. | The synchronization point can safely expire after a bounded interval.
- Do not use when: Every named participant must arrive or participant identities must be listed. | The barrier must remain durable indefinitely.
- State/payment: beta / free
- Describe/execute: /v1/tools/barrier-bell
- Idempotency required: true
- Errors: INVALID_INPUT[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]

### Freshness Lease (freshness-lease)
- Summary: Coordinate one renewable freshness owner without exposing identity.
- Use when: One agent should own a renewable refresh responsibility for a short period. | Peers need to see lease activity and expiry without learning the holder.
- Do not use when: The underlying refresh itself must execute exactly once. | A permanent ownership record is required.
- State/payment: beta / free
- Describe/execute: /v1/tools/freshness-lease
- Idempotency required: true
- Errors: INVALID_INPUT[retry=false,charged=false], TOOL_PAUSED[retry=true,charged=false], RATE_LIMITED[retry=true,charged=false], DEPENDENCY_UNAVAILABLE[retry=true,charged=false]


Inspect a tool manifest before invoking it. Invalid input and unsupported coverage are rejected before payment. Paid or side-effecting calls expose an execution.idempotency contract; reuse the same identifier only for recovery of the same normalized request. Verify X-Agent-Receipt as an Ed25519 compact JWS using the published JWKS.