Args:
    category: Restrict to one category (e.g. ``composition``, ``video``,
        ``model``, ``outpaint``). Call with no filters once — the response's
        ``categories`` / ``statuses`` maps are the full taxonomy.
    status: Restrict to one status (``live``, ``mostly-dead``,
        ``unimplemented``).
    include_reserved: When False (default) drop ``unimplemented``
        (recognized-but-blocked) parameters from the result.

Returns:
    A dict with ``count``, ``source`` (``live`` vs. ``bundled-snapshot``),
    ``categories`` / ``statuses`` (the filter taxonomy), and ``parameters``
    (the array of matching entries).

Args:
    query: Substring match, case-insensitive.
    category: Optional single-category restriction.
    include_reserved: Whether to include ``unimplemented`` parameters.

Returns:
    Dict with ``count``, ``source`` (``live`` vs. ``bundled-snapshot``),
    and ``parameters`` (ordered as they appear in the catalog).

Args:
    name: Parameter name with or without leading ``--`` (e.g. ``ar``,
        ``--ar``, ``aspect``). Case-insensitive.

Returns:
    The parameter dict. Not-found is an ``isError`` result — surface it
    rather than fabricating a param.

Args:
    prompt: The full prompt string, including any ``--flag`` parameters.
        E.g. ``"a fox in autumn foliage --ar 16:9 --flagship"``.
        Flags go at the END of the prompt. The ones people need most:
        ``--1`` / ``--2`` / ``--3`` / ``--4`` = how many images (default 4;
        ``--1`` for a single image, cheapest), ``--ar 16:9`` = aspect ratio,
        ``--v <model>`` = model. Anything else: call ``get_parameter(name)``
        or ``search_parameters`` first — never guess a flag.
    callback_url: Optional HTTPS URL that will receive a webhook when the
        generation reaches done / failed. See
        https://maginary.ai/blog/webhooks-guide for signature verification.

Returns:
    On success, the created generation record. Key fields: ``uuid`` (use
    to poll), ``action_type``, ``processing_state``,
    ``expected_output_count``.

    On failure, an ``isError`` result instead (nothing is raised), with a
    JSON body whose ``error`` field is one of:

    - ``"auth"`` — no/invalid API key. Surface the message directly to
      the human.
    - ``"payment_required"`` — out of credits. The body carries
      ``billing_url`` and ``challenge``: either send the human to
      ``billing_url`` to top up, or pay programmatically via x402 —
      ``challenge`` is the standard x402 payment-required payload (USDC
      on Base); settle it and retry this call.
    - ``"failed"`` — anything else (invalid prompt, rate limit, backend
      or network error); see ``message``.

    x402 over MCP: a ``payment_required`` result also carries the x402
    fields at the top level (``accepts``, ``resource``); an x402-capable
    client signs ``accepts[0]`` and calls this tool again with the payment
    in ``_meta["x402/payment"]``. The settled call returns the generation
    with ``x402_receipt`` (and ``_meta["x402/payment-response"]``); a
    wallet's first settlement also returns ``x402_account`` with an API
    key — pass it as ``_meta["maginary/api_key"]`` on later calls (or as
    the Authorization header of a new connection).

Args:
    uuid: The UUID returned by ``generate``.

Returns:
    The full generation record. If terminal, ``image_urls[]`` holds the
    finished outputs and ``processing_result.slots[]`` the per-slot detail.
    NOTE: a generation that failed server-side is a SUCCESSFUL tool call
    returning ``processing_state: "failed"`` — always check the state,
    never infer success from the absence of a tool error.
    Hosted: a key obtained mid-session may be passed as
    ``_meta["maginary/api_key"]``.

Args:
    uuid: The UUID returned by ``generate``.
    timeout_s: Return after this many seconds even if still running.
        Default 45 stays under the 60 s per-call limit most MCP clients
        enforce; a ``timeout`` result just means "call again". Only raise
        it (e.g. for video) on clients you know allow long tool calls.

