feat: clarify format discovery workflow and tool relationship (#64)

Addresses confusion about the purpose of list_creative_formats and its relationship with get_products.

Key changes:
- Restructure Creative Lifecycle to lead with format discovery workflow
- Add format_ids parameter to list_creative_formats for reverse workflow support
- Document both inventory-first and creative-first discovery approaches
- Move workflow discussion from tool docs to Creative Lifecycle page
- Clarify synergistic relationship between get_products and list_creative_formats

The Creative Lifecycle now properly explains the fundamental question: "How do I figure out what creative formats I need to create?" before diving into library management details.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Claude <[email protected]>

Author: bokelley

docs/media-buy/creative-formats.md

@@ -6,6 +6,8 @@ title: Creative Formats
 
 All creative formats have a unique identifier and specify delivery methods. Formats can require either a single asset or multiple assets for rich media experiences.
 
+**For the complete workflow on format discovery, see the [Creative Lifecycle](./creative-lifecycle#phase-1-format-discovery) documentation.**
+
 ## Standard vs Custom Formats
 
 AdCP defines two categories of formats:

docs/media-buy/creative-lifecycle.md

@@ -4,7 +4,74 @@ title: Creative Lifecycle
 
 # Creative Lifecycle
 
-AdCP provides a comprehensive centralized creative library for managing the entire lifecycle of creative assets. This document explains the conceptual model and workflow for creative management using the centralized library approach.
+AdCP manages the complete creative lifecycle from initial format discovery through ongoing optimization. This document covers the three main phases: discovering requirements, producing assets, and managing the creative library.
+
+## Phase 1: Format Discovery
+
+Before creating any creative assets, you need to understand **what formats are required**. AdCP provides two complementary tools that work together:
+
+### The Discovery Workflow
+
+**`get_products`** finds advertising inventory that matches your campaign needs, while **`list_creative_formats`** provides the detailed creative specifications for the formats those products require.
+
+#### Two Common Approaches:
+
+**1. Inventory-First** - "What products match my campaign?"
+```javascript
+// Find products for your campaign
+const products = await get_products({
+  brief: "Premium video inventory for sports fans",
+  promoted_offering: "Nike Air Max 2024"
+});
+// Products return: formats: ["video_15s_hosted", "homepage_takeover_2024"]
+
+// Get creative specs for those specific formats
+const formatSpecs = await list_creative_formats({
+  format_ids: products.products.flatMap(p => p.formats)
+});
+// Now you know: video_15s_hosted needs MP4 H.264, 15s, 1920x1080
+//                homepage_takeover_2024 needs hero image + logo + headline
+```
+
+**2. Creative-First** - "What video formats does this publisher support?"
+```javascript
+// Browse available video formats
+const videoFormats = await list_creative_formats({
+  type: "video",
+  category: "standard"
+});
+// Returns: video_15s_hosted, video_30s_vast, video_vertical_15s, etc.
+
+// Find products supporting your creative capabilities
+const products = await get_products({
+  promoted_offering: "Nike Air Max 2024",
+  filters: {
+    format_ids: ["video_15s_hosted", "video_30s_vast"]
+  }
+});
+// Returns only products that accept these specific formats
+```
+
+### Why Both Tools Matter
+
+- **Without `list_creative_formats`**: Format IDs from products are meaningless strings
+- **Without `get_products`**: You don't know which formats actually have available inventory
+- **Together**: You understand both what's available AND what's required
+
+**Common discovery patterns:**
+- **Campaign planning**: Inventory-first approach to find the right audience, then build creative
+- **Production planning**: Creative-first approach to understand capabilities, then find compatible inventory
+- **Cross-publisher campaigns**: Use standard formats for maximum reach across multiple publishers
+
+---
+
+## Phase 2: Creative Production
+
+Once you understand format requirements, create the actual creative assets according to the specifications discovered in Phase 1.
+
+---
+
+## Phase 3: Creative Library Management
 
 ## The Creative Library Model
 

docs/media-buy/tasks/get_products.md

@@ -7,7 +7,7 @@ Discover available advertising products based on campaign requirements, using na
 
 **Response Time**: ~60 seconds (inference/RAG with back-end systems)
 
-**Format Discovery**: Products return format references (IDs only). Use [`list_creative_formats`](./list_creative_formats) to get full format specifications including requirements, file types, and dimensions.
+**Format Discovery**: Products return format references (IDs only). Use [`list_creative_formats`](./list_creative_formats) to get full format specifications. **See [Creative Lifecycle](../creative-lifecycle#phase-1-format-discovery) for the complete workflow.**
 
 **Request Schema**: [`/schemas/v1/media-buy/get-products-request.json`](/schemas/v1/media-buy/get-products-request.json)  
 **Response Schema**: [`/schemas/v1/media-buy/get-products-response.json`](/schemas/v1/media-buy/get-products-response.json)

docs/media-buy/tasks/list_creative_formats.md

@@ -5,7 +5,9 @@ sidebar_position: 2
 
 # list_creative_formats
 
-Discover all supported creative formats in the system.
+Discover all supported creative formats in the system. 
+
+**See [Creative Lifecycle](../creative-lifecycle#phase-1-format-discovery) for the complete workflow on how this tool works with `get_products` for format discovery.**
 
 **Response Time**: ~1 second (simple database lookup)
 
@@ -19,6 +21,7 @@ Discover all supported creative formats in the system.
 | `type` | string | No | Filter by format type (e.g., `"audio"`, `"video"`, `"display"`) |
 | `category` | string | No | Filter by category (`"standard"` or `"custom"`) |
 | `standard_only` | boolean | No | Only return standard formats (deprecated, use `category: "standard"`) |
+| `format_ids` | string[] | No | Filter by specific format IDs (e.g., from `get_products` response) |
 
 ## Response (Message)
 
@@ -60,6 +63,7 @@ The message is returned differently in each protocol:
 - **requirements**: Format-specific requirements (varies by format type)
 - **assets_required**: Array of required assets with `asset_role` identifiers
 
+
 ## Protocol-Specific Examples
 
 The AdCP payload is identical across protocols. Only the request/response wrapper differs.
@@ -138,6 +142,81 @@ The AdCP payload is identical across protocols. Only the request/response wrappe
 }
 ```
 
+### Example 3: Reverse Workflow (Product-First)
+
+#### MCP Request - Get specs for specific format IDs
+```json
+{
+  "tool": "list_creative_formats",
+  "arguments": {
+    "format_ids": ["video_15s_hosted", "video_30s_vast", "display_300x250"]
+  }
+}
+```
+
+#### MCP Response
+```json
+{
+  "message": "Found 3 specific formats. These are the exact creative requirements for your available inventory.",
+  "formats": [
+    {
+      "format_id": "video_15s_hosted",
+      "name": "15-Second Hosted Video",
+      "type": "video",
+      "category": "standard",
+      "duration": "15s",
+      "accepts_3p_tags": false,
+      "assets_required": [
+        {
+          "asset_id": "video_file",
+          "asset_type": "video",
+          "asset_role": "hero_video",
+          "required": true,
+          "requirements": {
+            "duration": "15s",
+            "format": "MP4 H.264",
+            "resolution": ["1920x1080", "1280x720"],
+            "max_file_size_mb": 30
+          }
+        }
+      ]
+    },
+    {
+      "format_id": "video_30s_vast",
+      "name": "30-Second VAST Video", 
+      "type": "video",
+      "category": "standard",
+      "duration": "30s",
+      "accepts_3p_tags": true,
+      "delivery": {
+        "method": "VAST",
+        "versions": ["3.0", "4.0", "4.1", "4.2"]
+      }
+    },
+    {
+      "format_id": "display_300x250",
+      "name": "Medium Rectangle",
+      "type": "display",
+      "category": "standard",
+      "dimensions": "300x250",
+      "accepts_3p_tags": false,
+      "assets_required": [
+        {
+          "asset_id": "banner_image",
+          "asset_type": "image",
+          "asset_role": "hero_image",
+          "required": true,
+          "width": 300,
+          "height": 250,
+          "acceptable_formats": ["jpg", "png", "gif"],
+          "max_file_size_kb": 200
+        }
+      ]
+    }
+  ]
+}
+```
+
 ### MCP Response
 
 **Message:**
@@ -368,14 +447,16 @@ I found 15 display formats including standard IAB sizes and innovative formats l
 
 ## Usage Notes
 
-- Use this tool to understand what creative formats are supported before creating assets
-- Standard formats follow IAB specifications for maximum compatibility
-- Non-standard formats may offer enhanced features but have limited inventory
-- For composite formats (like carousels), check `assets_required` for all needed components
-- Requirements vary by format type:
-  - Audio formats specify duration, file types, and bitrate
-  - Video formats include resolution, aspect ratio, and codec requirements
-  - Display formats define dimensions, file types, and size limits
+- **Primary use case**: Get creative specifications after `get_products` returns format IDs
+- **Format IDs are just strings** until you get their specifications from this tool
+- **Standard formats** follow IAB specifications and work across multiple publishers
+- **Custom formats** (like "homepage_takeover") are publisher-specific with unique requirements  
+- **The `format_ids` parameter** is the most efficient way to get specs for specific formats returned by products
+- **Asset requirements vary by format type**:
+  - Audio formats: duration, file types, bitrate specifications
+  - Video formats: resolution, aspect ratio, codec, delivery method
+  - Display formats: dimensions, file types, file size limits
+  - Rich media formats: multiple assets with specific roles and requirements
 
 ## Implementation Guide
 

static/schemas/v1/media-buy/list-creative-formats-request.json

@@ -19,6 +19,18 @@
     "standard_only": {
       "type": "boolean",
       "description": "Only return IAB standard formats"
+    },
+    "category": {
+      "type": "string",
+      "description": "Filter by format category",
+      "enum": ["standard", "custom"]
+    },
+    "format_ids": {
+      "type": "array",
+      "description": "Filter by specific format IDs (e.g., from get_products response)",
+      "items": {
+        "type": "string"
+      }
     }
   },
   "additionalProperties": false