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 a Sonnet subagent with the research question. Receive a structured summary.
• Write actions: Dispatch to a Haiku subagent with a pre-built action manifest. Mechanical execution, no judgment required.

Credentials

Ozone tools require four environment variables: OZONE_HANDLE, OZONE_ADMIN_PASSWORD, OZONE_DID, OZONE_PDS. These are NOT in .mcp.json — they load from the project .envrc via direnv. Non-secret values live directly in .envrc; OZONE_ADMIN_PASSWORD lives in secrets/ozone.env, loaded by .envrc via source_env_if_exists. The MCP server inherits them at startup, so claude must be launched from a directory where the .envrc is active. All tools fail gracefully with a clear error if credentials are missing; do not print secret values.

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.

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

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.

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.

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.

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.

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").

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.

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 ozone_query_statuses.

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.

ozone_unmute

Remove a mute from a previously muted subject.

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 not in .mcp.json — OZONE_HANDLE, OZONE_DID, OZONE_PDS live in the project .envrc; OZONE_ADMIN_PASSWORD lives in secrets/ozone.env, loaded via direnv. If credentials are missing, the operator should update .envrc, run direnv allow ., and restart Claude Code from that directory
• Auth route: PDS proxy, not direct Ozone connection
• 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
• batchId is optional but recommended: Makes audit trails traceable — group related operations under one UUID