Skywatch Querying Ozone

Querying Ozone

Reference guide for the 10 Ozone MCP tools available through the skywatch-mcp server. Covers parameter patterns, filter combinations, pagination, and common recipes. Load this skill when you need to interact with the Ozone moderation API.

Delegation Pattern

Ozone read queries (queue pulls, event history) and write actions (labelling, acknowledging, escalating) should be dispatched to subagents rather than executed inline by the supervisory agent. Pass the subagent the parameters it needs — subject, label, comment, batchId — and let it execute. This preserves the supervisory agent's context window for decision-making.

• Read queries: Dispatch to the data-analyst subagent with the research question. Receive a structured summary.
• Write actions: Dispatch to the general-purpose-mini subagent with a pre-built action manifest. Mechanical execution, no judgment required.
• ⚠️ Subagent data loss risk: When subagents are dispatched to collect data (fetch records, profiles, media), intermediate collection results are lost if the subagent fails to return structured data in its final message. Only the final message content persists in the task log. Ensure subagent prompts include explicit instructions to return structured summaries — if the subagent's output is unstructured or missing data, re-dispatch with a leaner, more focused prompt.

Rate limit note: Burst-launching 5+ subagents simultaneously can trigger 429 rate limit errors. Cap dispatch waves at 3 parallel launches; stagger retries.

Credentials

Ozone tools require five environment variables: OZONE_HANDLE, OZONE_ADMIN_PASSWORD, OZONE_DID, OZONE_PDS, OZONE_SERVICE_URL. All are set in .envrc in the project root. All tools fail gracefully with a clear error if credentials are missing.

Auth goes through the PDS (via atproto-proxy header), not directly to the Ozone service. The ozoneRequest helper automatically retries on ExpiredToken with a session refresh — no manual retry logic needed.

Direct HTTP API Access (No MCP Server)

On Letta Cloud (or any environment where the skywatch-mcp stdio MCP server is not available), Ozone API calls can be made directly via HTTP using curl or Python. The auth flow and endpoint mapping are documented in references/http-api-access.md.

Key points:

