{
  "schemaVersion": 1,
  "mcpVersion": "0.1.0",
  "schemaHash": "sha256:cef4815a39301fccbfc394e2a75cca30c6182c383a8916ca95e19358a33abcc1",
  "canonicalToolCount": 386,
  "compatibilityAliasCount": 18,
  "groups": [
    {
      "id": "account-and-reporting",
      "label": "Account usage & reporting",
      "tools": [
        {
          "name": "puppetto_get_account_action_handoff",
          "title": "Get Account Action Handoff",
          "description": "Return a trusted Puppetto native billing, payout, capability or personal-account entry point and local return state. Organization admin required for organization financial actions; personal actions require an OAuth user. performed=false means no payment, redemption, cancellation, deletion, credential change or sign-out occurred. Native completion remains unverified."
        },
        {
          "name": "puppetto_get_account_balance",
          "title": "Get Account Balance",
          "description": "Read unexpired credit-lot balance and separate ledger wallet/escrow/receivable positions in credit units. Shows their agreement, expiration and provenance. Missing quota measurements remain null. This read never grants credits, posts expiry adjustments or calls a payment provider."
        },
        {
          "name": "puppetto_get_account_capabilities",
          "title": "Get Account Capabilities",
          "description": "Read live account capabilities without trusting caller-supplied roles. Distinguishes organization admin from OAuth platform super-admin; an organization key never gains platform authority through its creator. No payment, credit grant, account mutation or impersonation capability is granted."
        },
        {
          "name": "puppetto_get_account_usage",
          "title": "Get Account Usage",
          "description": "Organization-admin-only financial usage for a required half-open window up to 366 days. Separates logged credits, signed legacy transactions, debit-positive wallet ledger movement/reversals, recorded token events, paginated logs and unverified stored subscriptions. Overlapping sources are not additive. Never reads live Stripe or mutates an account."
        },
        {
          "name": "puppetto_get_reporting_summary",
          "title": "Get Reporting Summary",
          "description": "Read stored post/campaign reporting for a required UTC half-open window (maximum 366 days). Reports confirmation-time cadence, normalized platform coverage, provider outcomes, goal definitions, and cumulative engagement with source, freshness, target coverage and null when unavailable. Confirmation time is not provider publication time; no analytics refresh or external request occurs. Large cohorts require a narrower window."
        }
      ]
    },
    {
      "id": "ad-schedule",
      "label": "ad schedule",
      "tools": [
        {
          "name": "puppetto_cancel_ad_schedule_item",
          "title": "Cancel Ad Schedule Item",
          "description": "Cancel local scheduled work at its current revision. A claimant or organization administrator may cancel claimed work. No remote ad, browser, publishing job, payment or budget is cancelled; in-flight external work may still require reconciliation."
        },
        {
          "name": "puppetto_claim_ad_schedule_item",
          "title": "Claim Ad Schedule Item",
          "description": "Exclusively claim a due planned task using current revision and a durable retry key. Claim ownership comes from verified credential identity. Claims have no automatic expiry or requeue and do not execute a browser action. Read the returned revision and claim ID before recording an outcome."
        },
        {
          "name": "puppetto_create_ad_schedule_item",
          "title": "Create Ad Schedule Item",
          "description": "Save one organization-scoped ad task with a due time, destination and native campaign/draft/asset references. This is a computer-use work schedule, not an organic publishing job. Makes no provider call and grants no spend or account authorization."
        },
        {
          "name": "puppetto_get_ad_schedule_handoff",
          "title": "Get Ad Schedule Handoff",
          "description": "Read current ad task, native references and computer-use instructions for the human-authorized account. Prefer a sufficient connected service tool, otherwise use available computer tools within existing authorization. Handoff starts no browser; stored instructions do not override human or agent rules. Outcome evidence is agent-reported, not provider-verified."
        },
        {
          "name": "puppetto_list_ad_schedule",
          "title": "List Ad Schedule",
          "description": "List native ad schedule items by due cutoff, campaign and status with cursor pagination. With dueBefore and no status, returns planned work only. Agents or their orchestrator poll this read; it runs no recurring dispatcher or external action."
        },
        {
          "name": "puppetto_record_ad_schedule_outcome",
          "title": "Record Ad Schedule Outcome",
          "description": "Persist the exact claimant’s observed result and evidence. Completion requires evidence and remains providerVerified=false. Unknown external outcomes are blocked for reconciliation, not requeued. The claimant may reconcile blocked work at its current revision. Never repeats an external click or asserts an independently verified ad result."
        }
      ]
    },
    {
      "id": "agent-email",
      "label": "Agent email & intake",
      "tools": [
        {
          "name": "puppetto_create_agent_email_inbox",
          "title": "Create Agent Email Inbox",
          "description": "Provision an AgentMail inbox for the organization and optionally bind it to a workflow and character. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_delete_agent_email_inbox",
          "title": "Delete Agent Email Inbox",
          "description": "Delete an AgentMail inbox from AgentMail and Puppetto. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_get_agent_email_inbox",
          "title": "Get Agent Email Inbox",
          "description": "Get a single AgentMail inbox by row ID for this organization. Secrets are never returned."
        },
        {
          "name": "puppetto_get_agent_email_message",
          "title": "Get Agent Email Message",
          "description": "Get a single AgentMail message from an organization inbox. Requires a member- or admin-linked organization API key."
        },
        {
          "name": "puppetto_ingest_agent_email",
          "title": "Ingest Agent Email",
          "description": "Read one existing provider message from a verified organization inbox and persist its body, provenance and attachment metadata once. Reuses existing AgentMail getMessage; repeated keys or duplicate provider message IDs do not create duplicate intakes. Attachment bytes/download/storage are unavailable. Does not provision inboxes, consume webhook deliveries, send mail, or run workflows."
        },
        {
          "name": "puppetto_inspect_agent_email_intake",
          "title": "Inspect Agent Email Intake",
          "description": "Read a persisted scoped email intake, attachment IDs/filenames/MIME/sizes, pinned workflow route, failure code and execution pointer. Attachment bytes require a native/provider handoff; this release does not claim attachment ingestion."
        },
        {
          "name": "puppetto_list_agent_email_inboxes",
          "title": "List Agent Email Inboxes",
          "description": "List AgentMail inboxes provisioned for this organization, including workflow and character bindings. Secrets are never returned."
        },
        {
          "name": "puppetto_list_agent_email_intakes",
          "title": "List Agent Email Intakes",
          "description": "Page persisted organization-scoped email intake records. Existing inbox/message listing and retrieval tools remain available; this list reports durable intake state and recovery pointers."
        },
        {
          "name": "puppetto_list_agent_email_messages",
          "title": "List Agent Email Messages",
          "description": "List recent messages for an AgentMail inbox. Requires a member- or admin-linked organization API key."
        },
        {
          "name": "puppetto_retry_agent_email_intake",
          "title": "Retry Agent Email Intake",
          "description": "Recover a failed or unresolved test-mode email route using its original pinned workflow request and stable key. If a workflow committed before a timeout, recover that same execution. Review current intake/revision first; this command does not redownload attachments or retry provider email delivery."
        },
        {
          "name": "puppetto_route_agent_email_intake",
          "title": "Route Agent Email Intake",
          "description": "Commit a test-mode route intent using the inbox current workflow binding, pin its graph revision and stored message/attachment metadata, then create one execution through the canonical workflow service. No paid generation, publication or outbound email occurs in test mode. Read intake for the resulting execution ID. Existing automatic native webhook dispatch remains a separate legacy path without these recovery guarantees."
        },
        {
          "name": "puppetto_send_agent_email_message",
          "title": "Send Agent Email Message",
          "description": "Send a plain-text email from an AgentMail inbox. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_update_agent_email_inbox",
          "title": "Update Agent Email Inbox",
          "description": "Update an AgentMail inbox internal key, display name, workflow binding, or character binding. Requires an admin-linked organization API key."
        }
      ]
    },
    {
      "id": "assets",
      "label": "Assets & media generation",
      "tools": [
        {
          "name": "puppetto_add_post_assets",
          "title": "Add Post Assets",
          "description": "Attach existing organization assets to a post and update final asset IDs."
        },
        {
          "name": "puppetto_archive_asset",
          "title": "Archive Asset",
          "description": "Archive media while preserving stored bytes and all story/post links. Linked media reads unavailable until restored. Resolve or cancel active generation first; archival does not stop provider work."
        },
        {
          "name": "puppetto_begin_asset_upload",
          "title": "Begin Asset Upload",
          "description": "Create one durable organization-scoped upload intent and asset placeholder. Supply the exact byte size, MIME type, and lowercase SHA-256 hex digest. The intent expires in one hour. Read its signed URL with puppetto_get_asset_upload, PUT once, then finalize. Same input/key returns the same asset; no file is uploaded by this command."
        },
        {
          "name": "puppetto_cancel_asset_job",
          "title": "Cancel Asset Job",
          "description": "Cancel a durable queued job before the worker claims it. Confirmed cancellation prevents provider submission for that attempt. Running and legacy provider cancellation is unsupported; it does not promise stopped work or a refund."
        },
        {
          "name": "puppetto_chain_asset_production",
          "title": "Chain Asset Production",
          "description": "Start a new asset production run using an existing completed or source asset as an upstream input. Use this to chain simple assets into complex scene, campaign, product, or post assets."
        },
        {
          "name": "puppetto_create_asset_folder",
          "title": "Create Asset Folder",
          "description": "Create an empty organization-scoped asset folder. Repeated creation of the same path returns its existing folder ID. Place assets in it with puppetto_update_asset_metadata. No storage objects are moved."
        },
        {
          "name": "puppetto_create_private_asset_share",
          "title": "Create Private Asset Share",
          "description": "Prepare a private share from completed assets in the credential-selected organization. Requires current owner/admin access, including when using an organization API key. Copies up to 10 files with a combined maximum of 100 MiB into private snapshots: JPEG/PNG/WebP/GIF images, MP4/WebM video, and MP3/MP4/WAV/OGG/FLAC/AAC audio. Copies run inline without a generation job or credit spend. Returns the creator share DTO with preparation status. The recipient must authenticate and explicitly accept a native organization member invitation, which grants normal member access to the organization. No outreach or message is sent. The current credential-selected organization and any existing organization-bound token remain unchanged. The invitation URL contains a secret in its fragment and is returned only on the first successful create or reissue response; identical retries and reads return inviteUrl: null. Keep it private. Read the current revision and use a new idempotencyKey to explicitly reissue a lost link. Retry identical arguments with the same idempotencyKey to recover preparation."
        },
        {
          "name": "puppetto_estimate_asset_generation",
          "title": "Estimate Asset Generation",
          "description": "Estimate credits for generating an asset with a supported provider before queueing a job. Pass provider-specific customizations in params; options remains supported as a legacy alias."
        },
        {
          "name": "puppetto_finalize_asset_upload",
          "title": "Finalize Asset Upload",
          "description": "Finalize one scoped upload after verifying storage byte size, MIME type, and SHA-256 checksum. The asset becomes ready atomically with its durable operation receipt. Retry the same input/key after a transport failure."
        },
        {
          "name": "puppetto_generate_asset",
          "title": "Generate Asset",
          "description": "Queue a Puppetto asset-generation job through any supported asset-generation integration. Use puppetto_list_integration_capabilities or puppetto_list_asset_generation_integrations to discover provider models, controls, and defaults, then pass provider-specific customizations in params; options remains supported as a legacy alias. Supports images, speech/audio, music, sound effects, video, lipsync, 3D, source-asset edits, and optional character/post links. Returns job.id/assetId for async polling with puppetto_list_asset_generation_jobs. For character profile pictures, pass characterId with assetType \"image\" and params.setAsProfileImage true. For character narration, assign a character voiceId first, then pass characterId with assetType \"speech\"; MCP resolves the provider voice ID before queueing."
        },
        {
          "name": "puppetto_get_asset",
          "title": "Get Asset",
          "description": "Get an asset by ID for the authorized organization."
        },
        {
          "name": "puppetto_get_asset_job",
          "title": "Get Asset Job",
          "description": "Read an asset generation job directly by its asset/job ID, including durable checkpoint, job revision, provider reference when recorded, safe retry status, and actual cancellation support. Legacy jobs without submission checkpoints cannot promise safe paid retry."
        },
        {
          "name": "puppetto_get_asset_production_graph",
          "title": "Get Asset Production Graph",
          "description": "Return a canvas-ready asset production graph for a production run, asset, story, or script node. Nodes include production runs, workflow executions, and linked source/target assets."
        },
        {
          "name": "puppetto_get_asset_upload",
          "title": "Get Asset Upload",
          "description": "Read a short-lived scoped PUT URL for a pending upload. Send every returned header exactly. Storage enforces SHA-256 and prevents overwrite. URLs are credentials; they are never persisted in durable receipts. Finalized or expired intents do not issue URLs."
        },
        {
          "name": "puppetto_get_private_asset_share",
          "title": "Get Private Asset Share",
          "description": "Read the creator DTO and current preparation status of a private share in the credential-selected organization. Requires current owner/admin access, including an organization API key. Read-only; inviteUrl is always null. The invitation URL contains a secret in its fragment and is returned only on the first successful create or reissue response; identical retries and reads return inviteUrl: null. Keep it private. Read the current revision and use a new idempotencyKey to explicitly reissue a lost link. The recipient must authenticate and explicitly accept a native organization member invitation, which grants normal member access to the organization. No outreach or message is sent. The current credential-selected organization and any existing organization-bound token remain unchanged."
        },
        {
          "name": "puppetto_inspect_asset_readiness",
          "title": "Inspect Asset Readiness",
          "description": "Read readiness for up to 100 asset IDs in the verified organization. Missing, archived, and foreign IDs report unavailable. This read does not grant linking permission or generate media."
        },
        {
          "name": "puppetto_list_asset_blueprints",
          "title": "List Asset Blueprints",
          "description": "List asset-first production blueprints. Each blueprint describes the target end-result asset, required inputs, expected outputs, accepted upstream assets, and suggested downstream chains."
        },
        {
          "name": "puppetto_list_asset_folders",
          "title": "List Asset Folders",
          "description": "List explicit folders and folders inferred from active asset paths, with direct asset counts. complete:false means the 1000-folder limit was reached. Move an asset through puppetto_update_asset_metadata."
        },
        {
          "name": "puppetto_list_asset_generation_integrations",
          "title": "List Asset Generation Integrations",
          "description": "List asset-generation providers available to Puppetto MCP, optionally filtered by asset type. Includes capabilities, asset types, model defaults, controls, and whether the organization has a connected integration."
        },
        {
          "name": "puppetto_list_asset_generation_jobs",
          "title": "List Asset Generation Jobs",
          "description": "Bulk query async asset-generation job status. Pass jobIds returned by puppetto_generate_asset, or omit IDs to list recent pending/generating jobs. Use statuses/status to include completed or failed jobs."
        },
        {
          "name": "puppetto_list_assets",
          "title": "List Assets",
          "description": "List assets for the authorized organization."
        },
        {
          "name": "puppetto_list_in_progress_assets",
          "title": "List In Progress Assets",
          "description": "List generating or pending assets for the authorized organization. Prefer puppetto_list_asset_generation_jobs when polling specific jobs returned by puppetto_generate_asset."
        },
        {
          "name": "puppetto_list_selection_source_assets",
          "title": "List Selection Source Assets",
          "description": "list registerable assets for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_list_website_asset_import_jobs",
          "title": "List Website Asset Import Jobs",
          "description": "List website asset scrape/import jobs for the organization."
        },
        {
          "name": "puppetto_plan_asset_production",
          "title": "Plan Asset Production",
          "description": "Plan an asset-first production run before queueing work. Returns missing requirements, resolution guidance, expected outputs, and downstream workflow-chain suggestions for the requested blueprint."
        },
        {
          "name": "puppetto_read_asset",
          "title": "Read Asset",
          "description": "Read asset metadata, current revision, archive state, and readiness, including an archived asset in this organization. Existing links remain identified when media becomes unavailable. Legacy puppetto_get_asset remains available."
        },
        {
          "name": "puppetto_reissue_private_asset_share",
          "title": "Reissue Private Asset Share",
          "description": "Explicitly replace the invitation of a ready or revoked private share using its current expectedRevision and a new idempotencyKey. Requires current owner/admin access in the credential-selected organization, including an organization API key. Invalidates the previous invitation and returns the creator DTO. Existing private copies are reused; no queue or credit spend. The invitation URL contains a secret in its fragment and is returned only on the first successful create or reissue response; identical retries and reads return inviteUrl: null. Keep it private. Read the current revision and use a new idempotencyKey to explicitly reissue a lost link. The recipient must authenticate and explicitly accept a native organization member invitation, which grants normal member access to the organization. No outreach or message is sent. The current credential-selected organization and any existing organization-bound token remain unchanged."
        },
        {
          "name": "puppetto_remove_post_assets",
          "title": "Remove Post Assets",
          "description": "Detach one or more assets from a post and reconcile final asset IDs. Use this to clean up failed, empty, or accidental placeholder assets attached during generation attempts."
        },
        {
          "name": "puppetto_request_asset_generation",
          "title": "Request Asset Generation",
          "description": "Create a durable idempotent generation request before sending the existing provider queue. Reuses current provider/model/voice validation and estimates. maxEstimatedCredits bounds the accepted estimate, not final provider usage. Credits are checked now and charged by the existing worker on completed output; no reservation/refund or provider exactly-once guarantee. Same input/key recovers the same job after timeout; unknown provider outcomes require reconciliation. Supports the same providers and source/character/post links as legacy generation."
        },
        {
          "name": "puppetto_restore_asset",
          "title": "Restore Asset",
          "description": "Restore an archived asset without changing its links, file bytes, or provider job. Failed generation remains failed. This cannot recover physically deleted bytes."
        },
        {
          "name": "puppetto_retry_asset_job",
          "title": "Retry Asset Job",
          "description": "Retry only a known pre-provider failure, or resume durable saved output settlement without a second provider call/debit. Commits a stable retry intent before sending the existing generation queue payload. Dispatch pending/unknown is recovered by repeating the exact command/key. Unknown provider outcomes require reconciliation and reject automatic paid resubmission. No refund or provider exactly-once guarantee."
        },
        {
          "name": "puppetto_revoke_private_asset_share",
          "title": "Revoke Private Asset Share",
          "description": "Revoke a private share invitation using its current expectedRevision and an idempotencyKey. Requires current owner/admin access in the credential-selected organization, including an organization API key. Prevents future invitation acceptance; existing organization memberships remain. Preserves private asset copies and returns the creator DTO with inviteUrl: null. No queue or credit spend. The recipient must authenticate and explicitly accept a native organization member invitation, which grants normal member access to the organization. No outreach or message is sent. The current credential-selected organization and any existing organization-bound token remain unchanged."
        },
        {
          "name": "puppetto_search_assets",
          "title": "Search Assets",
          "description": "Search this organization by display name or user metadata, exact folder, and all requested tags. Results page by stable asset UUID. Set includeArchived to inspect recoverable archives. Search does not expose foreign assets."
        },
        {
          "name": "puppetto_start_asset_production",
          "title": "Start Asset Production",
          "description": "Create an asset production run around a target end-result asset. If requirements are missing, the run is created as blocked with actionable requirement guidance; if a workflowId is supplied, an execution record is created for the run."
        },
        {
          "name": "puppetto_update_asset_metadata",
          "title": "Update Asset Metadata",
          "description": "Update display name, tags, folder, or user metadata with a revision check. Clear displayName with null or tags with []. Metadata merges into the userMetadata namespace and preserves generation/provider fields. Folder paths are absolute. Does not change stored bytes or existing links."
        }
      ]
    },
    {
      "id": "campaigns",
      "label": "Campaigns & templates",
      "tools": [
        {
          "name": "puppetto_adopt_campaign_template",
          "title": "Adopt Campaign Template",
          "description": "Adopt a discoverable campaign template with its real inherited description, color, dates, content guidance, goals, and poster defaults. Existing adoption is reused; repeated requests create no duplicate campaign."
        },
        {
          "name": "puppetto_create_campaign",
          "title": "Create Campaign",
          "description": "Create an organization campaign. Requires a member- or admin-linked organization API key."
        },
        {
          "name": "puppetto_create_campaign_goal",
          "title": "Create Campaign Goal",
          "description": "Create a goal for an organization campaign. Requires a member- or admin-linked organization API key."
        },
        {
          "name": "puppetto_create_campaign_template",
          "title": "Create Campaign Template",
          "description": "Create an organization-owned campaign template. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_create_campaign_v2",
          "title": "Create Campaign V2",
          "description": "Create a draft campaign and optional goals atomically with a durable idempotency receipt. Dates are optional and nullable."
        },
        {
          "name": "puppetto_discover_public_campaign_templates",
          "title": "Discover Public Campaign Templates",
          "description": "Discover published public campaign templates and their actual content guidance, default goals, and calendar metadata. Use template ID to adopt."
        },
        {
          "name": "puppetto_duplicate_campaign",
          "title": "Duplicate Campaign",
          "description": "Duplicate a campaign as a draft with goals by default and optional post/story links. Campaign and goal dates are cleared; existing linked posts retain their own schedules. Never creates or clones publishing jobs. Uses source revision and a durable retry key."
        },
        {
          "name": "puppetto_get_campaign",
          "title": "Get Campaign",
          "description": "Get an organization campaign with goals and post count by campaign ID."
        },
        {
          "name": "puppetto_get_campaign_bundle",
          "title": "Get Campaign Bundle",
          "description": "Inspect campaign posts with campaignPostId/role/scheduledAt, goals and authoritative progress availability, explicit story links, asset relationships, and post readiness. Each child page has a separate cursor. Campaign status preserves post schedules and jobs."
        },
        {
          "name": "puppetto_link_post_to_campaign",
          "title": "Link Post To Campaign",
          "description": "Link a post to an organization campaign. Requires a member- or admin-linked organization API key."
        },
        {
          "name": "puppetto_list_campaign_templates",
          "title": "List Campaign Templates",
          "description": "List discoverable campaign templates for the authorized organization."
        },
        {
          "name": "puppetto_list_campaigns",
          "title": "List Campaigns",
          "description": "List organization campaigns with goals and post counts."
        },
        {
          "name": "puppetto_list_campaigns_page",
          "title": "List Campaigns Page",
          "description": "List authorized campaigns with command revisions and stable UUID cursors. Reads do not seed or create campaigns."
        },
        {
          "name": "puppetto_mutate_campaign",
          "title": "Mutate Campaign",
          "description": "Revisioned atomic campaign command: update (explicit null clears nullable fields), transition, upsert/remove goal, link/unlink post or story, explicit repeatable story-link import, or set/clear a promotional asset. Unlink uses IDs from the bundle. Archiving requires pendingPublishingPolicy=\"preserve\" and leaves post publishing jobs active until separately canceled."
        },
        {
          "name": "puppetto_publish_campaign_template",
          "title": "Publish Campaign Template",
          "description": "Publish an organization-owned campaign template. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_unlink_post_from_campaign",
          "title": "Unlink Post From Campaign",
          "description": "Unlink a post from a campaign using the campaign-post link ID. Requires a member- or admin-linked organization API key."
        },
        {
          "name": "puppetto_update_campaign",
          "title": "Update Campaign",
          "description": "Update an organization campaign. Requires a member- or admin-linked organization API key."
        },
        {
          "name": "puppetto_update_campaign_goal",
          "title": "Update Campaign Goal",
          "description": "Update a campaign goal. Requires a member- or admin-linked organization API key."
        }
      ]
    },
    {
      "id": "characters",
      "label": "Characters & voices",
      "tools": [
        {
          "name": "puppetto_adopt_character_template",
          "title": "Adopt Character Template",
          "description": "Create a character from an exact advertised native template version using existing profile commands. Saves version zero and a durable receipt. No generation, voice import, image upload or paid provider action occurs."
        },
        {
          "name": "puppetto_archive_character",
          "title": "Archive Character",
          "description": "Archive without deleting profiles, versions, media or linked cast roles. Existing linked story generation requires restore. The response counts affected following and pinned roles; their IDs and pins remain unchanged."
        },
        {
          "name": "puppetto_assign_character_media",
          "title": "Assign Character Media",
          "description": "Assign or clear an existing usable organization voice record and ready organization image asset. Rejects foreign, archived, unavailable or non-image media. Creates a new version so explicit cast pins retain their old media."
        },
        {
          "name": "puppetto_create_starter_character",
          "title": "Create Starter Character",
          "description": "Create a real starter character with a versioned profile using concise notes and safe defaults. Requires a member- or admin-linked organization API key."
        },
        {
          "name": "puppetto_get_character",
          "title": "Get Character",
          "description": "Get a character by ID for the authorized organization."
        },
        {
          "name": "puppetto_inspect_character_version",
          "title": "Inspect Character Version",
          "description": "Read a selected character version, its public profile and media IDs, latest version, revision and cast effects. Version zero is valid. Secret settings are excluded. Archived snapshots remain inspectable."
        },
        {
          "name": "puppetto_list_character_assets",
          "title": "List Character Assets",
          "description": "List assets linked to a character, optionally filtered by assetType such as image, speech, audio, video, or lipsync."
        },
        {
          "name": "puppetto_list_character_role_effects",
          "title": "List Character Role Effects",
          "description": "Page linked story cast roles and their effective selected versions. Explicit pins remain fixed when the character changes. Use puppetto_save_story_cast_role with the story revision to pin or unpin a role."
        },
        {
          "name": "puppetto_list_character_templates",
          "title": "List Character Templates",
          "description": "List the native character templates and exact versions accepted for adoption. Suggested template media are not provider voice assignments or uploaded image assets."
        },
        {
          "name": "puppetto_list_character_versions",
          "title": "List Character Versions",
          "description": "Page available character versions newest first. An absent snapshot denotes a legacy storage-backed version. Foreign, deleted and missing versions are not returned."
        },
        {
          "name": "puppetto_list_character_voices",
          "title": "List Character Voices",
          "description": "List usable organization voice records that can be assigned to characters for speech generation. Use the returned id as the character voiceId; providerVoiceId is the downstream speech-provider ID. Set includeUnusable true only to diagnose dirty records that need ElevenLabs re-import/sync."
        },
        {
          "name": "puppetto_list_characters",
          "title": "List Characters",
          "description": "List characters for the authorized organization with their current profile version."
        },
        {
          "name": "puppetto_restore_character",
          "title": "Restore Character",
          "description": "Restore an archived character and retain all version pins and linked cast roles. Existing voice and media availability are checked separately when preparing generation."
        },
        {
          "name": "puppetto_search_characters",
          "title": "Search Characters",
          "description": "Page character lifecycle records, including archived records when requested. Use each revision for lifecycle commands and inspect a selected immutable profile version."
        },
        {
          "name": "puppetto_update_character_profile",
          "title": "Update Character Profile",
          "description": "Update a character name, system prompt, legacy voice model, assigned organization voice, profile image URL/storage path, or profile image from a completed image asset."
        },
        {
          "name": "puppetto_update_versioned_character_profile",
          "title": "Update Versioned Character Profile",
          "description": "Update bounded public profile fields and create the next immutable version using existing profile commands. Unpinned cast follows the latest version; explicit pins retain their version and snapshot. Secret configuration uses the native UI."
        }
      ]
    },
    {
      "id": "commerce",
      "label": "Shops, products & print",
      "tools": [
        {
          "name": "puppetto_add_shop_collection_item",
          "title": "Add Shop Collection Item",
          "description": "Add a product template to a shop/store collection. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_archive_print_plate",
          "title": "Archive Print Plate",
          "description": "Soft delete a scoped print_plate with its revision while preserving relationships and durable receipts. Does not remove provider output, cancel orders, or publish."
        },
        {
          "name": "puppetto_archive_print_plate_artwork",
          "title": "Archive Print Plate Artwork",
          "description": "Soft delete a scoped print_plate_artwork with its revision while preserving relationships and durable receipts. Does not remove provider output, cancel orders, or publish."
        },
        {
          "name": "puppetto_archive_product_price",
          "title": "Archive Product Price",
          "description": "Soft delete a scoped product_price with its revision while preserving relationships and durable receipts. Does not remove provider output, cancel orders, or publish."
        },
        {
          "name": "puppetto_archive_product_template",
          "title": "Archive Product Template",
          "description": "Soft delete a scoped product_template with its revision while preserving relationships and durable receipts. Does not remove provider output, cancel orders, or publish."
        },
        {
          "name": "puppetto_archive_product_variant",
          "title": "Archive Product Variant",
          "description": "Soft delete a scoped product_variant with its revision while preserving relationships and durable receipts. Does not remove provider output, cancel orders, or publish."
        },
        {
          "name": "puppetto_archive_shop",
          "title": "Archive Shop",
          "description": "Soft delete a scoped shop with its revision while preserving relationships and durable receipts. Does not remove provider output, cancel orders, or publish."
        },
        {
          "name": "puppetto_archive_shop_collection",
          "title": "Archive Shop Collection",
          "description": "Soft delete a scoped shop_collection with its revision while preserving relationships and durable receipts. Does not remove provider output, cancel orders, or publish."
        },
        {
          "name": "puppetto_archive_shop_collection_item",
          "title": "Archive Shop Collection Item",
          "description": "Soft delete a scoped shop_collection_item with its revision while preserving relationships and durable receipts. Does not remove provider output, cancel orders, or publish."
        },
        {
          "name": "puppetto_create_draft_product_template",
          "title": "Create Draft Product Template",
          "description": "Create a draft shop product template for the authorized organization. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_create_draft_shop",
          "title": "Create Draft Shop",
          "description": "Create a draft shop/store for the authorized organization. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_create_print_plate",
          "title": "Create Print Plate",
          "description": "Create a draft/scoped print_plate through the existing product command. Returns its ID, revision, fields, and durable operation receipt. No publication, email, provider submission, or paid generation. Parent relationships and referenced artwork must be available in this organization."
        },
        {
          "name": "puppetto_create_print_plate_artwork",
          "title": "Create Print Plate Artwork",
          "description": "Create a draft/scoped print_plate_artwork through the existing product command. Returns its ID, revision, fields, and durable operation receipt. No publication, email, provider submission, or paid generation. Parent relationships and referenced artwork must be available in this organization."
        },
        {
          "name": "puppetto_create_product_price",
          "title": "Create Product Price",
          "description": "Create a draft/scoped product_price through the existing product command. Returns its ID, revision, fields, and durable operation receipt. No publication, email, provider submission, or paid generation. Parent relationships and referenced artwork must be available in this organization."
        },
        {
          "name": "puppetto_create_product_template",
          "title": "Create Product Template",
          "description": "Create a draft/scoped product_template through the existing product command. Returns its ID, revision, fields, and durable operation receipt. No publication, email, provider submission, or paid generation. Parent relationships and referenced artwork must be available in this organization."
        },
        {
          "name": "puppetto_create_product_variant",
          "title": "Create Product Variant",
          "description": "Create a draft/scoped product_variant through the existing product command. Returns its ID, revision, fields, and durable operation receipt. No publication, email, provider submission, or paid generation. Parent relationships and referenced artwork must be available in this organization."
        },
        {
          "name": "puppetto_create_shop",
          "title": "Create Shop",
          "description": "Create a draft/scoped shop through the existing product command. Returns its ID, revision, fields, and durable operation receipt. No publication, email, provider submission, or paid generation. Parent relationships and referenced artwork must be available in this organization."
        },
        {
          "name": "puppetto_create_shop_automation_job",
          "title": "Create Shop Automation Job",
          "description": "Create a pending ecommerce/shop automation job from a shop, taste profile, character, and flexible job input. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_create_shop_collection",
          "title": "Create Shop Collection",
          "description": "Create a draft collection for a shop/store. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_create_shop_collection_item",
          "title": "Create Shop Collection Item",
          "description": "Create a draft/scoped shop_collection_item through the existing product command. Returns its ID, revision, fields, and durable operation receipt. No publication, email, provider submission, or paid generation. Parent relationships and referenced artwork must be available in this organization."
        },
        {
          "name": "puppetto_create_shop_collection_v2",
          "title": "Create Shop Collection V2",
          "description": "Create a draft/scoped shop_collection through the existing product command. Returns its ID, revision, fields, and durable operation receipt. No publication, email, provider submission, or paid generation. Parent relationships and referenced artwork must be available in this organization."
        },
        {
          "name": "puppetto_create_shop_taste_profile",
          "title": "Create Shop Taste Profile",
          "description": "Create a shop taste profile for ecommerce asset generation defaults. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_create_usps_label",
          "title": "Create Usps Label",
          "description": "Create a private 4x6 USPS PDF for all manual items in one paid US domestic order. Requires measured packed weight in ounces/dimensions in inches, sender address, and the environment just read from get_usps_shipping. Production charges the organization USPS EPS account; obtain human authorization before setting confirmPostageCharge=true. Test labels buy no postage and cannot ship. A created label is reused, and concurrent web/MCP requests share a durable purchase lock. Never automatically retry an unknown creating/review outcome. Does not mark shipped."
        },
        {
          "name": "puppetto_download_usps_label",
          "title": "Download Usps Label",
          "description": "Retrieve the private USPS PDF, or recover it from the saved carrier response, without buying postage or contacting USPS. Select test or production explicitly. Returns application/pdf bytes as base64 and a filename; decode base64 into a local file for printing. Labels contain private addresses; keep them private. A saved response that cannot be parsed needs operator review, never repurchase."
        },
        {
          "name": "puppetto_get_commerce_cart_bundle",
          "title": "Get Commerce Cart Bundle",
          "description": "Inspect cart lines and catalog-only price diagnostics for this page. Current catalog prices are not a checkout quote; legacy checkout currency/effective-date pricing requires separate verification."
        },
        {
          "name": "puppetto_get_commerce_fulfillment",
          "title": "Get Commerce Fulfillment",
          "description": "Read a durable fulfillment intent and checkpointed provider identity after timeout/restart. This read makes no provider request and does not assert refunds."
        },
        {
          "name": "puppetto_get_commerce_order_bundle",
          "title": "Get Commerce Order Bundle",
          "description": "Inspect an existing order, paginated line IDs and immutable prices, separate fulfillment/provider/shipment/cancellation/refund evidence, and operator recovery handoffs."
        },
        {
          "name": "puppetto_get_product_template",
          "title": "Get Product Template",
          "description": "Get a shop product template with variants and pricing for the authorized organization."
        },
        {
          "name": "puppetto_get_shop",
          "title": "Get Shop",
          "description": "Get a shop/store by ID for the authorized organization."
        },
        {
          "name": "puppetto_get_shop_catalogue",
          "title": "Share the full storefront catalogue",
          "description": "Return the public JSON catalogue URL and counts for one published shop in the connected organization. Fetch catalogueUrl to receive the complete published catalogue with collections, descriptions, galleries, variants, options, effective retail prices by currency, cached stock timestamps and product links. No product pagination or truncation. Draft/unpublished shops have no public feed. Internal costs, markup rules, private metadata and digital fulfillment files are excluded. This read does not publish a shop or change checkout."
        },
        {
          "name": "puppetto_get_shop_collection",
          "title": "Get Shop Collection",
          "description": "Get a shop/store collection and its product items for the authorized organization."
        },
        {
          "name": "puppetto_get_shop_order",
          "title": "Get Shop Order",
          "description": "Get an ecommerce shop order with line items. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_get_shop_website_import_job",
          "title": "Get Shop Website Import Job",
          "description": "Get a create-shop-from-URL import job for the authorized organization."
        },
        {
          "name": "puppetto_get_usps_shipping",
          "title": "Get Usps Shipping",
          "description": "Inspect manual shipment eligibility, checkout delivery address, supported services, connected USPS environment and saved label status for an existing paid order. Credentials and PDF bytes are never returned by this read. Use list_commerce_orders/get_commerce_order_bundle to discover orders. One US domestic package covers all manual items; mixed-order provider items remain separate."
        },
        {
          "name": "puppetto_inspect_catalog_readiness",
          "title": "Inspect Catalog Readiness",
          "description": "Inspect up to 100 products linked to a shop, active variants, effective currency-specific resolved prices, published collection membership, and artwork readiness. Missing/foreign products and missing prices are blockers; zero is a valid price. This preparation report excludes checkout/payment/provider readiness and does not publish."
        },
        {
          "name": "puppetto_inspect_commerce_launch_readiness",
          "title": "Inspect Commerce Launch Readiness",
          "description": "Return catalog, pricing provenance and configured fulfillment diagnostics. Catalog readiness does not prove storefront checkout, payment, tax or shipping readiness; unresolved checks keep overall ready=false."
        },
        {
          "name": "puppetto_list_commerce_carts",
          "title": "List Commerce Carts",
          "description": "Inspect server carts by read-derived cart IDs without exposing shopper client-cart keys."
        },
        {
          "name": "puppetto_list_commerce_orders",
          "title": "List Commerce Orders",
          "description": "List existing authorized orders with stored amounts, native status and revisions. Does not create checkout, charge, or reprice orders."
        },
        {
          "name": "puppetto_list_print_plate_artworks",
          "title": "List Print Plate Artworks",
          "description": "List scoped print_plate_artwork records with UUID cursor pagination. parentId is required and identifies printPlateTemplateId. Set includeArchived to inspect preserved relationships."
        },
        {
          "name": "puppetto_list_print_plates",
          "title": "List Print Plates",
          "description": "List scoped print_plate records with UUID cursor pagination. parentId is required and identifies productTemplateId. Set includeArchived to inspect preserved relationships."
        },
        {
          "name": "puppetto_list_product_prices",
          "title": "List Product Prices",
          "description": "List scoped product_price records with UUID cursor pagination. parentId is required and identifies productTemplateVariantId. Set includeArchived to inspect preserved relationships."
        },
        {
          "name": "puppetto_list_product_templates",
          "title": "List Product Templates",
          "description": "List shop product templates for the authorized organization."
        },
        {
          "name": "puppetto_list_product_templates_v2",
          "title": "List Product Templates V2",
          "description": "List scoped product_template records with UUID cursor pagination.  Set includeArchived to inspect preserved relationships."
        },
        {
          "name": "puppetto_list_product_variants",
          "title": "List Product Variants",
          "description": "List scoped product_variant records with UUID cursor pagination. parentId is required and identifies productTemplateId. Set includeArchived to inspect preserved relationships."
        },
        {
          "name": "puppetto_list_shop_automation_jobs",
          "title": "List Shop Automation Jobs",
          "description": "List ecommerce/shop automation jobs for product, artwork, and merchandising generation. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_list_shop_collection_items",
          "title": "List Shop Collection Items",
          "description": "List product templates in a shop/store collection."
        },
        {
          "name": "puppetto_list_shop_collection_items_v2",
          "title": "List Shop Collection Items V2",
          "description": "List scoped shop_collection_item records with UUID cursor pagination. parentId is required and identifies shopCollectionId. Set includeArchived to inspect preserved relationships."
        },
        {
          "name": "puppetto_list_shop_collections",
          "title": "List Shop Collections",
          "description": "List shop/store collections for the authorized organization, optionally scoped to a shop."
        },
        {
          "name": "puppetto_list_shop_collections_v2",
          "title": "List Shop Collections V2",
          "description": "List scoped shop_collection records with UUID cursor pagination. parentId is required and identifies shopId. Set includeArchived to inspect preserved relationships."
        },
        {
          "name": "puppetto_list_shop_orders",
          "title": "List Shop Orders",
          "description": "List ecommerce shop orders for the authorized organization. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_list_shop_taste_profiles",
          "title": "List Shop Taste Profiles",
          "description": "List shop taste profiles that guide ecommerce artwork, product mockup, and merchandising generation."
        },
        {
          "name": "puppetto_list_shop_website_import_jobs",
          "title": "List Shop Website Import Jobs",
          "description": "List create-shop-from-URL import jobs for the authorized organization."
        },
        {
          "name": "puppetto_list_shops",
          "title": "List Shops",
          "description": "List shops/stores for the authorized organization."
        },
        {
          "name": "puppetto_list_shops_v2",
          "title": "List Shops V2",
          "description": "List scoped shop records with UUID cursor pagination.  Set includeArchived to inspect preserved relationships."
        },
        {
          "name": "puppetto_mark_usps_shipped",
          "title": "Mark Usps Shipped",
          "description": "After the human confirms the package was handed to USPS, mark only the label manual items shipped. Requires a created production label and confirmCarrierHandoff=true; test labels cannot ship. Updates the whole order only after all fulfillment groups shipped. Repeats are safe. Label creation alone is not carrier handoff; this does not claim delivery or refund."
        },
        {
          "name": "puppetto_match_cached_printful_catalog",
          "title": "Match Cached Printful Catalog",
          "description": "Search cached Printful product titles/type/description by literal text. Cursor is the prior product ID. cacheStatus unavailable distinguishes a missing catalog from a zero-match result. No provider sync, vector generation, or spending."
        },
        {
          "name": "puppetto_read_print_plate",
          "title": "Read Print Plate",
          "description": "Read one organization-scoped print_plate, including its revision and archive state. Foreign IDs are unavailable."
        },
        {
          "name": "puppetto_read_print_plate_artwork",
          "title": "Read Print Plate Artwork",
          "description": "Read one organization-scoped print_plate_artwork, including its revision and archive state. Foreign IDs are unavailable."
        },
        {
          "name": "puppetto_read_product_price",
          "title": "Read Product Price",
          "description": "Read one organization-scoped product_price, including its revision and archive state. Foreign IDs are unavailable."
        },
        {
          "name": "puppetto_read_product_template",
          "title": "Read Product Template",
          "description": "Read one organization-scoped product_template, including its revision and archive state. Foreign IDs are unavailable."
        },
        {
          "name": "puppetto_read_product_variant",
          "title": "Read Product Variant",
          "description": "Read one organization-scoped product_variant, including its revision and archive state. Foreign IDs are unavailable."
        },
        {
          "name": "puppetto_read_shop",
          "title": "Read Shop",
          "description": "Read one organization-scoped shop, including its revision and archive state. Foreign IDs are unavailable."
        },
        {
          "name": "puppetto_read_shop_collection",
          "title": "Read Shop Collection",
          "description": "Read one organization-scoped shop_collection, including its revision and archive state. Foreign IDs are unavailable."
        },
        {
          "name": "puppetto_read_shop_collection_item",
          "title": "Read Shop Collection Item",
          "description": "Read one organization-scoped shop_collection_item, including its revision and archive state. Foreign IDs are unavailable."
        },
        {
          "name": "puppetto_recover_commerce_fulfillment",
          "title": "Recover Commerce Fulfillment",
          "description": "Inspect a saved provider order, request supported cancellation, explicitly retry an authoritative pre-provider rejection, or repair the local submitted pointer from accepted provider evidence without submitting again. Cancellation is confirmed only by local pre-submit cancellation or actual provider evidence and never claims a buyer refund. Unknown submission/cancellation is not automatically retried."
        },
        {
          "name": "puppetto_request_commerce_fulfillment",
          "title": "Request Commerce Fulfillment",
          "description": "Request fulfillment of a single-provider physical order using the shared native paid-order path. Requires recorded payment; confirmed submission can charge the provider account. Durable claims block concurrent web/MCP duplicates. Returns receipt plus current intent; unknown outcomes require reconciliation, not automatic retries."
        },
        {
          "name": "puppetto_transition_commerce_order",
          "title": "Transition Commerce Order",
          "description": "Move a recorded paid order into internal processing using existing domain rules. Cannot assert payment, shipment, cancellation or refund evidence."
        },
        {
          "name": "puppetto_update_print_plate",
          "title": "Update Print Plate",
          "description": "Update one scoped print_plate with its current expectedRevision. Same key/input recovers the prior receipt; changed input with the same key conflicts. Shop/collection publication is a distinct operation and is unavailable through this local preparation command."
        },
        {
          "name": "puppetto_update_print_plate_artwork",
          "title": "Update Print Plate Artwork",
          "description": "Update one scoped print_plate_artwork with its current expectedRevision. Same key/input recovers the prior receipt; changed input with the same key conflicts. Shop/collection publication is a distinct operation and is unavailable through this local preparation command."
        },
        {
          "name": "puppetto_update_product_price",
          "title": "Update Product Price",
          "description": "Update one scoped product_price with its current expectedRevision. Same key/input recovers the prior receipt; changed input with the same key conflicts. Shop/collection publication is a distinct operation and is unavailable through this local preparation command."
        },
        {
          "name": "puppetto_update_product_template",
          "title": "Update Product Template",
          "description": "Update or activate a shop product template. Product templates must be active before they appear on public storefronts. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_update_product_template_v2",
          "title": "Update Product Template V2",
          "description": "Update one scoped product_template with its current expectedRevision. Same key/input recovers the prior receipt; changed input with the same key conflicts. Shop/collection publication is a distinct operation and is unavailable through this local preparation command."
        },
        {
          "name": "puppetto_update_product_variant",
          "title": "Update Product Variant",
          "description": "Update one scoped product_variant with its current expectedRevision. Same key/input recovers the prior receipt; changed input with the same key conflicts. Shop/collection publication is a distinct operation and is unavailable through this local preparation command."
        },
        {
          "name": "puppetto_update_shop",
          "title": "Update Shop",
          "description": "Update shop/store metadata or status for the authorized organization. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_update_shop_collection",
          "title": "Update Shop Collection",
          "description": "Update or publish a shop/store collection. Publish collections before expecting product templates to appear on the public storefront. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_update_shop_collection_item",
          "title": "Update Shop Collection Item",
          "description": "Update one scoped shop_collection_item with its current expectedRevision. Same key/input recovers the prior receipt; changed input with the same key conflicts. Shop/collection publication is a distinct operation and is unavailable through this local preparation command."
        },
        {
          "name": "puppetto_update_shop_collection_v2",
          "title": "Update Shop Collection V2",
          "description": "Update one scoped shop_collection with its current expectedRevision. Same key/input recovers the prior receipt; changed input with the same key conflicts. Shop/collection publication is a distinct operation and is unavailable through this local preparation command."
        },
        {
          "name": "puppetto_update_shop_taste_profile",
          "title": "Update Shop Taste Profile",
          "description": "Update a shop taste profile used for ecommerce asset generation defaults. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_update_shop_v2",
          "title": "Update Shop V2",
          "description": "Update one scoped shop with its current expectedRevision. Same key/input recovers the prior receipt; changed input with the same key conflicts. Shop/collection publication is a distinct operation and is unavailable through this local preparation command."
        }
      ]
    },
    {
      "id": "documents",
      "label": "Documents & extraction",
      "tools": [
        {
          "name": "puppetto_apply_document_template",
          "title": "Apply Document Template",
          "description": "Validate values/defaults against a template revision and create a native metadata document linked to that template with an immutable field snapshot. This operation creates no PDF."
        },
        {
          "name": "puppetto_clone_document_template",
          "title": "Clone Document Template",
          "description": "Clone a native template with its content, margin, type and linked field overrides. The source revision must match; the new template gets new link IDs."
        },
        {
          "name": "puppetto_create_document_execution",
          "title": "Create Document Execution",
          "description": "Create a draft native document execution for an existing product workflow identifier. Does not start EventBridge processing."
        },
        {
          "name": "puppetto_create_document_field",
          "title": "Create Document Field",
          "description": "Create a reusable native field definition with a stable variable name and value type."
        },
        {
          "name": "puppetto_create_document_folder",
          "title": "Create Document Folder",
          "description": "Create a native folder. Create its parent first when nested."
        },
        {
          "name": "puppetto_create_document_template",
          "title": "Create Document Template",
          "description": "Create a native template with content, margin and active state. PDF generation is a separate unavailable capability."
        },
        {
          "name": "puppetto_delete_document_folder",
          "title": "Delete Document Folder",
          "description": "Delete an empty native folder after checking documents and subfolders. Does not delete stored files."
        },
        {
          "name": "puppetto_extract_document_text",
          "title": "Extract Document Text",
          "description": "Paid native OpenAI structured extraction (gpt-4o-mini): persist an intent and provider checkpoint first, then save validated values on a native metadata document. Same-key replay never resends a dispatched provider call. Read the document for current status; unknown provider outcomes require operator reconciliation."
        },
        {
          "name": "puppetto_finalize_document_upload",
          "title": "Finalize Document Upload",
          "description": "Verify stored byte count, MIME type and SHA-256, then atomically finalize the native upload and receipt."
        },
        {
          "name": "puppetto_get_document",
          "title": "Get Document",
          "description": "Read a native document, template snapshot/values and durable extraction checkpoint. No signed URL is stored in the document."
        },
        {
          "name": "puppetto_get_document_download",
          "title": "Get Document Download",
          "description": "Create a short-lived private download link after checking current authorization, finalization and source-file availability. Existing issued links remain valid until expiry."
        },
        {
          "name": "puppetto_get_document_execution",
          "title": "Get Document Execution",
          "description": "Read native execution status/counters and paginated document-link IDs/values. Start/retry remain explicitly unsupported pending durable EventBridge integration."
        },
        {
          "name": "puppetto_get_document_processing_capabilities",
          "title": "Get Document Processing Capabilities",
          "description": "Inspect actual text extraction readiness and explicit PDF/native execution gaps. A draft native execution is not a completed processing run."
        },
        {
          "name": "puppetto_get_document_template",
          "title": "Get Document Template",
          "description": "Read a template and up to 100 linked fields, including link IDs, effective defaults, required flags and definition revisions."
        },
        {
          "name": "puppetto_get_document_upload",
          "title": "Get Document Upload",
          "description": "Get a fresh five-minute upload URL for a pending organization-scoped private document. Never save the signed URL in logs."
        },
        {
          "name": "puppetto_list_document_executions",
          "title": "List Document Executions",
          "description": "List native document execution lifecycle records; these are separate from workflow graph runs."
        },
        {
          "name": "puppetto_list_document_fields",
          "title": "List Document Fields",
          "description": "List organization-owned field definitions with revisions."
        },
        {
          "name": "puppetto_list_document_folders",
          "title": "List Document Folders",
          "description": "List native document folders with their paths and revisions."
        },
        {
          "name": "puppetto_list_document_templates",
          "title": "List Document Templates",
          "description": "List native document templates with active/archive state and revisions."
        },
        {
          "name": "puppetto_list_documents",
          "title": "List Documents",
          "description": "List native documents with revisions and keyset pagination; optionally select one native folder."
        },
        {
          "name": "puppetto_mutate_document",
          "title": "Mutate Document",
          "description": "Revisioned rename, folder move, archive or restore. Archive preserves the native record and stored file."
        },
        {
          "name": "puppetto_mutate_document_execution",
          "title": "Mutate Document Execution",
          "description": "Revisioned native draft attachment/detachment, editable document values, or archive of a nonactive execution. Relationships and counters stay in native execution tables; no provider is launched."
        },
        {
          "name": "puppetto_mutate_document_field",
          "title": "Mutate Document Field",
          "description": "Replace a native field definition or delete an unlinked definition. Updates also advance linked template revisions."
        },
        {
          "name": "puppetto_mutate_document_template",
          "title": "Mutate Document Template",
          "description": "Revisioned template update/archive/restore and field add/remove/order/default/required changes using native links. Field IDs must belong to the verified organization."
        },
        {
          "name": "puppetto_prepare_document_upload",
          "title": "Prepare Document Upload",
          "description": "Create a durable private-document upload reservation. Then request its transient upload URL, upload bytes with all returned headers, and finalize with checksum verification."
        },
        {
          "name": "puppetto_retry_document_extraction",
          "title": "Retry Document Extraction",
          "description": "Explicit new paid attempt only after a known invalid extraction output, with additional-cost acknowledgement. Unknown or still-dispatched provider outcomes are blocked for reconciliation."
        }
      ]
    },
    {
      "id": "integrations",
      "label": "Connected integrations",
      "tools": [
        {
          "name": "puppetto_execute_integration_action",
          "title": "Execute Integration Action",
          "description": "Execute paid marketplace, private.*, or launch.* actions. Launch enrollment explicitly authorizes automatic publishing after trusted work, independent quality votes, and refundable credit stakes pass; stakes reserve real organization credits. Mutations require idempotency keys. Private compute charges no credits."
        },
        {
          "name": "puppetto_list_integration_actions",
          "title": "List Integration Actions",
          "description": "Discover marketplace, private integration, and launch.* actions and schemas. Launch gates combine trusted work receipts, independent quality votes, and refundable credit stakes before automatic publishing."
        },
        {
          "name": "puppetto_list_integration_capabilities",
          "title": "List Integration Capabilities",
          "description": "List the public Puppetto integration capability catalog in one generic shape, optionally filtered by provider, capability, category, asset type, or connected integrations. Includes MCP coverage hints, auth/setup fields, generation controls, model defaults, and sanitized connection status without returning tokens or secrets."
        },
        {
          "name": "puppetto_list_integrations",
          "title": "List Integrations",
          "description": "List connected organization integrations and sanitized account/auth metadata. Does not return stored tokens or secrets."
        },
        {
          "name": "puppetto_query_integration",
          "title": "Query Integration",
          "description": "Read marketplace accounting, organization-private execution, launch.get gate assessments, and launch.integration_events. Discover schemas with puppetto_list_integration_actions."
        }
      ]
    },
    {
      "id": "memory-stories",
      "label": "Memory stories & submissions",
      "tools": [
        {
          "name": "puppetto_configure_memory_story_collection",
          "title": "Configure Memory Story Collection",
          "description": "Save native memory collection settings with one aggregate revision and durable receipt. Private visibility is enforced. Optional ownerUserId must be a current member; native organization-owner assignment restrictions apply. Does not send invitations or notifications."
        },
        {
          "name": "puppetto_create_memory_story_invite",
          "title": "Create Memory Story Invite",
          "description": "Create a link-only native memory-writing invite with full-token hashing, expiry, recipient and quota rules. Returns a private inviteKey/URL only to the authorized collection owner. Reuse the exact key/input after timeout to recover the same link. No email is sent."
        },
        {
          "name": "puppetto_get_memory_story_writing_context",
          "title": "Get Memory Story Writing Context",
          "description": "Read the existing native invite/public-grant writing prompts, character summary, current collection revision and rules for the verified organization member. Does not grant guest MCP access or bypass disabled, expired, revoked, recipient, or foreign collection checks."
        },
        {
          "name": "puppetto_inspect_memory_story_collection",
          "title": "Inspect Memory Story Collection",
          "description": "Read native customer memory-story settings and collection revision for one character. This private submission workflow is distinct from editable story scripts. Settings owner or organization owner manages an existing collection. Guest writers use existing native invite/public links; an invite is not an MCP credential."
        },
        {
          "name": "puppetto_list_memory_story_invites",
          "title": "List Memory Story Invites",
          "description": "Page native invitation records without key hashes or invite secrets. Use IDs from this read to revoke a link. Legacy links require owner replacement to verify complete-token integrity."
        },
        {
          "name": "puppetto_list_memory_story_submissions",
          "title": "List Memory Story Submissions",
          "description": "Page private native customer memory submissions for collection owner review, with IDs and native moderation status. This does not expose script beats or foreign organization submissions."
        },
        {
          "name": "puppetto_moderate_memory_story_submission",
          "title": "Moderate Memory Story Submission",
          "description": "Set the native submitted, reviewed, or archived moderation status with an aggregate revision check and durable receipt. Archive preserves the private submission and segments; moderation never publishes it or changes editable story scripts."
        },
        {
          "name": "puppetto_read_memory_story_submission",
          "title": "Read Memory Story Submission",
          "description": "Read one scoped private submission with its ordered dated segments and snapshotted tags/prompts/owner metadata. Requires current native collection-management permission."
        },
        {
          "name": "puppetto_revoke_memory_story_invite",
          "title": "Revoke Memory Story Invite",
          "description": "Revoke an invite in this character collection. Subsequent writing context/submission access, including receipt replay through this MCP wrapper, must pass current invite checks. Existing submissions remain private and reviewable."
        },
        {
          "name": "puppetto_submit_memory_story",
          "title": "Submit Memory Story",
          "description": "Submit dated memory segments through the native invite/public collection grant as the verified organization member. Native recipient/expiry/quota checks apply. Verified account email is used; caller-supplied identity is unavailable. Commits once with its receipt and preserves private snapshots. No notification is sent."
        }
      ]
    },
    {
      "id": "onboarding",
      "label": "Verified onboarding",
      "tools": [
        {
          "name": "puppetto_accept_onboarding_activation_offer",
          "title": "Accept Onboarding Activation Offer",
          "description": "Record that an onboarding agent offered a credit activation path to the human and return the exact proof requirements."
        },
        {
          "name": "puppetto_begin_onboarding",
          "title": "Start a guest workspace",
          "description": "Start a guest workspace without an email, password, API key, or account. Keep the returned claimToken private. Prepare limited drafts with puppetto_prepare_guest_onboarding_draft, then call puppetto_connect_account with this sessionId and claimToken. The client opens account sign-in and organization consent; retry the same call afterward to claim and resume the drafts at the same MCP URL."
        },
        {
          "name": "puppetto_confirm_verified_onboarding_agentmail_email",
          "title": "Confirm Verified Onboarding Agentmail Email",
          "description": "For AgentMail-backed onboarding sessions, inspect the session inbox, open the Supabase/Puppetto signup confirmation link, and mark the email as verified. This does not create the organization; call puppetto_create_verified_onboarding_organization afterwards."
        },
        {
          "name": "puppetto_connect_account",
          "title": "Connect Puppetto and resume your work",
          "description": "Connect the human Puppetto account through client-managed OAuth. If challenged, let the client open sign-in, select or create the organization, and consent, then retry this same call in the same conversation. Pass a guest sessionId and claimToken to claim its drafts exactly once; omit both to resume previously claimed drafts. Returns the verified organization and saved drafts. Never asks for API keys, changes endpoints, publishes, sends, or spends credits."
        },
        {
          "name": "puppetto_create_campaign_from_onboarding_template",
          "title": "Create Campaign From Onboarding Template",
          "description": "Create a ready-to-edit social campaign from a creative onboarding template, including optional storyline, starter characters, scheduled draft posts, and connected target accounts."
        },
        {
          "name": "puppetto_create_verified_onboarding",
          "title": "Create Verified Onboarding",
          "description": "Create a verified Puppetto onboarding session and return a human signup link. Default path requires the human to verify/sign in before org creation and MCP token release. Optionally provisions an AgentMail inbox for controlled test onboarding."
        },
        {
          "name": "puppetto_create_verified_onboarding_organization",
          "title": "Create Verified Onboarding Organization",
          "description": "After the onboarding email is verified, create the Puppetto organization, redeem starter credits, complete the session, and return the org-scoped Streamable HTTP MCP config. This separates email confirmation from org creation so agents can recover when the browser callback did not carry mcpOnboardingId."
        },
        {
          "name": "puppetto_get_social_onboarding_status",
          "title": "Get Social Onboarding Status",
          "description": "Verify social onboarding after the human returns from provider consent. Reads the authorized organization’s connections, account identities, token expiry/reconnect state, and next steps. An existing integration row alone does not establish publishing readiness. This read does not publish, refresh tokens, or spend credits."
        },
        {
          "name": "puppetto_get_verified_onboarding_audit",
          "title": "Get Verified Onboarding Audit",
          "description": "Return the claim-token-scoped audit trail for a verified onboarding session: handoff links, created artifacts, accepted activation offers, submitted proof, completion state, and admin review hints."
        },
        {
          "name": "puppetto_get_verified_onboarding_email_message",
          "title": "Get Verified Onboarding Email Message",
          "description": "Get a single AgentMail message for an AgentMail-backed onboarding session. Requires the onboarding claim token."
        },
        {
          "name": "puppetto_get_verified_onboarding_status",
          "title": "Get Verified Onboarding Status",
          "description": "Poll a verified onboarding session. Once the human has completed auth and org creation, returns an org-scoped Streamable HTTP MCP config."
        },
        {
          "name": "puppetto_list_onboarding_activation_offers",
          "title": "List Onboarding Activation Offers",
          "description": "List currently supported activation offers that can earn organization credits after admin verification. Offers are audit-only from MCP; admins grant credits through Puppetto."
        },
        {
          "name": "puppetto_list_onboarding_templates",
          "title": "List Onboarding Templates",
          "description": "List opinionated creative onboarding templates that can create a campaign, storyline, starter characters, and draft posts quickly."
        },
        {
          "name": "puppetto_list_verified_onboarding_email_messages",
          "title": "List Verified Onboarding Email Messages",
          "description": "List messages for an AgentMail inbox created by puppetto_create_verified_onboarding. Requires the onboarding claim token."
        },
        {
          "name": "puppetto_prepare_guest_onboarding_draft",
          "title": "Prepare Guest Onboarding Draft",
          "description": "Prepare claim-token-scoped onboarding draft material before human verification. This stores limited draft content in the onboarding audit trail only; it cannot publish, spend, send email, connect integrations, or read existing organizations."
        },
        {
          "name": "puppetto_prepare_verified_onboarding_handoff",
          "title": "Prepare Verified Onboarding Handoff",
          "description": "Collect the human preferred confirmation email for a claim-token-scoped onboarding session and return prefilled signup/sign-in links the agent can hand to the user. This does not send email or release organization credentials."
        },
        {
          "name": "puppetto_record_verified_onboarding_artifact",
          "title": "Record Verified Onboarding Artifact",
          "description": "Append a link, created object, or artifact to the verified onboarding audit trail so admins can inspect what the assisting agent created."
        },
        {
          "name": "puppetto_start_verified_onboarding_account",
          "title": "Start Verified Onboarding Account",
          "description": "Start the email-confirmation step for a verified MCP onboarding session without creating the organization yet. For AgentMail sessions, the MCP server can generate a private password and the agent can confirm the email from the session inbox; for human email sessions, pass the human-provided password or use the normal signup link."
        },
        {
          "name": "puppetto_submit_onboarding_activation_proof",
          "title": "Submit Onboarding Activation Proof",
          "description": "Submit activation proof for admin review, such as a public X post URL plus Puppetto post and integration IDs. Does not grant credits automatically."
        }
      ]
    },
    {
      "id": "organization-operations",
      "label": "Approvals & fulfillment",
      "tools": [
        {
          "name": "puppetto_get_prompt_action_object",
          "title": "Get Prompt Action Object",
          "description": "Get a stored prompt-action context object by ID for the authorized organization."
        },
        {
          "name": "puppetto_list_prompt_action_objects",
          "title": "List Prompt Action Objects",
          "description": "List stored prompt-action context objects for the authorized organization."
        },
        {
          "name": "puppetto_resolve_prompt_action",
          "title": "Resolve Prompt Action",
          "description": "Resolve a prompt against organization context such as assets, references, campaigns, posts, and schedules. Optionally stores the prompt action for later recall."
        }
      ]
    },
    {
      "id": "organizations",
      "label": "Organization management",
      "tools": [
        {
          "name": "puppetto_assign_organization_quest",
          "title": "Assign Organization Quest",
          "description": "Assign a quest and optional credit reward/incentive campaign to the authorized organization for agents to read through MCP. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_get_organization_access",
          "title": "Get Organization Access",
          "description": "Read the credential-bound organization, safe profile/contact settings, current live member role, command revision and supported capabilities. Billing and credential settings are excluded."
        },
        {
          "name": "puppetto_get_organization_connection_health",
          "title": "Get Organization Connection Health",
          "description": "Inspect an organization-scoped connection and current revision. Disconnected, unavailable, missing, unknown, expired and refresh-due connections are not publish-ready. No provider call is performed."
        },
        {
          "name": "puppetto_list_organization_connections",
          "title": "List Organization Connections",
          "description": "Page organization integration connections with local disconnect, recorded expiry and recovery states. This reads credential presence only; provider validity is unverified and secrets/account payloads are excluded."
        },
        {
          "name": "puppetto_list_organization_invites",
          "title": "List Organization Invites",
          "description": "List invitation IDs, expiry, delivery status and revocation state. Never returns invite keys or credential values. Administrator access required."
        },
        {
          "name": "puppetto_list_organization_members",
          "title": "List Organization Members",
          "description": "List active organization member IDs and roles with a cursor and the current organization revision. Administrator access required."
        },
        {
          "name": "puppetto_list_organization_quests",
          "title": "List Organization Quests",
          "description": "List organization quest assignments, incentive rewards, proof, and credit redemption review state readable by agents, optionally including the built-in quest catalog."
        },
        {
          "name": "puppetto_mutate_organization",
          "title": "Mutate Organization",
          "description": "Atomically update allowlisted profile/contact settings (contact replaces the contact object); invite a registered user without sending email; revoke a pending invitation; or manage members. Uses current organization revision and durable retry keys. Protects the organization owner and last administrator. Invite acceptance occurs in the authenticated native user flow."
        },
        {
          "name": "puppetto_mutate_organization_connection",
          "title": "Mutate Organization Connection",
          "description": "Revisioned connection command: assign/clear an organization character or locally disconnect. Disconnect clears stored credentials and cancels queued token refresh; it does not revoke the provider grant or cancel in-flight provider work. Reconnect uses the native UI."
        },
        {
          "name": "puppetto_review_organization_quest_redemption",
          "title": "Review Organization Quest Redemption",
          "description": "Review an assigned quest for a credit redemption campaign. This records approval/rejection/redeemed state and optional credit transaction ID, but does not mint credits by itself. Requires an admin-linked organization API key."
        },
        {
          "name": "puppetto_select_organization",
          "title": "Select Organization",
          "description": "Verify selection of the organization already bound to this credential. Selecting another requires OAuth consent or its organization API key; this read never changes credential scope or grants membership."
        },
        {
          "name": "puppetto_submit_organization_quest_proof",
          "title": "Submit Organization Quest Proof",
          "description": "Submit proof that an organization participated in or completed an assigned quest, such as a post URL, Puppetto entity IDs, metric summary, or text evidence. Requires a member- or admin-linked organization API key."
        },
        {
          "name": "puppetto_update_organization_quest",
          "title": "Update Organization Quest",
          "description": "Update progress, priority, notes, due date, reward metadata, redemption state, or audit metadata for an assigned organization quest. Requires an admin-linked organization API key."
        }
      ]
    },
    {
      "id": "platform",
      "label": "Context, diagnostics & commerce operations",
      "tools": [
        {
          "name": "puppetto_accept_selection_invitation",
          "title": "Accept Selection Invitation",
          "description": "Accept a recipient-bound invitation with its fragment token. Acceptance never grants organization membership. The signed-in recipient must match the current verified email."
        },
        {
          "name": "puppetto_archive_selection_pool",
          "title": "Archive Selection Pool",
          "description": "Archive a decision pool (soft delete), close intake and remove it from default listings and public observation. Close or cancel open review rounds first; ROUND_IN_USE rejects archive while a round is open. Requires owner access, expectedRevision and an idempotencyKey. Existing immutable decisions and draft attachments remain available to authorized readers; no history or media is permanently deleted."
        },
        {
          "name": "puppetto_begin_public_selection_submission",
          "title": "Begin Public Selection Submission",
          "description": "Reserve a verified user public-origin contribution and quota. Always requires owner moderation, including users who also hold trusted private invitations. Get the separate ephemeral upload URL next."
        },
        {
          "name": "puppetto_begin_selection_submission",
          "title": "Begin Selection Submission",
          "description": "Reserve an invited contribution and quota. Only currently trusted private submissions can auto-admit after validation. Get the separate ephemeral upload URL next."
        },
        {
          "name": "puppetto_cancel_selection_round",
          "title": "Cancel Selection Round",
          "description": "cancel round for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_close_selection_round",
          "title": "Close Selection Round",
          "description": "Close a round at its committed response cutoff and persist the strategy result. Ties and insufficient coverage remain explicit. A result recommends; the owner must finalize a decision."
        },
        {
          "name": "puppetto_create_brand_workspace",
          "title": "Create Brand Workspace",
          "description": "Prepare a fresh private organization for a prospect company from its public website. Requires verified user OAuth. Creates an owned organization and a durable scan job; extracts source-backed brand/business facts and seeds three editable problem/solution stories linked to a draft campaign. Returns progress and a native review URL. No invitation, outreach, publishing, billing, or credential organization switch occurs. Reuse the requestKey for identical retries."
        },
        {
          "name": "puppetto_create_selection_invitation",
          "title": "Create Selection Invitation",
          "description": "Create a recipient-bound scoped invitation. Vote invitations require a round. The acceptance URL is returned once in ephemeral; delivery is not_sent. Share it explicitly. Receipt replay never returns the secret."
        },
        {
          "name": "puppetto_create_selection_merch_drop",
          "title": "Create Selection Merch Drop",
          "description": "Create a draft store collection for a merch drop using the existing catalog creation workflow. Requires current catalog administrator access and an idempotency key. Does not publish the collection or store."
        },
        {
          "name": "puppetto_create_selection_pool",
          "title": "Create Selection Pool",
          "description": "Create a campaign selection pool with independent viewing, submissions, voting and intake limits. Candidates remain private immutable snapshots until an explicit publishing workflow."
        },
        {
          "name": "puppetto_create_selection_round",
          "title": "Create Selection Round",
          "description": "create round for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_finalize_selection_decision",
          "title": "Finalize Selection Decision",
          "description": "Explicitly select one active candidate, optionally referencing a closed round. Creates immutable decision history and supersedes the current decision without changing existing drafts."
        },
        {
          "name": "puppetto_finalize_selection_submission",
          "title": "Finalize Selection Submission",
          "description": "Verify uploaded media, seal its private immutable snapshot and finalize contribution. Public submissions stay pending until owner approval. No organization asset is created."
        },
        {
          "name": "puppetto_get_action_requirements",
          "title": "Get Action Requirements",
          "description": "Explain the dependencies an agent must resolve before a Puppetto action is fulfillable, including onboarding/setup links, required MCP tools, credits, provider support, character voice requirements, social targets, and cleanup paths."
        },
        {
          "name": "puppetto_get_authorized_context",
          "title": "Get Authorized Context",
          "description": "Verify the authorized organization, MCP credential context, and owner membership for this MCP session."
        },
        {
          "name": "puppetto_get_brand_workspace",
          "title": "Get Brand Workspace",
          "description": "Read a URL-prepared brand workspace by jobId, including durable progress, observed source facts, draft hypotheses, and native story/campaign links. Requires verified user OAuth and current target owner/admin access. Progress responses omit full extraction details until ready."
        },
        {
          "name": "puppetto_get_connection_action_handoff",
          "title": "Get Connection Action Handoff",
          "description": "Return the authenticated native UI handoff for secret configuration, reconnect, refresh or live provider inspection. Requires an administrator. This read performs no provider action, refresh, credential change or enqueue."
        },
        {
          "name": "puppetto_get_handoff_links",
          "title": "Open this work in Puppetto",
          "description": "Get verified deep links to a workspace, shop, product editor, collection manager, campaign, post, character, or workflow in the connected organization. Send url to the human to continue in Puppetto; sign-in preserves the destination. Product targets require shopId and a real collection membership. Published shop/product/collection targets also return publicUrl; published shops return catalogueUrl. Links contain no credentials and grant no new access."
        },
        {
          "name": "puppetto_get_mcp_diagnostics",
          "title": "Get Mcp Diagnostics",
          "description": "Read safe release identity and exact discovery catalog hashes. This read does not access organization data or verify connected-plugin exposure."
        },
        {
          "name": "puppetto_get_own_selection_submission",
          "title": "Get Own Selection Submission",
          "description": "get own submission for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_get_public_selection_brief",
          "title": "Get Public Selection Brief",
          "description": "public brief for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_get_public_selection_decision",
          "title": "Get Public Selection Decision",
          "description": "Read one shareable public decision and its current or superseded state. Current public-gallery policy is checked every time. Withdrawn candidate IDs, titles and media details are withheld."
        },
        {
          "name": "puppetto_get_selection_contribution_brief",
          "title": "Get Selection Contribution Brief",
          "description": "contribution brief for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_get_selection_decision",
          "title": "Get Selection Decision",
          "description": "get decision for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_get_selection_draft_placement",
          "title": "Get Selection Draft Placement",
          "description": "get draft placement for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_get_selection_merch_drop",
          "title": "Get Selection Merch Drop",
          "description": "Read the destination draft collection revision and this pool’s current drop placements. changed indicates catalog edits since a design was chosen; selection evidence stays immutable."
        },
        {
          "name": "puppetto_get_selection_pool",
          "title": "Get Selection Pool",
          "description": "Read a decision pool, its current revision and your current access. Use the returned revision for updates and archive. Private details require ownership or an explicit view invitation; public galleries have separate observation tools."
        },
        {
          "name": "puppetto_get_selection_review_task",
          "title": "Get Selection Review Task",
          "description": "Get a persisted review task. Pairwise tasks balance graph coverage, reviewer coverage and rating proximity. Retry with the same key after uncertainty."
        },
        {
          "name": "puppetto_get_selection_round",
          "title": "Get Selection Round",
          "description": "get round for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_get_selection_submission_upload",
          "title": "Get Selection Submission Upload",
          "description": "Get an ephemeral conditional upload URL and required checksum/content headers for your current submission. Upload bytes exactly once, then explicitly finalize. The URL is never stored in receipts."
        },
        {
          "name": "puppetto_inspect_selection_merch_design",
          "title": "Inspect Selection Merch Design",
          "description": "Inspect the complete current product design and obtain its digest before registration: template, variants, prices, print areas, artwork assignments and source asset versions are fingerprinted. Review output omits costs, storage paths and private metadata."
        },
        {
          "name": "puppetto_list_background_tasks",
          "title": "List Background Tasks",
          "description": "List recurring/background calendar tasks for the authorized organization."
        },
        {
          "name": "puppetto_list_bug_reports",
          "title": "List Bug Reports",
          "description": "List and stack-rank organization bug reports created through MCP. Defaults to active reports and returns lifecycle status, priority, severity, area, triage score, and related entity IDs."
        },
        {
          "name": "puppetto_list_own_selection_submissions",
          "title": "List Own Selection Submissions",
          "description": "list own submissions for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_list_public_selection_candidates",
          "title": "List Public Selection Candidates",
          "description": "public candidates for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_list_public_selection_decisions",
          "title": "List Public Selection Decisions",
          "description": "Read public decision history newest first, using its independent opaque cursor. Decisions omit owner rationale and identities; withdrawn choices expose only an unavailable marker."
        },
        {
          "name": "puppetto_list_public_selection_rounds",
          "title": "List Public Selection Rounds",
          "description": "Read opened public round progress with aggregate participation counts. Drafts, ballots, tasks, identities and live tallies are withheld. Only closed rounds expose redacted recommendations, explicit ties and provisional coverage."
        },
        {
          "name": "puppetto_list_scheduled_jobs",
          "title": "List Scheduled Jobs",
          "description": "List scheduled backend jobs for the authorized organization, optionally filtered by run date and status."
        },
        {
          "name": "puppetto_list_selection_candidates",
          "title": "List Selection Candidates",
          "description": "list candidates for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_list_selection_decisions",
          "title": "List Selection Decisions",
          "description": "list decisions for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_list_selection_draft_attachments",
          "title": "List Selection Draft Attachments",
          "description": "list attachments for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_list_selection_drafts",
          "title": "List Selection Drafts",
          "description": "list draft posts for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_list_selection_invitations",
          "title": "List Selection Invitations",
          "description": "list invitations for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_list_selection_merch_designs",
          "title": "List Selection Merch Designs",
          "description": "List organization-owned physical product designs available for this merch pool. Designs may be prepared for different similar products; the pool product group records the choice being made for the store drop."
        },
        {
          "name": "puppetto_list_selection_merch_drops",
          "title": "List Selection Merch Drops",
          "description": "List available store collections for drop planning in the credential organization. Requires current catalog administrator access. Only draft collections can receive selected product designs."
        },
        {
          "name": "puppetto_list_selection_participants",
          "title": "List Selection Participants",
          "description": "list participants for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_list_selection_pools",
          "title": "List Selection Pools",
          "description": "List accessible decision pools in the credential organization, optionally filtered by campaignId. Archived pools are excluded unless includeArchived is true. Follow nextCursor even when access filtering returns an empty page."
        },
        {
          "name": "puppetto_list_selection_rounds",
          "title": "List Selection Rounds",
          "description": "list rounds for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_list_selection_submissions",
          "title": "List Selection Submissions",
          "description": "list submissions for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_moderate_selection_submission",
          "title": "Moderate Selection Submission",
          "description": "Approve or reject a pending contribution at its current revision. Approval admits the exact snapshot to the pool and only future unfrozen rounds."
        },
        {
          "name": "puppetto_open_selection_round",
          "title": "Open Selection Round",
          "description": "Freeze the eligible candidate manifest and open this revision of the round. Later approvals enter subsequent rounds. Ballots and assignments use this immutable manifest."
        },
        {
          "name": "puppetto_register_selection_merch_design",
          "title": "Register Selection Merch Design",
          "description": "Register a complete product design with a sealed image preview or design sheet. Pass the inspected productTemplateId and expectedDigest in design, plus the preview asset and its revision. A later product edit creates a different candidate; frozen votes retain their original design."
        },
        {
          "name": "puppetto_register_selection_output",
          "title": "Register Selection Output",
          "description": "Register one completed organization asset as an immutable candidate. Pass its current revision. Generate variations without postId, then register each completed output here; this command does not generate or attach media."
        },
        {
          "name": "puppetto_report_bug",
          "title": "Report Bug",
          "description": "File a structured organization-scoped MCP bug report when an agent hits a Puppetto/provider/API gap, broken integration, unexpected error, missing cleanup path, or workaround. Agents should call this before silently switching providers or leaving failed placeholders behind."
        },
        {
          "name": "puppetto_restore_selection_participant",
          "title": "Restore Selection Participant",
          "description": "Remove an explicit participant ban. Revoked invitations stay revoked; use a new invitation to restore private capabilities."
        },
        {
          "name": "puppetto_retry_brand_workspace",
          "title": "Retry Brand Workspace",
          "description": "Retry a failed, undispatched, or expired URL brand setup using its current attempt and a new requestKey. Preserves the fresh organization; stale workers cannot duplicate or overwrite draft outputs. Requires verified user OAuth and current target owner/admin access."
        },
        {
          "name": "puppetto_revoke_selection_invitation",
          "title": "Revoke Selection Invitation",
          "description": "revoke invitation for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_revoke_selection_participant",
          "title": "Revoke Selection Participant",
          "description": "revoke participant for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_rotate_selection_invitation",
          "title": "Rotate Selection Invitation",
          "description": "Explicitly replace a pending invitation secret. Invalidates the previous link and returns a new one-time ephemeral acceptance URL. No message is sent."
        },
        {
          "name": "puppetto_submit_selection_response",
          "title": "Submit Selection Response",
          "description": "Submit one immutable ranked ballot or pairwise outcome. Draw scores, skip does not. Closed rounds and revoked grants reject responses, including receipt replay after access is revoked."
        },
        {
          "name": "puppetto_update_brand_workspace_brief",
          "title": "Update Brand Workspace Brief",
          "description": "Save reviewed name, business description, audience, and tone at the current brief revision. Source facts remain unchanged; edit native story scripts separately. Requires verified user OAuth and current target owner/admin access. Never publishes content or changes credential organization."
        },
        {
          "name": "puppetto_update_bug_report",
          "title": "Update Bug Report",
          "description": "Update bug-report lifecycle metadata, including status, priority, owner, fixed commit, verification evidence, duplicate relationship, notes, and resolution. Use after fixing or verifying an MCP-reported bug."
        },
        {
          "name": "puppetto_update_selection_pool",
          "title": "Update Selection Pool",
          "description": "Update a decision pool brief, name, campaign, default strategy or independent viewing, submission and voting policies. Requires owner access, expectedRevision and an idempotencyKey. Read the current revision after a conflict. Existing frozen review rounds retain their strategy and candidate manifest."
        },
        {
          "name": "puppetto_use_selection_in_draft",
          "title": "Use Selection In Draft",
          "description": "Attach the exact selected private snapshot to an eligible DRAFT at expectedPostRevision. Explicitly append or replace one selection attachment. Verifies bytes and records provenance; never schedules, cancels jobs or publishes."
        },
        {
          "name": "puppetto_use_selection_in_drop",
          "title": "Use Selection In Drop",
          "description": "Explicitly add the current selected complete product design to its draft store collection. Requires current collection revision and catalog administrator rights. Changed designs must be reviewed again. Replacement requires the prior item and revision. Records decision provenance; never activates products, publishes a collection, calls a paid provider or publishes a store."
        },
        {
          "name": "puppetto_watch_public_selection_pool",
          "title": "Watch Public Selection Pool",
          "description": "Observe the current explicit selection and public candidate, decision and open-round counts. Available only while the gallery is public, the pool is unarchived and the organization is active. Public submission intake alone does not grant observation."
        },
        {
          "name": "puppetto_withdraw_selection_candidate",
          "title": "Withdraw Selection Candidate",
          "description": "withdraw candidate for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        },
        {
          "name": "puppetto_withdraw_selection_submission",
          "title": "Withdraw Selection Submission",
          "description": "withdraw submission for the currently authorized selection pool. Reads are paginated with independent cursors; media access uses authorized application endpoints."
        }
      ]
    },
    {
      "id": "platform-admin",
      "label": "Admin workflow handoffs",
      "tools": [
        {
          "name": "puppetto_list_admin_workflow_handoffs",
          "title": "List Admin Workflow Handoffs",
          "description": "OAuth platform-super-admin-only paginated native administration/account/billing inventory with exact source entry points, required permission, native effects, trusted handoff links, owner and explicit blocked completion status. Organization admin keys cannot access this profile. Reading this directory executes no native action and does not certify legacy authorization or completed human handoffs."
        }
      ]
    },
    {
      "id": "posts-and-social",
      "label": "Posts, social & scheduling",
      "tools": [
        {
          "name": "puppetto_create_draft_post",
          "title": "Create Draft Post",
          "description": "Create a draft post for the authorized organization."
        },
        {
          "name": "puppetto_create_social_post",
          "title": "Create Social Post",
          "description": "Create a social post with optional character, assets, target integrations, campaign link, and schedule using MCP-safe defaults. Scheduled posts are saved for approval unless status is READY and targets are connected."
        },
        {
          "name": "puppetto_get_post",
          "title": "Get Post",
          "description": "Get a post by ID for the authorized organization."
        },
        {
          "name": "puppetto_get_post_bundle",
          "title": "Get Post Bundle",
          "description": "Read post revision, target branches and provider results, linked media availability, campaign membership link IDs, schedule intents, notifications, and readiness. Child collections have independent cursors. UNKNOWN/IN_PROGRESS provider outcomes require reconciliation; no external cancellation or provider idempotency is implied."
        },
        {
          "name": "puppetto_get_social_connection_links",
          "title": "Get Social Connection Links",
          "description": "Start or resume social onboarding with browser consent links, automatic reconnect targeting, account identities, and verification steps. The human completes provider OAuth; then call this tool again or puppetto_get_social_onboarding_status to verify the connection in the same conversation."
        },
        {
          "name": "puppetto_list_calendar_posts",
          "title": "List Calendar Posts",
          "description": "List scheduled calendar posts for the authorized organization, optionally filtered by date range and status."
        },
        {
          "name": "puppetto_list_linkedin_profiles",
          "title": "List Linkedin Profiles",
          "description": "List connected LinkedIn profiles for the authorized organization using sanitized stored account data."
        },
        {
          "name": "puppetto_list_posts",
          "title": "List Posts",
          "description": "List posts for the authorized organization."
        },
        {
          "name": "puppetto_list_posts_page",
          "title": "List Posts Page",
          "description": "List authorized posts with revisions and stable UUID cursors. No publishing or readiness side effects."
        },
        {
          "name": "puppetto_list_social_posting_providers",
          "title": "List Social Posting Providers",
          "description": "List social posting providers, web-deployment OAuth readiness, connected account identities, and reconnect requirements. Unknown readiness does not mean platform credentials are missing."
        },
        {
          "name": "puppetto_mark_post_ready",
          "title": "Mark Post Ready",
          "description": "Approve a post after review. If the post has a schedule and connected targets, this creates the pending scheduled publishing job; otherwise it marks the post ready or returns missing requirements."
        },
        {
          "name": "puppetto_mutate_post",
          "title": "Mutate Post",
          "description": "Revisioned, durable post command: schedule/reschedule an already READY/QUEUED post (enqueues future external publication), cancel pending publishing jobs, return an unpublished post to draft, or retry only a selected authoritative failed target known not to have published. Retrying preserves completed target results. In-flight provider cancellation is unsupported. Unknown outcomes and legacy failures without safe-retry evidence are never resent automatically. Recover an uncertain command response by replaying identical input and key."
        },
        {
          "name": "puppetto_set_post_targets",
          "title": "Set Post Targets",
          "description": "Replace the connected social target integrations for a post and update readiness. Scheduled posts still require approval before a publishing job is queued."
        },
        {
          "name": "puppetto_update_draft_post",
          "title": "Update Draft Post",
          "description": "Update a draft post for the authorized organization."
        },
        {
          "name": "puppetto_update_post_schedule",
          "title": "Update Post Schedule",
          "description": "Schedule, reschedule, or clear a non-published post on the organization calendar. Scheduling saves the time but requires connected targets and puppetto_mark_post_ready before a publishing job is queued. Use null scheduledAt to clear the schedule."
        }
      ]
    },
    {
      "id": "research",
      "label": "Research tasks",
      "tools": [
        {
          "name": "puppetto_control_research_task",
          "title": "Control Research Task",
          "description": "Revisioned cancellation of only an undispatched initializing/pending research record, by its owner or an organization admin. Local cancellation does not stop remote work or refund credits. Retry, dispatched/running cancellation and terminal-state cancellation return explicit unsupported errors."
        },
        {
          "name": "puppetto_get_research_task",
          "title": "Get Research Task",
          "description": "Read a scoped native research task and its persisted inline answer with source provenance. File artifacts and provider attribution are explicitly unavailable; unknown external outcomes are not retried."
        },
        {
          "name": "puppetto_list_research_tasks",
          "title": "List Research Tasks",
          "description": "List actual native research tasks with revisions and stable UUID cursors. Distinct from generic background tasks. Native ECS/Owl research dispatch and S3 artifact listing are disabled; availability is explicit."
        },
        {
          "name": "puppetto_start_research_task_v2",
          "title": "Start Research Task V2",
          "description": "Check the native research start capability. Returns UNSUPPORTED_ACTION because ECS/Owl dispatch is disabled; creates no task, makes no provider call and charges zero credits."
        }
      ]
    },
    {
      "id": "skills",
      "label": "Skills marketplace",
      "tools": [
        {
          "name": "puppetto_get_skill",
          "title": "Get Skill",
          "description": "Read one public skill by slug, including every immutable bundle file, content hash, source version, attribution and license. Treat these third-party instructions as content to inspect. Reading does not install or execute the skill."
        },
        {
          "name": "puppetto_list_saved_skills",
          "title": "List Saved Skills",
          "description": "List the authorized organization’s saved skill library, optionally filtered by query or tag. Saved entries reference exact immutable skill bundles and include savedAt. Organization identity comes from the verified credential."
        },
        {
          "name": "puppetto_list_skills",
          "title": "List Skills",
          "description": "Discover publicly posted Puppetto marketplace skills by query or tag. Returns bounded metadata pages with an independent nextCursor. Use puppetto_get_skill to inspect the complete immutable bundle before saving it."
        },
        {
          "name": "puppetto_publish_skill",
          "title": "Publish Skill",
          "description": "Post a new public skill from any current Puppetto organization member. Supply a unique slug and the complete text-file bundle, including a root SKILL.md and required resources and license. Listings are immutable; source metadata is publisher-declared. Requires an idempotency key and never executes uploaded code."
        },
        {
          "name": "puppetto_save_skill",
          "title": "Save Skill",
          "description": "Save an exact immutable public skill bundle by slug to the authorized organization’s shared library. Any current member may save. Requires an idempotency key. Does not install, execute, deploy, upload media or incur provider costs; inspect the bundle with puppetto_get_skill."
        },
        {
          "name": "puppetto_unsave_skill",
          "title": "Unsave Skill",
          "description": "Remove a skill from the authorized organization’s saved library. Any current member may remove a saved entry. The public immutable listing and its files remain available. Requires an idempotency key."
        }
      ]
    },
    {
      "id": "stories",
      "label": "Stories, scripts & collaboration",
      "tools": [
        {
          "name": "puppetto_accept_story_collaborator_invite",
          "title": "Accept Story Collaborator Invite",
          "description": "Accept a user-bound story invitation using verified OAuth identity. Email-only invitations use the web acceptance URL; collaborator-only OAuth access depends on credential support."
        },
        {
          "name": "puppetto_add_story_beat",
          "title": "Add Story Beat",
          "description": "Add one editable beat/node to a storyline script, optionally linked to a cast role and source assets."
        },
        {
          "name": "puppetto_archive_story",
          "title": "Archive Story",
          "description": "Archive a story without deleting its script, links, or published snapshot. Requires owner permission. Restore before further edits. Does not cancel external jobs."
        },
        {
          "name": "puppetto_convert_story_text",
          "title": "Convert Story Text",
          "description": "Import exactly the metadata text accepted in a preview into a script beat. Retains unrelated metadata and the source text. Repeating conversion of identical source field/text returns the original node without duplication."
        },
        {
          "name": "puppetto_create_story",
          "title": "Create Story",
          "description": "Create a storyline/script for the authorized organization. Requires a member- or admin-linked organization API key."
        },
        {
          "name": "puppetto_create_story_suggestion",
          "title": "Create Story Suggestion",
          "description": "Propose script event changes for review without applying them to the draft. Reviewer access required."
        },
        {
          "name": "puppetto_create_story_with_initial_cast",
          "title": "Create Story With Initial Cast",
          "description": "Create a storyline/script and optional starter cast roles. Cast entries can reuse characterId or create starter characters from characterName/notes."
        },
        {
          "name": "puppetto_decide_story_suggestion",
          "title": "Decide Story Suggestion",
          "description": "Approve or reject a pending suggestion atomically. Repeated approval never appends its events twice."
        },
        {
          "name": "puppetto_delete_story",
          "title": "Delete Story",
          "description": "Delete a storyline/script. Defaults to a soft delete/archive; hardDelete permanently removes the story and requires admin access."
        },
        {
          "name": "puppetto_edit_story",
          "title": "Edit Story",
          "description": "Atomically create, update, move, remove, restore, assign roles, and link or unlink references. Use clientKey references for a beat created earlier in this batch. after:null moves to the start; omitted create.after appends. Clear text or role with explicit null. All edits roll back on failure. Does not publish or generate paid media."
        },
        {
          "name": "puppetto_get_story_bundle",
          "title": "Get Story Bundle",
          "description": "Get a storyline/script bundle with story settings, cast roles, nodes, events, suggestions, collaborators, and latest replay."
        },
        {
          "name": "puppetto_get_story_generation_package",
          "title": "Get Story Generation Package",
          "description": "Prepare generation inputs without executing providers. Set published to read the frozen package; omitted uses the draft. Explicit character pins use immutable database profile, voice and tracked image snapshots; missing legacy snapshots or archived characters block generation."
        },
        {
          "name": "puppetto_invite_story_collaborator",
          "title": "Invite Story Collaborator",
          "description": "Create a story-scoped invitation and return its acceptance URL. An owner role grants publication and collaborator management for this story. Does not grant organization membership or send email. Current owner access required."
        },
        {
          "name": "puppetto_list_stories",
          "title": "List Stories",
          "description": "List storylines/scripts for the authorized organization with cast and pending suggestion counts."
        },
        {
          "name": "puppetto_list_story_cast",
          "title": "List Story Cast",
          "description": "List story cast with mutation IDs, current story revision and an explicit cursor."
        },
        {
          "name": "puppetto_list_story_collaborators",
          "title": "List Story Collaborators",
          "description": "List story collaborators with mutation IDs, current story revision and an explicit cursor."
        },
        {
          "name": "puppetto_list_story_suggestions",
          "title": "List Story Suggestions",
          "description": "List story suggestions with mutation IDs, current story revision and an explicit cursor."
        },
        {
          "name": "puppetto_preview_story_text_conversion",
          "title": "Preview Story Text Conversion",
          "description": "Preview importing one top-level metadata text field as a beat. Does not modify metadata or script. Supply the returned sourceHash to the conversion command."
        },
        {
          "name": "puppetto_publish_story_version",
          "title": "Publish Story Version",
          "description": "Publish an immutable story version atomically with its event, cast and generation snapshot, and publication pointer. Draft edits remain separate. Owner access required."
        },
        {
          "name": "puppetto_read_story_state",
          "title": "Read Story State",
          "description": "Read current revision and ordered beats, optionally including removed beats or replaying an event/time/published boundary. Missing or archived media remains identified by ID with availability; current reference rows may differ from historical node references."
        },
        {
          "name": "puppetto_remove_story_cast_role",
          "title": "Remove Story Cast Role",
          "description": "Remove an unused story cast role. Unassign the role from active nodes first."
        },
        {
          "name": "puppetto_restore_story",
          "title": "Restore Story",
          "description": "Restore an archived story and its prior draft/published state. Requires owner permission. This restores archival state, not deleted data."
        },
        {
          "name": "puppetto_save_story_cast_role",
          "title": "Save Story Cast Role",
          "description": "Create or edit a story cast role, including organization-scoped character, voice and character version pin (version zero is valid). Advances the story revision."
        },
        {
          "name": "puppetto_story_history",
          "title": "Story History",
          "description": "Read immutable story events in event-index order with a continuation cursor. Use nextCursor as afterEventIndex."
        },
        {
          "name": "puppetto_update_story",
          "title": "Update Story",
          "description": "Update story settings and metadata for a storyline/script, including title, slug, publication status, visibility, public contribution settings, logline, metadata, and script settings."
        },
        {
          "name": "puppetto_update_story_collaborator",
          "title": "Update Story Collaborator",
          "description": "Change an active collaborator role or revoke story access and all related invites. Granting owner permits publication and collaborator management for this story, without granting organization membership. Current owner access required."
        },
        {
          "name": "puppetto_update_story_script",
          "title": "Update Story Script",
          "description": "Append or replace editable script beats for a storyline. Provide ordered beats for structured edits, or script text for a single replacement scene."
        }
      ]
    },
    {
      "id": "suggestions",
      "label": "Content suggestions",
      "tools": [
        {
          "name": "puppetto_decide_content_suggestion",
          "title": "Decide Content Suggestion",
          "description": "Admin-only revisioned acceptance or rejection. A prepared calendar acceptance atomically creates one DRAFT via the canonical P transaction command, preserves provenance and links its intended campaign via canonical C using expectedCampaignRevision. Rejecting creates no post. Product and trend-campaign acceptance remain unsupported by this draft command. Never schedules publication or starts external generation."
        },
        {
          "name": "puppetto_get_content_suggestion",
          "title": "Get Content Suggestion",
          "description": "Read a scoped native suggestion, its frozen calendar provenance, prepared draft copy and committed acceptance/rejection result. No publication or provider calls."
        },
        {
          "name": "puppetto_list_calendar_suggestions",
          "title": "List Calendar Suggestions",
          "description": "Inspect canonical CalendarSuggestionService recommendations from current curated/imported trends and native platform-fit rules. Read-only, no LLM or provider calls. Prepare a returned suggestion ID before deciding it."
        },
        {
          "name": "puppetto_list_content_suggestions",
          "title": "List Content Suggestions",
          "description": "Read persisted native suggestions and their revisions, source snapshots and decision IDs. Does not seed or expire suggestions as a side effect. Native product/campaign adoption gaps are explicitly labeled."
        },
        {
          "name": "puppetto_prepare_calendar_suggestion",
          "title": "Prepare Calendar Suggestion",
          "description": "Admin-only durable preparation of a read-derived calendar suggestion. Reuses the native calendar generator deterministic fallback with external providers disabled. Freezes source provenance, draft copy and optional intended campaign. Reuses the same source/campaign record under retries; no post, media or publishing job is created."
        }
      ]
    },
    {
      "id": "workflows",
      "label": "Workflows & execution",
      "tools": [
        {
          "name": "puppetto_control_workflow_v2",
          "title": "Control Workflow V2",
          "description": "Durably accept resume, retry_node, or supported cancellation; advance through existing asset/post services after the intent commits. Read execution details for observed outcome and explicit refusals. Retry only failed nodes. Post retry requires selected integrationId. Running provider cancellation can be unsupported. Live control can schedule approved content or retry a known-safe paid job; test mode performs neither effect."
        },
        {
          "name": "puppetto_create_workflow_v2",
          "title": "Create Workflow V2",
          "description": "Create and validate a DAG with unique IDs and existing edge dependencies. Actions: pure value, canonical asset generation with an estimate limit, observe an existing asset job, or schedule an existing approved post through its canonical publishing service."
        },
        {
          "name": "puppetto_estimate_workflow_v2",
          "title": "Estimate Workflow V2",
          "description": "Return zero cost for test mode and pure local work. Live provider estimates are explicitly unavailable rather than falsely reporting zero or guaranteeing credits."
        },
        {
          "name": "puppetto_get_workflow",
          "title": "Get Workflow",
          "description": "Get a workflow by ID for the authorized organization."
        },
        {
          "name": "puppetto_get_workflow_execution_v2",
          "title": "Get Workflow Execution V2",
          "description": "Read persisted graph version, execution revision, node checkpoints, operation intent, errors, result and cancellation capability. Completed nodes are retained across runtime restart and graph edits."
        },
        {
          "name": "puppetto_get_workflow_graph_v2",
          "title": "Get Workflow Graph V2",
          "description": "Read an identifiable immutable graph revision, or the current version. Legacy graphs remain readable; unsupported actions require explicit graph replacement before durable execution."
        },
        {
          "name": "puppetto_get_workflow_readiness",
          "title": "Get Workflow Readiness",
          "description": "Validate graph actions and tenant-scoped asset/post readiness. Test mode simulates node effects and sends no real generation or publishing work."
        },
        {
          "name": "puppetto_list_workflows",
          "title": "List Workflows",
          "description": "List workflows for the authorized organization."
        },
        {
          "name": "puppetto_list_workflows_page",
          "title": "List Workflows Page",
          "description": "List current organization graphs with public IDs and authoring revisions. Stable UUID pagination."
        },
        {
          "name": "puppetto_start_workflow_v2",
          "title": "Start Workflow V2",
          "description": "Persist an execution pinned to the expected graph revision. Explicit mode is required. Test mode never invokes live job or publishing ports; live mode uses existing services. Call workflow control to advance, then read execution details."
        },
        {
          "name": "puppetto_trigger_workflow",
          "title": "Trigger Workflow",
          "description": "Create a pending workflow execution for the authorized organization."
        },
        {
          "name": "puppetto_update_workflow_graph_v2",
          "title": "Update Workflow Graph V2",
          "description": "Replace a graph using its expected revision and durable retry key. Rejects cycles and missing dependencies. Existing executions retain their pinned graph, version and completed effects."
        }
      ]
    }
  ]
}
