Agent Tools

Governed, owner‑scoped tools that AI agents call to read and (in one case) write catalog state. Every tool is defined by a contract — a static, versioned declaration of its inputs, outputs, scope, entitlement, redaction policy, and approval requirements. Discovery and execution share one contract source, so the catalog cannot drift between runtimes.

All routes live under https://app.swayzio.com/api/swayzio/v1/agent-tools and require a Clerk actor. These are the same tools the AI Chat endpoints drive internally.

Endpoints

Method	Path	Purpose	Auth	Request	Response
`GET`	`/v1/agent-tools/contracts`	List the read/write tool contracts	Clerk actor	(none)	`{ tools: AgentToolContract[] }`
`POST`	`/v1/agent-tools/execute`	Execute one tool + record an audit row	Clerk actor	`agentToolExecutionRequestSchema`	`agentToolExecutionResponseSchema`

The Fastify Core API also exposes GET /v1/agent-tools/access-policy, GET /v1/agent-tools/adapter-manifest, and a legacy POST /v1/agent-tools. On the native Vercel surface those are proxy‑only (not ported); the two routes above are the supported native interface. The adapter manifest describes how MCP / ADK bridges should wrap these contracts.

The governance model

Each contract is enforced server‑side, not by the calling agent:

Owner scope — ownerIdSource is always "authenticated actor ownerId". The owner comes from the verified credential; a tool can never read or write another account’s data.
Guarded inputs — bodies are validated against a discriminated‑union schema keyed on toolName, each branch .strict() (unknown fields rejected). AI callers additionally run assertSafeAgentToolInput before forwarding.
Redacted outputs — every contract carries a redactionPolicy; results return catalog/operational metadata only — no signed media URLs, storage URIs, share tokens, or raw provider payloads.
Approval‑gated writes — a contract with requiresHumanApproval: true (only addTrackToPack) must be approved by a human before execution. In the chat surface this renders an Approve / Cancel card.
Audited — every execute call records an owner‑scoped agent_actions audit row and returns its id as actionId.

The tools

Seven tools are executable. Six are read‑only; one is an approval‑gated write.

Tool	Class	Approval	Purpose
`searchTracks`	read	no	Owner‑scoped catalog search (NL, tags, BPM, key, genre, mood, similarity)
`getTrackContext`	read	no	One track with optional tags + processing status
`getRightsContext`	read	no	Rights + split‑sheet context for one track
`findMissingMetadata`	read	no	Missing‑metadata / readiness gaps across the catalog
`suggestProcessingRetries`	read	no	Advisory retry candidates for a track (never enqueues work)
`listPacks`	read	no	The owner’s packs (ids, names, track counts)
`addTrackToPack`	write	yes	Add one track to one pack — requires human approval

Each contract returned by /contracts includes: name, version, purpose, dataAccessTier, readWriteClass (read · write · mutating_suggestion · destructive · outbound · billing), inputSchema, outputSchema, requiredClaims, ownerIdSource, entitlementCheck, dataSources, writesProductState, requiresHumanApproval, idempotencyKey?, timeoutMs, rowLimit?, byteLimit?, rateLimitKey, redactionPolicy, agentActionsEvent, bigQueryTraceEvent, and rollbackOrCompensationPlan.

`GET /v1/agent-tools/contracts`

Returns the full contract catalog. Use it to discover which tools are active and to read each tool’s input/output schema before calling execute.

curl -s https://app.swayzio.com/api/swayzio/v1/agent-tools/contracts \
  -H "Authorization: Bearer $SWAYZIO_TOKEN"

{
  "tools": [
    {
      "name": "searchTracks",
      "version": "v1",
      "purpose": "Return a small owner-scoped slice of catalog records for agent reasoning, QA, and retrieval context.",
      "dataAccessTier": "static_api_contract",
      "readWriteClass": "read",
      "requiredClaims": ["sub"],
      "ownerIdSource": "authenticated actor ownerId",
      "entitlementCheck": "catalog_read",
      "writesProductState": false,
      "requiresHumanApproval": false,
      "timeoutMs": 3000,
      "rowLimit": 20
    }
  ]
}

`POST /v1/agent-tools/execute`

Executes a single tool and records the audit row. The body is a discriminated union: { toolName, input }, where input is validated against that tool’s strict schema. The response echoes the tool’s governance flags alongside the redacted result and the actionId of the audit row.

curl -s -X POST https://app.swayzio.com/api/swayzio/v1/agent-tools/execute \
  -H "Authorization: Bearer $SWAYZIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "toolName": "searchTracks", "input": { "query": "dark trap 140 bpm", "limit": 5 } }'

{
  "actionId": "act_…",
  "toolName": "searchTracks",
  "dataAccessTier": "static_api_contract",
  "readWriteClass": "read",
  "requiresApproval": false,
  "executedAt": "2026-06-10T00:00:00.000Z",
  "result": {
    "contextKind": "global_track_search",
    "records": [],
    "recordCount": 0,
    "resolvedMode": "hybrid"
  }
}

The approval‑gated write looks the same on the wire but its contract sets requiresHumanApproval: true; callers (including the chat surface) must obtain human approval before invoking it:

curl -s -X POST https://app.swayzio.com/api/swayzio/v1/agent-tools/execute \
  -H "Authorization: Bearer $SWAYZIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "toolName": "addTrackToPack", "input": { "packId": "pack_123", "trackId": "trk_456", "packName": "Summer Demos", "trackTitle": "Sunset Drive" } }'

Invalid input returns 400 { "error": "validation_error", "issues": [...] }. Tool errors are surfaced as structured, privacy‑safe payloads ({ "error": "<code>", "message": "..." }) with an appropriate status. See Conventions for the shared error model and Data Contracts for the full contract and execution schemas.

Analytics AI Chat