• Auth goes through the PDS: create a session via com.atproto.server.createSession, then use the accessJwt with atproto-proxy: [OZONE_DID]#atproto_labeler header
• Writes MUST go through PDS proxy, not direct service URL: All write operations (label, acknowledge, comment, escalate, tag, mute) use tools.ozone.moderation.emitEvent via POST https://{pds}/xrpc/... — direct POSTs to OZONE_SERVICE_URL return 401 BadJwtType
• Read operations: queryStatuses and queryEvents are GET requests. queryStatuses?unresolvedOnly=true is silently ignored on this deployment — filter by reviewState manually (full lexicon ref, e.g. tools.ozone.moderation.defs#reviewOpen)
• queryStatuses.labels projection is empty even when labels applied — queryLabels is BROKEN on this deployment (501 via service URL, MethodNotImplemented via PDS proxy, as of 2026-08-27); verify labels via queryEvents with types=tools.ozone.moderation.defs#modEventLabel instead
• queryLabels requires uriPatterns (not uri) on this deployment's lexicon — historical note; the endpoint is currently 501 anyway
• Newer-version response shape: the response key is subjectStatuses (not subjects); SubjectStatus items have NO reports array and NO subjectProfile; report reasons surface in tags as report:<reasonType>; reporter identity and report comments require a separate queryEvents?types=modEventReport call (comments live at .event.comment, NOT .event.report.comment)
• Token expiry must be handled manually (no auto-retry like the MCP server's ozoneRequest helper)
• ClickHouse queries go through SSH + Docker (see references/http-api-access.md for the command pattern)

When MCP tools are available, prefer them — they handle auth, retries, and type safety automatically. Use direct HTTP only when the MCP server is not configured.

Subject Format

All tools accept a subject parameter. Two formats:

• Account-level: Pass a DID (did:plc:...). Actions apply to the account.
• Post-level: Pass an AT-URI (at://did:plc:.../app.bsky.feed.post/...). Requires cid parameter — resolve it via com.atproto.repo.getRecord if not already known.

When in doubt, use account-level subjects. Post-level operations are for labelling or acting on specific content rather than the account as a whole.

Read Tools

mcp__skywatch-mcp__ozone_query_statuses

Query the moderation queue. Returns subjects with their current review state, tags, and metadata.

Parameters (all optional):

Common recipes:

Pagination: When results exceed limit, the response includes a cursor. Pass it in the next call to get the next page. Continue until no cursor is returned.

⚠️ Newer-version response shape (2026-08-17): This deployment returns a newer Ozone API shape that diverges from the MCP abstraction. Underlying response key is subjectStatuses (NOT subjects — jq '.subjects | length' returns 0 on null and silently masks real results). SubjectStatus items do NOT embed a reports array or subjectProfile; report reasons surface in the tags array as report:<reasonType> (e.g. report:harassment-other, report:misleading-scam). Reporter identity and report comments require a separate queryEvents call with types=modEventReport — report comments are at .event.comment on those events, NOT .event.report.comment (which silently returns null). queryStatuses?subject=<did> returns ONLY the account subject, not the account's reported records — query each post AT-URI separately. Acknowledged record-level subjects vanish from queryStatuses entirely — verify post-level acks via the emitEvent response ID, not a later subject query.

mcp__skywatch-mcp__ozone_query_events

Query moderation event history. Returns a log of all moderation actions taken on subjects.

Parameters (all optional):

Common recipes:

Write Tools

Common Conventions

batchId: All write tools accept an optional batchId (UUID string). Use a single batchId to group related operations — e.g., all labels applied during one queue triage session share one batchId. Generate a new UUID for each logical batch of work. Different types of actions (labelling vs. acknowledging) within the same session may use the same batchId if they're part of the same workflow.

comment: Most write tools accept an optional comment. Use it to record reasoning for the action. Comments become part of the permanent moderation event history.

Metadata: All write tools automatically include modTool metadata (name: "skywatch-mcp") for traceability.

mcp__skywatch-mcp__ozone_label

Apply or remove a moderation label.

When to use: After reviewing evidence and determining a policy violation. Use duration_in_hours for temporary labels on borderline cases or time-limited enforcement.

mcp__skywatch-mcp__ozone_acknowledge

Move a subject from open/reported to reviewed. Closes reports.

When to use: After reviewing a subject and completing all actions (labelling, no-action, etc.). Acknowledgement closes the report in the queue. Use acknowledgeAccountSubjects: true to bulk-close all reports for an account in one call.

mcp__skywatch-mcp__ozone_comment

Add a comment to a subject's moderation record.

When to use: To record observations, investigation notes, or context that other moderators should see. Use sticky: true for important context that should remain visible (e.g., "this account is part of a coordinated network — see investigation report YYYY-MM-DD").

mcp__skywatch-mcp__ozone_escalate

Escalate a subject for higher-level review.

When to use: When a subject requires review by someone with more authority or context — policy edge cases, high-profile accounts, potential legal issues.

mcp__skywatch-mcp__ozone_tag

Add or remove tags from a subject's moderation record.

At least one of add or remove is required.

When to use: For categorisation, tracking, or workflow routing. Tags are searchable via mcp__skywatch-mcp__ozone_query_statuses.

mcp__skywatch-mcp__ozone_mute

Mute a subject for a specified duration.

When to use: To suppress a subject from the queue temporarily — e.g., an account that's been reviewed but may need re-evaluation after a cooling period.

mcp__skywatch-mcp__ozone_unmute

Remove a mute from a previously muted subject.

mcp__skywatch-mcp__ozone_resolve_appeal

Resolve an appeal on a subject.

When to use: When a user has appealed a moderation action and you've reviewed the appeal. The comment is mandatory — document why the appeal was upheld or denied.

Gotchas

• Credentials via direnv — non-secret Ozone settings live in .envrc; OZONE_ADMIN_PASSWORD lives in secrets/ozone.env, loaded by .envrc via source_env_if_exists. The skywatch-mcp Polytoken MCP server should be launched through direnv exec /path/to/project ... so Ozone tools receive OZONE_HANDLE, OZONE_ADMIN_PASSWORD, OZONE_DID, OZONE_PDS, and OZONE_SERVICE_URL at server startup.
• Auth route: PDS proxy, not direct Ozone connection — direct writes to OZONE_SERVICE_URL with proxied session JWTs return 401 BadJwtType
• cid required for post-level: If you have an AT-URI but no cid, resolve it first via com.atproto.repo.getRecord
• Auto-retry on token expiry: The ozoneRequest helper handles ExpiredToken automatically — don't add manual retry logic
• Acknowledge closes reports: Acknowledgement is the "done" action — use it after all other actions are complete, not before
• Always acknowledge after labeling (subjects AND posts): Labeling without acknowledging leaves the report open in the queue. queryStatuses?subject=<did> returns only the account subject — reported posts remain open and unacknowledged and must be handled individually. Never leave labeled subjects unacknowledged.
• Batch labeling in ≤50-account chunks: Ozone rate-limits bulk labeling; batches of 200+ accounts may timeout. If a batch times out, check how many were labeled before the failure, then resume with the remaining accounts.
• modEventLabel uses OLD field names: createLabelVals / negateLabelVals (not create / negate), and negateLabelVals is required — send [] when negating nothing. createdBy is a TOP-LEVEL body property (old lexicon), not inside the event object. Comments must be a separate modEventComment event.
• Verify labels via queryEvents, not queryLabels: queryStatuses.labels is empty even when labels applied, and queryLabels is BROKEN on this deployment as of 2026-08-27 (501 via service URL, MethodNotImplemented via PDS proxy). Confirm subject DID, createLabelVals, and createdBy on queryEvents?types=tools.ozone.moderation.defs#modEventLabel events instead.
• batchId is optional but recommended: Makes audit trails traceable — group related operations under one UUID. Note batchId inside the event body is silently dropped (not in the lexicon); persist it via top-level modTool.meta.batchId.
• ALWAYS resolve actor DIDs via com.atproto.identity.resolveHandle immediately before emitting labels: never write a target DID from memory, session context, or notes — DID conflation mislabels innocent accounts (three incidents: julian-reichelt 2026-08-20, aragornreedsyhere feed-extraction 2026-08-20, 13bullits 2026-08-30 — the last was a label applied to the wrong DID because the DID was carried over from earlier query results; caught 40 s later via post-emit verification). For 0-post or newly-created subjects, verify DID→handle→displayName against the investigation BEFORE emitting, and always verify the applied label by subjectHandle via queryEvents afterwards.