# Zebrafish Tool Belt

Use this reference when a Zebrafish skill needs project context, assets, Studio
generation, workflow authoring, run monitoring, or debugging.

## Discovery And Planning

- `get_agent_playbook`: read compact operating rules before non-trivial work.
- `list_models`: inspect available Studio models, constraints, and pricing
  before generation.
- `list_campaigns` and `get_campaign`: find project context.
- `get_campaign_knowledge`: load brand/project knowledge before prompts,
  scripts, claims, or visual direction.
- `list_campaign_assets`: inspect existing reference files before uploading or
  generating new assets.

## References And Assets

- `upload_campaign_asset_from_url`: default path for public HTTPS assets.
- `create_campaign_asset_upload` plus `finalize_campaign_asset_upload`: local
  file upload path.
- `get_campaign_asset_url`: read back a project asset when the agent needs bytes
  or a provider-reachable URL.

Record the source URL, campaign asset ID, role, and any constraints attached to
each reference.

## Studio Generation

- `create_studio_generation`: create image, video, or audio generations. Check
  model constraints and pricing first, and treat this as spend.
- `get_studio_generation`: poll until `succeeded`, `failed`, or `timed_out`.
- `list_studio_generations`: recover recent generations, compare variants, or
  resume interrupted work.

For every generation, record prompt, model, parameters, references, campaign ID,
generation ID, cost if available, status, and output URLs.

## Billing And Credits

- `purchase_credits`: buy org-bound prepaid credits only after explicit spend
  approval. This tool requires an API key with `billing:purchase_credits`, the
  hosted deployment's agent-payments flag, an available rail, and an explicit
  `idempotencyKey`. Every new key can spend real money; reuse the same key only
  when retrying the same approved purchase. The response may be
  `requires_action` with `action.url`, which a human or browser-capable agent
  must open to finish payment. Credits become usable only after settlement.
- `get_credit_purchase`: poll after `purchase_credits` returns
  `requires_action` or `pending_settlement`; stop when the purchase is
  `confirmed`, `failed`, or `expired`.

If these tools are missing, stop and explain that billing tools are disabled or
not available in this client. They are hosted-MCP/API-key tools and are hidden
from the in-app session agent. Do not use them to bypass the spend gate; normal
generation and workflow spend still needs approval.

## Workflow Production

- `create_workflow_from_template`: start a repeatable workflow.
- `get_agent_authoring_guide`: read workflow authoring rules.
- `get_workflow_context`: inspect an existing workflow and latest revision.
- `validate_workflow_definition`: validate a draft before saving.
- `save_draft_revision`: save a draft with optimistic concurrency.
- `test_run_draft`: run an unpublished workflow safely before publishing.
- `publish_workflow_revision`: publish only after explicit approval.
- `run_workflow`: run an existing production workflow.

Use workflows when a production has multiple repeatable steps, approvals,
stitching, variants, or future reuse. Do not publish without explicit approval.

## Monitoring And Debugging

- `get_run`, `get_run_events`, and `get_run_trace`: poll and inspect execution.
- `get_run_costs`: capture cost evidence.
- `get_run_detail_errors`: get redacted errors for repair.
- `respond_run_approval`: approve or reject gated steps after the user decides.
- `cancel_run`: stop a queued or running workflow when needed.

When a run fails, gather run status, recent events, trace, costs, and redacted
detail errors before proposing a fix.