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

ozonequerystatuses

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

Parameters (all optional):

| Parameter | Type | Description | |-----------|------|-------------| | subject | string | Filter to a specific DID or AT-URI | | review_state | string | Filter by review state (e.g., open, escalated, closed) | | tags | array | Filter by tags applied to subjects | | takendown | bool | Filter for subjects that have been taken down | | appealed | bool | Filter for subjects with active appeals | | limit | number | Results per page | | cursor | string | Pagination cursor from previous response | | sort_field | string | Field to sort by (e.g., lastReportedAt, lastReviewedAt) | | sort_direction | string | asc or desc |

Common recipes:

| Goal | Parameters | |------|-----------| | Recent user reports | sort_field: "lastReportedAt", sort_direction: "desc", limit: 20 | | Open appeals | appealed: true, sort_direction: "desc" | | Unreviewed subjects | review_state: "open", sort_field: "lastReportedAt", sort_direction: "desc" | | All reports for one account | subject: "did:plc:..." | | Tagged for follow-up | tags: ["follow-up"], review_state: "open" | | Escalated subjects | review_state: "escalated" |

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.

ozonequeryevents

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

Parameters (all optional):

| Parameter | Type | Description | |-----------|------|-------------| | subject | string | Filter to a specific DID or AT-URI | | types | array | Filter by event type (e.g., label, acknowledge, comment, escalate, tag, mute, report) | | created_by | string | Filter by moderator DID | | created_after | string | ISO datetime — events after this time | | created_before | string | ISO datetime — events before this time | | added_labels | array | Filter for events that applied specific labels | | has_comment | bool | Filter for events with comments | | limit | number | Results per page | | cursor | string | Pagination cursor | | sort_direction | string | asc or desc |

Common recipes:

| Goal | Parameters | |------|-----------| | Full moderation history for an account | subject: "did:plc:...", sort_direction: "asc" | | Recent label actions | types: ["label"], sort_direction: "desc", limit: 50 | | Events by a specific moderator | created_by: "did:plc:...", sort_direction: "desc" | | All actions in a time window | created_after: "2026-04-01T00:00:00Z", created_before: "2026-04-28T00:00:00Z" | | Check if a label was ever applied | subject: "did:plc:...", added_labels: ["spam"] | | Events with moderator notes | has_comment: true, sort_direction: "desc" |

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.

| Parameter | Required | Description | |-----------|----------|-------------| | subject | yes | DID or AT-URI | | label | yes | Label string to apply or remove | | action | yes | "apply" or "remove" | | cid | post-level only | Content hash for AT-URI subjects | | comment | no | Reasoning for the label action | | batchId | no | UUID grouping related operations | | duration_in_hours | no | For temporary labels — auto-expires after this duration |

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.

| Parameter | Required | Description | |-----------|----------|-------------| | subject | yes | DID or AT-URI | | acknowledgeAccountSubjects | no | true to acknowledge all reported content by this account | | comment | no | Reasoning | | cid | post-level only | Content hash | | batchId | no | UUID |

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.

| Parameter | Required | Description | |-----------|----------|-------------| | subject | yes | DID or AT-URI | | comment | yes | Comment text | | sticky | no | true for persistent visibility in the moderation UI | | cid | post-level only | Content hash | | batchId | no | UUID |

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.

| Parameter | Required | Description | |-----------|----------|-------------| | subject | yes | DID or AT-URI | | comment | no | Reasoning for escalation | | cid | post-level only | Content hash | | batchId | no | UUID |

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.

| Parameter | Required | Description | |-----------|----------|-------------| | subject | yes | DID or AT-URI | | add | no | Array of tag strings to add | | remove | no | Array of tag strings to remove | | comment | no | Reasoning | | cid | post-level only | Content hash | | batchId | no | UUID |

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.

| Parameter | Required | Description | |-----------|----------|-------------| | subject | yes | DID or AT-URI | | duration_in_hours | yes | How long to mute | | comment | no | Reasoning | | cid | post-level only | Content hash | | batchId | no | UUID |

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.

| Parameter | Required | Description | |-----------|----------|-------------| | subject | yes | DID or AT-URI | | comment | no | Reasoning | | cid | post-level only | Content hash | | batchId | no | UUID |

ozoneresolveappeal

Resolve an appeal on a subject.

| Parameter | Required | Description | |-----------|----------|-------------| | subject | yes | DID or AT-URI | | comment | yes | Explanation of the resolution (required) | | cid | post-level only | Content hash | | batchId | no | UUID |

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: skywatch-bsky
• Source: skywatch-bsky/skywatch-agent-skills
• License: MIT
• Homepage: https://bsky.app/profile/skywatch.blue

Install and usage instructions live in the source repository linked above.