references/tools.md

# NewsTune plugin tools

The plugin uses OAuth. Tool authorization is handled by the host; never request or transmit an API key.

## Read tools

- `get_account_overview`: returns account status, tier limits, total credits, and current server-owned prices. It does not spend credits.
- `list_podcast_series`: accepts `limit`, `offset`, and `latestEpisodesPerSeries`; keep calling with `nextOffset` until it is `null` when full discovery is needed.
- `get_podcast_series`: accepts `seriesId` and a bounded `episodeLimit`; it returns the persistent `customPrompts`. Read every non-empty field before continuing, scripting, or publishing a show.
- `list_podcast_voices`: filters authorized hosts and voices by query, language, and source. A returned preview URL is read-only; listing never adopts or renders a voice.
- `preview_podcast_series_creation`: accepts the complete final private-series payload, reads affordability, and returns the exact charge plus a short-lived opaque `previewId` when affordable. It never creates a series or spends credits and remains read-only. Retain the `previewId` as tool context, not user-facing text. After it returns, ask for a self-contained approval that repeats the title, private action, and exact charge; a bare approval in the next turn continues this exact preview.
- `get_generation_status`: accepts the job ID returned by episode creation. Poll reasonably until success or failure and return an episode-page URL, not a raw audio URL.

## Protected write tools

- `confirm_podcast_series_creation`: executes the exact unexpired private-series preview after explicit approval. Pass exactly `{ "previewId": <opaque ID from preview>, "confirmed": true }`; NewsTune retrieves the full payload, quote, signed confirmation, and stable idempotency key server-side. Use this tool for short follow-ups such as “I approve” or “同意扣除 20 credits.” It never publishes the created series.
- `create_podcast_series`: compatibility-only combined preview/execution tool for older clients. It supports title, topic, language, `brief`/`deep`/`ultra` format, duration, approved host IDs, and eight detailed `customPrompts` fields. Do not choose it for a new preview-then-confirm workflow or for a short approval; use `preview_podcast_series_creation` followed by `confirm_podcast_series_creation`.
- `create_podcast_episode`: creates a private episode in an owned series. Read the series `customPrompts` first. `material_to_podcast` accepts an aligned approved brief/source pack and applies the stored prompts in NewsTune; `script_to_audio` requires a final script already written according to those prompts. Preview the exact charge. Confirm interactively for a manual run; in an approved recurring run, auto-execute only when the quote and inputs remain inside the schedule contract.
- `prepare_voice_action`: creates a short-lived NewsTune handoff for `select_voice`, `clone_my_voice`, or `clone_authorized_voice`. For selection, pass `selectionCount: 1` or `2`; an accessible public/community voice may be selected with a short non-deception/endorsement advisory and is not blocked solely because of its name. Cloning requires `authorizationConfirmed: true`; the user completes consent and upload in NewsTune.
- `publish_podcast_series`: previews and then publishes an exact approved scope. The preview separately returns the immediate audio-ready scope and `futurePublicEpisodeNumbersAfterAction`/`futurePublicEpisodesAfterAction`. Enumerate and explicitly approve both scopes for interactive work. In an approved recurring run, auto-execute only when the selected scope is the one new episode, other public episodes remain unchanged, and RSS/slug/SEO match the contract. `rssAction` is always explicit; recurring runs normally use `preserve`. See the publisher skill.

## Confirmation invariants

- For series creation, do not reconstruct or resend content inputs after preview. Pass only the exact opaque `previewId` and `confirmed: true` to `confirm_podcast_series_creation`; NewsTune binds the stored payload and quote to the connected OAuth principal.
- Keep `previewId`, confirmation tokens, and idempotency keys tool-internal. The user-facing approval should repeat the title, private action, and exact credit charge, never the coordination values.
- A bare approval such as “同意扣除 20 credits” routes directly from the immediately preceding unexpired preview to `confirm_podcast_series_creation`. If context is missing or expired, preview again rather than saying the confirmation tool is unavailable or falling back to `create_podcast_series`.
- `insufficient_credits` has no confirmation token and is a terminal stop until the balance independently changes. Report the balance and quote, confirm that no write or debit occurred, and do not retry, switch accounts, bypass billing, or direct the user to buy credits, upgrade, subscribe, or open a payment link.
- A stale preview, changed quote, changed immediate or future-public scope, or expired token requires a new preview. Interactive work needs new approval; scheduled work may auto-execute the replacement only when it is still exactly within the stored recurring contract.
- Never parallelize two protected write calls for the same series.

## Recurring workflows

A host automation may gather changed project information, generate one episode, and publish it automatically after the user approves a recurring contract at setup. The automation prompt must include target series/hosts/mode/credit ceiling; every exact source and location; required/preferred/background/excluded, freshness, citation, provenance, and checkpoint rules; all `customPrompts` and editorial style; privacy boundaries; visibility/RSS behavior; and retry/skip conditions.

Each run reads the live series and recent episodes, collects only changed relevant material, excludes credentials/build artifacts, previews and executes the covered charge, polls to completion, then previews and publishes only the new episode while preserving RSS. It never asks a question. Insufficient credits or any target/source/editorial/host/credit/visibility/RSS/slug/SEO/scope mismatch pauses or skips without advancing the checkpoint.