Returns:
    The terminal generation record — which includes generations that
    failed server-side: those are SUCCESSFUL tool calls returning
    ``processing_state: "failed"`` with empty ``image_urls``, so always
    check the state. On tool failure, an ``isError`` result whose
    ``error`` field is ``"timeout"`` (``message`` names the last
    observed state — the generation keeps running server-side and can be
    re-fetched with ``get_generation`` later), ``"auth"``, or
    ``"failed"``.

Returns the auto-generated password — display it to the user ONCE so they
can save it. A verification email is sent; the user must click the link
before the account can generate images.

After verification, use ``manage_api_key(action='create')`` with
``email`` + ``password`` to get an API key, then ``configure_api_key``
to activate it.

Args:
    email: The user's email address.

Returns:
    Dict with ``email``, ``password``, and ``message``. On failure, an
    ``isError`` result — e.g. ``error: "already_exists"`` (email taken:
    ask the user for their password or a different email),
    ``"rate_limited"``, or ``"failed"``.

Use this after ``create_account`` to poll whether the user has clicked the
verification link. Pass ``email`` + ``password`` (from ``create_account``)
for Basic auth, or omit both to use the configured API key.

Args:
    email: Account email (for Basic auth).
    password: Account password (for Basic auth).

Returns:
    Dict with ``verified`` (bool), ``email``, ``api_key_count``,
    ``credits_remaining``, ``uploads_remaining``.

Auth: pass ``email`` + ``password`` for Basic auth (onboarding), or omit
both to use the configured API key (normal operation).

Args:
    action: One of ``create``, ``list``, ``revoke``.
    name: Key name (required for ``create``).
    key_prefix: 8-char prefix of the key to revoke (required for ``revoke``).
    email: Account email (for Basic auth).
    password: Account password (for Basic auth).

Returns:
    For ``create``: dict with ``raw_key`` (the full key — show once, then
    use ``configure_api_key`` to activate it), ``key_prefix``, ``name``.
    For ``list``: dict with ``keys`` array.
    For ``revoke``: success/error message.

Call this after ``manage_api_key(action='create')`` returns a ``raw_key``.
On a local server the key is saved to ``~/.config/maginary/api_key``
(chmod 600) and survives restarts. On the hosted server
(mcp.maginary.ai) nothing can be stored — auth is per-request: the
response will say ``persisted: false`` and the key must be sent as an
``Authorization: Bearer <key>`` header on every request (set it in the
MCP client's connection config).

Args:
    api_key: The full API key string returned by ``manage_api_key``.

Returns:
    Confirmation dict.

No authentication required. Use this to present purchase options to the
user. The ``novice_pack`` ($10, 150 credits) is the recommended starting
point.

Returns:
    Dict with ``count`` and ``products`` — each product carries ``id``,
    ``short_name``, ``title``, ``description``, ``price_cents``,
    ``credits``, ``uploads``, ``is_subscription``. (The backend sends a
    bare array; it is wrapped here because FastMCP validates tool output
    against the dict annotation and rejects a top-level list.)

Returns a ``checkout_url`` — the user must open it in a browser to
complete payment. After payment, credits are provisioned automatically
via webhook.

If the agent has a USDC wallet, skip this entirely — just call
``generate`` and the x402 protocol handles payment on-chain.

Args:
    product_id: Product ID from ``get_products``.
    email: Account email (for Basic auth during onboarding).
    password: Account password (for Basic auth during onboarding).

Returns:
    Dict with ``checkout_url``. On failure, an ``isError`` result — e.g.
    ``error: "email_not_verified"`` until the user clicks the
    verification link, or ``"auth"`` / ``"failed"``.

Args:
    email: Account email (for Basic auth).
    password: Account password (for Basic auth).

Returns:
    Dict with ``credits_remaining`` and ``uploads_remaining``.