ivon-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{ivon_cli-0.2.0/src/ivon_cli.egg-info → ivon_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ivon-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: ivon CLI — Meta Ads connector commands + MCP access for the ivon autonomous marketing team
 Author: ivon (LemonTree Media)
 License: Proprietary

ivon_cli-0.2.2/src/ivon_cli/__init__.py

@@ -0,0 +1,3 @@
+"""ivon CLI."""
+
+__version__ = "0.2.2"

{ivon_cli-0.2.0 → ivon_cli-0.2.2}/src/ivon_cli/_tools_snapshot.json

@@ -2,7 +2,7 @@
   "tools": [
     {
       "name": "compute_image_crops",
-      "description": "Compute centered placement crops for an image (no API call).\n\n    Returns an image_crops spec \u2014 {crop_key: [[left, top], [right, bottom]]}\n    \u2014 usable directly in create_ad_creative. Supported keys: 100x100\n    (square), 191x100 (landscape link), 100x72 (right column), 400x500\n    (4:5 mobile feed), 90x160 (9:16 stories).\n\n    Args:\n        image_width: Source image width in pixels.\n        image_height: Source image height in pixels.\n        access_token: Unused (kept for tool-call uniformity).\n        crop_keys: Subset of crop keys to compute (default: all).\n    ",
+      "description": "Compute centered placement crop boxes for an image (pure math \u2014 no\n    Meta API call, works for any image dimensions). Run this before\n    create_ad_creative when you want explicit per-placement crops instead\n    of Meta's auto-crop.\n\n    Args:\n        image_width: Source image width in pixels.\n        image_height: Source image height in pixels.\n        access_token: Unused (kept for tool-call uniformity).\n        crop_keys: Subset of crop keys to compute (default: all five) \u2014\n            100x100 (1:1 square: feeds, carousels), 191x100 (landscape\n            link ads), 100x72 (right column), 400x500 (4:5 mobile feed),\n            90x160 (9:16 stories/reels).\n\n    Returns:\n        JSON {\"image_crops\": {key: [[left, top], [right, bottom]]}} \u2014\n        pass image_crops directly to create_ad_creative; unknown keys are\n        reported under \"skipped\".\n    ",
       "inputSchema": {
         "properties": {
           "image_width": {
@@ -51,7 +51,7 @@
     },
     {
       "name": "create_ad",
-      "description": "Create an ad linking an existing creative into an ad set\n    (created PAUSED by default).\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        name: Ad name.\n        adset_id: Parent ad set id.\n        creative_id: Existing creative id (see create_ad_creative).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        status: ACTIVE or PAUSED.\n        bid_amount: Per-ad bid override in minor units.\n        tracking_specs: Extra tracking specs, e.g.\n            [{\"action.type\": [\"offsite_conversion\"], \"fb_pixel\": [\"<pixel_id>\"]}].\n    ",
+      "description": "Create an ad \u2014 the final step of the launch chain \u2014 by linking an\n    existing creative into an ad set. Created PAUSED by default; nothing\n    spends until activated. Returns the new ad id.\n\n    Common failures bubble up from earlier steps: an ON_POST engagement ad\n    set missing promoted_object fails with subcode 1885154 (recreate the\n    ad set), and an asset-customization creative without a link fails with\n    1885800 (recreate the creative with link_url).\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        name: Ad name.\n        adset_id: Parent ad set id (from create_adset).\n        creative_id: Creative id (from create_ad_creative).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        status: ACTIVE or PAUSED (default PAUSED).\n        bid_amount: Per-ad bid override in minor units (cents).\n        tracking_specs: Extra tracking specs, e.g.\n            [{\"action.type\": [\"offsite_conversion\"], \"fb_pixel\": [\"<pixel_id>\"]}].\n\n    Returns:\n        JSON with the created ad id. The ad then goes through Meta review\n        (effective_status PENDING_REVIEW) before it can deliver.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {
@@ -126,7 +126,7 @@
     },
     {
       "name": "create_ad_creative",
-      "description": "Create an ad creative.\n\n    Three modes, picked from the arguments you pass:\n\n    1. Existing post: pass object_story_id (\"<page_id>_<post_id>\").\n    2. Single image/video: pass page_id plus image_hash (from\n       upload_ad_image) or video_id, with message/headline/description/\n       link_url/call_to_action_type.\n    3. Flexible/dynamic (asset feed): pass page_id plus plural lists \u2014\n       images/image_hashes/videos/messages/headlines/descriptions \u2014 and\n       optionally ad_formats (e.g. [\"SINGLE_IMAGE\"]),\n       asset_customization_rules, or dynamic_creative_spec.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        name: Creative name (defaults to the headline or \"ivon creative\").\n        page_id: Facebook Page identity the ad runs under (required for\n            modes 2 and 3).\n        instagram_actor_id: Instagram account id to pair with the Page.\n        image_hash: Image hash from upload_ad_image (single-image mode).\n        video_id: Video id (single-video mode).\n        thumbnail_url: Video thumbnail image URL.\n        message: Primary text.\n        headline: Headline (link_data \"name\").\n        description: Link description.\n        link_url: Destination URL.\n        caption: Display caption shown with the link.\n        call_to_action_type: LEARN_MORE, SHOP_NOW, SIGN_UP, CALL_NOW, \u2026\n        image_crops: Placement crop spec, e.g. {\"100x100\": [[0,0],[500,500]]}\n            (see compute_image_crops).\n        object_story_id: Existing post id to promote (mode 1).\n        images / image_hashes / videos / messages / headlines / descriptions:\n            Asset lists for flexible creatives (strings or Graph asset dicts).\n        ad_formats: Asset-feed ad formats, e.g. [\"SINGLE_IMAGE\", \"SINGLE_VIDEO\"].\n        asset_customization_rules: Per-placement asset rules.\n        optimization_type: Asset-feed optimization type (e.g. PLACEMENT).\n        dynamic_creative_spec: Extra dynamic-creative configuration merged\n            into the asset feed spec.\n        lead_gen_form_id: Lead form id \u2014 wires the CTA to the form.\n        phone_number: Click-to-call number (E.164) \u2014 wires a CALL_NOW CTA.\n        url_tags: Tracking query string appended to landing URLs.\n        event_id: Facebook event id \u2014 used as the link destination when no\n            link_url is given.\n        reminder_data: Reminder-ad configuration (passed through to Graph).\n        facebook_branded_content: {\"sponsor_page_id\": \"...\"} for branded content.\n        instagram_branded_content: Branded-content config (passed through).\n        creative_features_spec: Advantage+ enhancement spec (placed under\n            degrees_of_freedom_spec).\n        disable_all_enhancements: Opt out of standard Advantage+ enhancements.\n    ",
+      "description": "Create an ad creative \u2014 the content (image/video + text + CTA + link)\n    an ad delivers. Step 4 of the launch chain: upload_ad_image \u2192\n    create_ad_creative \u2192 create_ad (binds it to an ad set). Returns the new\n    creative id. Content is effectively immutable once the ad delivers; to\n    change a live ad, create a new creative and swap it in via update_ad.\n\n    Three modes, picked from the arguments you pass:\n\n    1. Existing post: pass object_story_id (\"<page_id>_<post_id>\") to\n       promote a published organic post \u2014 no page_id/image/video needed.\n    2. Single image/video: pass page_id plus image_hash (from\n       upload_ad_image) or video_id, with message/headline/description/\n       link_url/call_to_action_type.\n    3. Flexible/dynamic (asset feed): pass page_id plus plural lists \u2014\n       images/image_hashes/videos/messages/headlines/descriptions \u2014 and\n       optionally ad_formats (e.g. [\"SINGLE_IMAGE\"]),\n       asset_customization_rules (different assets per placement, e.g. 1:1\n       feed image + 9:16 Story video), optimization_type, or\n       dynamic_creative_spec.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        name: Creative name (defaults to the headline or \"ivon creative\").\n        page_id: Facebook Page identity the ad runs under \u2014 required for\n            modes 2 and 3. Find one with get_account_pages.\n        instagram_actor_id: Instagram account id to pair with the Page for\n            Instagram placements. For video creatives Meta additionally\n            requires ad_formats=[\"SINGLE_VIDEO\"] (i.e. use the asset-feed\n            mode) or it rejects with \"object_story_spec ill formed\"\n            (code 1443048).\n        image_hash: Image hash from upload_ad_image (single-image mode).\n        video_id: Video id (single-video mode). A freshly uploaded video\n            needs a few seconds to transcode \u2014 if creation fails or the\n            thumbnail looks like a processing placeholder, poll\n            get_ad_video until ready or pass thumbnail_url explicitly.\n        thumbnail_url: Video thumbnail image URL (any public image URL);\n            image_hash is used as the thumbnail when this is omitted.\n        message: Primary text (the main ad copy above the media).\n        headline: Headline (link_data \"name\") shown next to the CTA.\n        description: Secondary text shown under the headline.\n        link_url: Destination URL. Required for link creatives. Also\n            required when lead_gen_form_id is combined with\n            asset_customization_rules \u2014 Meta demands a URL on the creative\n            even though the CTA opens the form (error 1885800 otherwise at\n            create_ad time); any valid URL such as the site root works.\n        caption: Display URL shown in the ad (e.g. \"example.com/sale\");\n            Meta derives it from link_url when omitted.\n        call_to_action_type: CTA button enum. Free-form values are rejected\n            with code 100 \u2014 use a documented one: LEARN_MORE, SHOP_NOW,\n            SIGN_UP, SUBSCRIBE, GET_QUOTE, CONTACT_US, DOWNLOAD, GET_OFFER,\n            APPLY_NOW, CALL_NOW, MESSAGE_PAGE, SEE_MENU, ORDER_NOW, BUY_NOW,\n            WHATSAPP_MESSAGE, GET_DIRECTIONS, BUY_TICKETS, EVENT_RSVP,\n            BOOK_TRAVEL, BOOK_NOW (for reservations use BOOK_NOW \u2014 there is\n            no MAKE_RESERVATION enum). Defaults when omitted: SIGN_UP with\n            lead_gen_form_id, CALL_NOW with phone_number, else LEARN_MORE.\n        image_crops: Per-ratio crop boxes for the single image, keyed by\n            Meta crop key: \"100x100\" (1:1 feed/search), \"191x100\"\n            (landscape link), \"100x72\" (right column), \"400x500\" (4:5\n            mobile feed), \"90x160\" (9:16 Stories). Format\n            {\"100x100\": [[x1,y1],[x2,y2]]} in source pixels, origin\n            top-left. Run compute_image_crops first for centered boxes;\n            omit to let Meta auto-crop.\n        object_story_id: Existing post id to promote (mode 1), formatted\n            \"<page_id>_<post_id>\". Combine with asset_customization_rules\n            to attach a 9:16 Story/Reels video while the post serves in\n            feed.\n        images / image_hashes / videos / messages / headlines / descriptions:\n            Asset lists for mode 3. Entries are plain strings/hashes/ids, or\n            Graph asset dicts when labels are needed \u2014 images:\n            {\"hash\": \u2026, \"adlabels\": [{\"name\": \"label\"}]}, videos:\n            {\"video_id\": \u2026, \"thumbnail_url\": \u2026}, texts: {\"text\": \u2026,\n            \"adlabels\": [\u2026]}. Labels are how asset_customization_rules\n            reference specific assets.\n        ad_formats: Asset-feed formats: AUTOMATIC_FORMAT (flexible),\n            SINGLE_IMAGE, SINGLE_VIDEO, CAROUSEL.\n        asset_customization_rules: Per-placement asset assignment. Each rule\n            pairs a targeting of placements with a customization_spec that\n            references asset labels. Every label referenced must exist on\n            an asset entry or Meta fails with \"Adcreative Create Failed\"\n            (subcode 1487390).\n        optimization_type: PLACEMENT (per-placement assets via the rules\n            above) or DEGREES_OF_FREEDOM (Advantage+ auto-combination).\n            Caution with DEGREES_OF_FREEDOM + multiple image hashes: Meta\n            accepts them but serves only ONE image \u2014 for true multi-image\n            rotation use dynamic creative (is_dynamic_creative=true on the\n            ad set) instead.\n        dynamic_creative_spec: Extra dynamic-creative configuration merged\n            into the asset feed spec (the ad set must set\n            is_dynamic_creative=true).\n        lead_gen_form_id: Instant Form id \u2014 wires the CTA to open the lead\n            form instead of a website.\n        phone_number: Click-to-call number in E.164 format (e.g.\n            \"+18005551234\") \u2014 wires a CALL_NOW CTA (sent as a tel: link).\n        url_tags: Tracking query string appended to landing URLs, e.g.\n            \"utm_source=facebook&utm_medium=cpc&utm_campaign=spring\".\n        event_id: Facebook event id \u2014 its event page becomes the link\n            destination when no link_url is given (pair with EVENT_RSVP or\n            BUY_TICKETS CTAs).\n        reminder_data: Instagram Reminder Ads config: {\"event_name\": str,\n            \"start_time\": unix_seconds, \"end_time\": unix_seconds}. The ad\n            set must use optimization_goal=REMINDERS_SET.\n        facebook_branded_content: {\"sponsor_page_id\": \"<page_id>\"} for\n            partnership ads where a brand sponsors a creator's content\n            (page_id stays the creator's Page).\n        instagram_branded_content: {\"sponsor_id\": \"<ig_user_id>\"} \u2014\n            Instagram partnership-ad equivalent (passed through).\n        creative_features_spec: Advantage+ enhancement opt-ins/outs, e.g.\n            {\"image_touchups\": {\"enroll_status\": \"OPT_IN\"}} (placed under\n            degrees_of_freedom_spec).\n        disable_all_enhancements: Opt out of standard Advantage+\n            enhancements for full creative control.\n\n    Returns:\n        JSON with the created creative id \u2014 pass it to create_ad.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {
@@ -572,7 +572,7 @@
     },
     {
       "name": "create_adset",
-      "description": "Create an ad set (created PAUSED by default).\n\n    Budgets are minor units (cents). Unless the campaign uses CBO, give the\n    ad set a daily_budget or lifetime_budget (lifetime also needs end_time).\n    A targeting spec is required by Meta, e.g.\n    {\"geo_locations\": {\"countries\": [\"US\"]}, \"age_min\": 18}.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        campaign_id: Parent campaign id.\n        name: Ad set name.\n        optimization_goal: e.g. LINK_CLICKS, LANDING_PAGE_VIEWS, REACH,\n            IMPRESSIONS, OFFSITE_CONVERSIONS, LEAD_GENERATION.\n        billing_event: e.g. IMPRESSIONS (most common), LINK_CLICKS.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        status: ACTIVE or PAUSED.\n        daily_budget: Daily budget in minor units.\n        lifetime_budget: Lifetime budget in minor units (requires end_time).\n        bid_amount: Bid cap/target in minor units.\n        bid_strategy: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP.\n        bid_constraints: e.g. {\"roas_average_floor\": 2000}.\n        bid_adjustments: e.g. {\"user_groups\": {...}}.\n        targeting: Full Meta targeting spec (geo_locations, age, interests, \u2026).\n        start_time / end_time: ISO 8601 schedule bounds.\n        promoted_object: e.g. {\"pixel_id\": ..., \"custom_event_type\": \"PURCHASE\"}\n            for conversion goals, or {\"page_id\": ...}.\n        attribution_spec: e.g. [{\"event_type\":\"CLICK_THROUGH\",\"window_days\":7}].\n        destination_type: WEBSITE, APP, MESSENGER, \u2026\n        is_dynamic_creative: Enable dynamic creative for this ad set.\n        frequency_control_specs: e.g. [{\"event\":\"IMPRESSIONS\",\"interval_days\":7,\"max_frequency\":3}].\n        multi_advertiser_ads: Opt in/out of multi-advertiser placements.\n        dsa_beneficiary / dsa_payor: EU DSA transparency strings.\n        regional_regulated_categories / regional_regulation_identities:\n            Regional regulation declarations (e.g. financial ads).\n    ",
+      "description": "Create an ad set (created PAUSED by default) \u2014 step 3 of the launch\n    chain, between create_campaign and create_ad. The ad set owns targeting,\n    budget (unless the campaign uses CBO), schedule, optimization goal, and\n    placements. Returns the new ad set id.\n\n    Budgets are minor units (cents). If the parent campaign already has a\n    budget (CBO), do NOT set one here \u2014 Meta allows budgets at exactly one\n    level. Otherwise give the ad set a daily_budget or lifetime_budget\n    (lifetime also needs end_time). A targeting spec is required, e.g.\n    {\"geo_locations\": {\"countries\": [\"US\"]}, \"age_min\": 18}.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        campaign_id: Parent campaign id (from create_campaign/get_campaigns).\n        name: Ad set name.\n        optimization_goal: What delivery optimizes for. Valid values depend\n            on the campaign objective (and destination_type):\n            OUTCOME_TRAFFIC: LINK_CLICKS, LANDING_PAGE_VIEWS, IMPRESSIONS,\n                REACH.\n            OUTCOME_SALES: OFFSITE_CONVERSIONS, VALUE, CONVERSATIONS,\n                LINK_CLICKS, IMPRESSIONS, REACH.\n            OUTCOME_LEADS: LEAD_GENERATION, QUALITY_LEAD (forms),\n                QUALITY_CALL (calls), OFFSITE_CONVERSIONS, LINK_CLICKS.\n            OUTCOME_AWARENESS: REACH, IMPRESSIONS, AD_RECALL_LIFT, THRUPLAY.\n            OUTCOME_APP_PROMOTION: APP_INSTALLS, VALUE.\n            OUTCOME_ENGAGEMENT: depends on destination_type \u2014 WEBSITE:\n                OFFSITE_CONVERSIONS, LANDING_PAGE_VIEWS, LINK_CLICKS,\n                IMPRESSIONS, REACH \u00b7 ON_POST: POST_ENGAGEMENT, IMPRESSIONS,\n                REACH (also set promoted_object={\"page_id\": \u2026} at creation;\n                it is immutable and create_ad later fails with subcode\n                1885154 without it) \u00b7 ON_VIDEO: THRUPLAY \u00b7 ON_EVENT:\n                EVENT_RESPONSES \u00b7 ON_PAGE: PAGE_LIKES \u00b7 messaging\n                destinations: CONVERSATIONS, LINK_CLICKS.\n        billing_event: How you're charged \u2014 IMPRESSIONS (almost always) or\n            LINK_CLICKS.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        status: ACTIVE or PAUSED (default PAUSED \u2014 nothing spends until you\n            activate). To schedule future delivery, pass a future\n            start_time with status=ACTIVE; effective_status shows SCHEDULED.\n        daily_budget: Daily budget in minor units \u2014 omit when the campaign\n            uses CBO.\n        lifetime_budget: Lifetime budget in minor units (requires end_time)\n            \u2014 omit when the campaign uses CBO.\n        bid_amount: Bid cap/target in minor units. Required by\n            LOWEST_COST_WITH_BID_CAP and COST_CAP; not used by\n            LOWEST_COST_WITH_MIN_ROAS.\n        bid_strategy: LOWEST_COST_WITHOUT_CAP (recommended; no bid_amount),\n            LOWEST_COST_WITH_BID_CAP or COST_CAP (both require bid_amount),\n            or LOWEST_COST_WITH_MIN_ROAS (requires bid_constraints and\n            optimization_goal=VALUE). \"LOWEST_COST\" alone is not valid.\n        bid_constraints: For LOWEST_COST_WITH_MIN_ROAS:\n            {\"roas_average_floor\": target_roas \u00d7 10000}, e.g. 2.0x ROAS \u2192\n            {\"roas_average_floor\": 20000}.\n        bid_adjustments: Bid multipliers per dimension, e.g. {\"user_groups\":\n            {\"user_os\": {\"iOS\": 0.9, \"default\": 1.0}}}. Requires a Meta app\n            allowlist capability \u2014 without it Meta returns OAuthException #3.\n        targeting: Full Meta targeting spec: geo_locations, age_min/age_max,\n            genders, interests (ids from search_interests),\n            custom_audiences, publisher_platforms, \u2026 Build audience size\n            estimates first with estimate_audience_size.\n        start_time / end_time: ISO 8601 bounds (e.g.\n            \"2026-07-01T09:00:00-0700\"). end_time is required with\n            lifetime_budget. Scheduling lives here \u2014 campaigns have no\n            start_time.\n        promoted_object: What's being promoted: {\"pixel_id\": \u2026,\n            \"custom_event_type\": \"PURCHASE\"} for conversion goals,\n            {\"application_id\": \u2026, \"object_store_url\": \u2026} for app installs,\n            {\"page_id\": \u2026} for ON_POST engagement (required + immutable \u2014\n            see optimization_goal).\n        attribution_spec: Conversion attribution windows, e.g.\n            [{\"event_type\": \"CLICK_THROUGH\", \"window_days\": 1}]. event_type:\n            CLICK_THROUGH or VIEW_THROUGH; window_days: 1, 7, or 28.\n            Default 7-day click. Immutable after creation \u2014 set it now or\n            never (update_adset is rejected with error 1504040).\n        destination_type: Where users land: WEBSITE, APP, MESSENGER,\n            WHATSAPP, INSTAGRAM_DIRECT, SHOP_AUTOMATIC, or engagement\n            locations ON_POST / ON_PAGE / ON_EVENT / ON_VIDEO. ON_AD is the\n            OUTCOME_LEADS instant-form destination only \u2014 using it with\n            OUTCOME_ENGAGEMENT is rejected (subcode 1815715).\n        is_dynamic_creative: Enable dynamic creative (required for creatives\n            with dynamic_creative_spec). Immutable after creation.\n        frequency_control_specs: Frequency caps, e.g. [{\"event\":\n            \"IMPRESSIONS\", \"interval_days\": 7, \"max_frequency\": 3}]. Only\n            for OUTCOME_AWARENESS with REACH/THRUPLAY goals, and immutable\n            after creation (error 1815198) \u2014 set at create time.\n        multi_advertiser_ads: Opt in (1) / out (0) of multi-advertiser\n            placements. Top-level param \u2014 not inside targeting.\n        dsa_beneficiary / dsa_payor: Who benefits from / pays for the ads \u2014\n            both required for EU-targeted ad sets (DSA transparency).\n        regional_regulated_categories / regional_regulation_identities:\n            Declarations for regulated regions (e.g. TAIWAN_UNIVERSAL,\n            AUSTRALIA_FINSERV, INDIA_FINSERV, SINGAPORE_UNIVERSAL) plus the\n            matching verified identity ids from Meta Business Settings.\n\n    Returns:\n        JSON with the created ad set id \u2014 pass it to create_ad.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {
@@ -864,7 +864,7 @@
     },
     {
       "name": "create_budget_schedule",
-      "description": "Schedule a temporary budget increase for a campaign (high-demand\n    period), e.g. a weekend sale boost.\n\n    Args:\n        campaign_id: Campaign id.\n        budget_value: Increase amount \u2014 minor units when ABSOLUTE, percent\n            (e.g. 200 = +200%) when MULTIPLIER.\n        budget_value_type: ABSOLUTE or MULTIPLIER.\n        time_start: Unix timestamp when the boost begins.\n        time_end: Unix timestamp when the boost ends.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "Schedule a temporary budget increase for a campaign (Meta \"High\n    Demand Periods\") \u2014 e.g. a weekend sale boost that starts and ends\n    automatically, without manual budget edits. The campaign must have a\n    budget (CBO) for the schedule to apply. This increases spend \u2014\n    confirm amounts and dates with the user first.\n\n    Args:\n        campaign_id: Campaign id.\n        budget_value: Increase amount \u2014 minor units (cents) when ABSOLUTE,\n            percent when MULTIPLIER (e.g. 200 = +200% of the base budget).\n        budget_value_type: ABSOLUTE or MULTIPLIER.\n        time_start: Unix timestamp (seconds) when the boost begins.\n        time_end: Unix timestamp (seconds) when the boost ends.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        JSON with the created budget schedule id.\n    ",
       "inputSchema": {
         "properties": {
           "campaign_id": {
@@ -913,7 +913,7 @@
     },
     {
       "name": "create_campaign",
-      "description": "Create a campaign (created PAUSED by default \u2014 nothing spends until\n    you activate it).\n\n    Budgets are in the account currency's minor units (e.g. cents): pass\n    daily_budget=5000 for $50/day. Set use_adset_level_budgets=true to skip\n    campaign-level budgets and budget each ad set instead.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        name: Campaign name.\n        objective: OUTCOME_TRAFFIC, OUTCOME_SALES, OUTCOME_LEADS,\n            OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, or OUTCOME_APP_PROMOTION.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        status: ACTIVE or PAUSED (default PAUSED).\n        special_ad_categories: Required by Meta for housing/credit/employment/\n            political ads; defaults to [] (none).\n        daily_budget: Campaign daily budget in minor units (CBO).\n        lifetime_budget: Campaign lifetime budget in minor units (CBO).\n        buying_type: AUCTION (default) or RESERVED.\n        bid_strategy: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP,\n            or COST_CAP (used with campaign budgets).\n        bid_cap: Bid cap in minor units (with LOWEST_COST_WITH_BID_CAP).\n        spend_cap: Lifetime spend ceiling in minor units.\n        campaign_budget_optimization: Explicitly toggle CBO.\n        ab_test_control_setups: A/B test configuration.\n        use_adset_level_budgets: Don't set campaign budgets at all.\n    ",
+      "description": "Create a campaign \u2014 step 1 of the launch chain (campaign \u2192 ad set \u2192\n    ad). Picks the objective and the budgeting mode: CBO (budget here on\n    the campaign) or ABO (use_adset_level_budgets=true, budget each ad set\n    instead). Created PAUSED by default \u2014 nothing spends until you\n    activate it. Returns the new campaign id.\n\n    Budgets are in the account currency's minor units (e.g. cents): pass\n    daily_budget=5000 for $50/day. Campaigns do not support start_time \u2014\n    scheduling lives on the ad set.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        name: Campaign name.\n        objective: Outcome-based (ODAX) objective \u2014 exactly one of\n            OUTCOME_TRAFFIC, OUTCOME_SALES, OUTCOME_LEADS,\n            OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_APP_PROMOTION.\n            Legacy names (LINK_CLICKS, CONVERSIONS, BRAND_AWARENESS,\n            APP_INSTALLS, \u2026) are rejected with a 400 \u2014 map them to the\n            outcome equivalents (CONVERSIONS \u2192 OUTCOME_SALES,\n            LINK_CLICKS \u2192 OUTCOME_TRAFFIC, BRAND_AWARENESS \u2192\n            OUTCOME_AWARENESS, LEAD_GENERATION \u2192 OUTCOME_LEADS).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        status: ACTIVE or PAUSED (default PAUSED).\n        special_ad_categories: Legally required for housing, credit,\n            employment, or political/social-issue ads \u2014 e.g. [\"HOUSING\"].\n            Defaults to [] (none). Ask before assuming none applies.\n        daily_budget: Campaign daily budget in minor units (enables CBO).\n        lifetime_budget: Campaign lifetime budget in minor units (CBO).\n        buying_type: AUCTION (default) or RESERVED.\n        bid_strategy: LOWEST_COST_WITHOUT_CAP (default),\n            LOWEST_COST_WITH_BID_CAP, or COST_CAP. Caution: with BID_CAP or\n            COST_CAP every child ad set must set bid_amount.\n        bid_cap: Bid cap in minor units (with LOWEST_COST_WITH_BID_CAP).\n        spend_cap: Lifetime spend ceiling in minor units.\n        campaign_budget_optimization: Explicitly toggle CBO.\n        ab_test_control_setups: A/B test configuration, e.g.\n            [{\"name\": \"Creative A\", \"ad_format\": \"SINGLE_IMAGE\"}].\n        use_adset_level_budgets: True = ABO; no campaign-level budgets are\n            sent, budget each ad set in create_adset.\n\n    Returns:\n        JSON with the created campaign id \u2014 pass it to create_adset.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {
@@ -1062,7 +1062,7 @@
     },
     {
       "name": "estimate_audience_size",
-      "description": "Estimate reachable audience size for a targeting spec.\n\n    Pass a full targeting spec, or just interests (names via interest_list\n    or ids via interest_fbid_list) \u2014 interests-only estimates default to a\n    US-wide audience.\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        account_id: Ad account id (required \u2014 estimates are account-scoped).\n        targeting: Full Meta targeting spec.\n        interest_list: Interest names to resolve and estimate.\n        interest_fbid_list: Interest ids to estimate.\n        optimization_goal: Goal the estimate assumes (default REACH).\n    ",
+      "description": "Estimate reachable audience size for a targeting spec \u2014 the\n    pre-flight check before create_adset. Too-narrow audiences deliver\n    poorly; use this to validate a spec and compare variants.\n\n    Pass a full targeting spec, or just interests (names via interest_list\n    or ids via interest_fbid_list) \u2014 interests-only estimates default to a\n    US-wide audience.\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        account_id: Ad account id (required \u2014 estimates are account-scoped).\n        targeting: Full Meta targeting spec, the same shape create_adset\n            takes, e.g. {\"age_min\": 25, \"age_max\": 55, \"geo_locations\":\n            {\"countries\": [\"US\"]}, \"flexible_spec\": [{\"interests\":\n            [{\"id\": \"6003371567474\"}]}]}.\n        interest_list: Interest names to resolve (via search) and estimate.\n        interest_fbid_list: Interest ids to estimate directly.\n        optimization_goal: Goal the estimate assumes \u2014 REACH (default),\n            LINK_CLICKS, IMPRESSIONS, OFFSITE_CONVERSIONS, \u2026.\n\n    Returns:\n        JSON delivery estimate (estimate_ready, users bounds) plus\n        targeting_used echoing the spec that was evaluated \u2014 reuse it in\n        create_adset.\n    ",
       "inputSchema": {
         "properties": {
           "access_token": {
@@ -1144,7 +1144,7 @@
     },
     {
       "name": "fetch",
-      "description": "Fetch full details for a `search` result.\n\n    Args:\n        id: A result id from `search` \u2014 \"account:act_\u2026\" or \"campaign:\u2026\".\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "Fetch full details for a `search` result (the deep-research\n    companion to search). For known ids prefer get_account_info /\n    get_campaign_details directly.\n\n    Args:\n        id: A result id from `search` \u2014 \"account:act_\u2026\" or \"campaign:\u2026\"\n            (a bare id is treated as a campaign).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        JSON document {id, title, text, url, metadata} with the object's\n        details serialized in text.\n    ",
       "inputSchema": {
         "properties": {
           "id": {
@@ -1173,7 +1173,7 @@
     },
     {
       "name": "get_account_info",
-      "description": "Get details for one ad account.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        fields: Comma-separated Graph fields to fetch (defaults to a useful set).\n    ",
+      "description": "Get details for one ad account \u2014 currency, timezone, status, spend\n    totals, and min_daily_budget (the floor Meta enforces on ad set\n    budgets in this account's currency).\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        fields: Comma-separated Graph fields to fetch (defaults to a useful\n            set; pass explicit fields for anything exotic).\n\n    Returns:\n        JSON account object. Monetary values are in the account currency's\n        minor units.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {
@@ -1207,7 +1207,7 @@
     },
     {
       "name": "get_account_pages",
-      "description": "List Facebook Pages usable with this ad account.\n\n    Tries the account's promote_pages edge first; falls back to the pages\n    the connected user manages (me/accounts).\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "List Facebook Pages usable with this ad account. Ads run under a\n    Page identity, so create_ad_creative needs a page_id from here \u2014\n    fetch this before building any creative.\n\n    Tries the account's promote_pages edge first; falls back to the pages\n    the connected user manages (me/accounts).\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        JSON list of Pages (id, name, category, fan_count, link). A\n        \"source\" field notes when the fallback was used.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {
@@ -1236,7 +1236,7 @@
     },
     {
       "name": "get_ad_accounts",
-      "description": "List the ad accounts the connected Facebook user can access.\n\n    Monetary fields (amount_spent, balance, spend_cap) are returned in the\n    account currency's minor units as provided by Meta.\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        user_id: Graph user node to query (default \"me\", the connected user).\n        limit: Maximum number of accounts to return.\n    ",
+      "description": "List the ad accounts the connected Facebook user can access \u2014 the\n    usual first call of any session: everything else needs an account id\n    (the \"act_\u2026\" value) from here.\n\n    Monetary fields (amount_spent, balance, spend_cap) are returned in the\n    account currency's minor units as provided by Meta.\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        user_id: Graph user node to query (default \"me\", the connected user).\n        limit: Maximum number of accounts to return (default 200).\n\n    Returns:\n        JSON list of accounts (act_\u2026 id, name, account_status, currency,\n        timezone, spend totals). account_status 1 = active, 2 = disabled,\n        3 = unsettled.\n    ",
       "inputSchema": {
         "properties": {
           "access_token": {
@@ -1268,7 +1268,7 @@
     },
     {
       "name": "get_ad_creatives",
-      "description": "Get the creatives attached to an ad.\n\n    Args:\n        ad_id: Ad id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "Get the creatives attached to an ad \u2014 what the ad actually shows\n    (text, media references, CTA, links). Use get_ads/get_ad_details first\n    to find ad ids; use get_creative_details for one creative by id.\n\n    Args:\n        ad_id: Ad id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        JSON list of creatives with id, name, texts, object_story_spec /\n        asset_feed_spec, image/video references, and CTA.\n    ",
       "inputSchema": {
         "properties": {
           "ad_id": {
@@ -1297,7 +1297,7 @@
     },
     {
       "name": "get_ad_details",
-      "description": "Get details for one ad.\n\n    Args:\n        ad_id: Ad id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "Get details for one ad, including issues_info \u2014 check this first\n    when an ad is rejected or not delivering.\n\n    Args:\n        ad_id: Ad id (from get_ads or create_ad).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        JSON ad object (status, effective_status, creative reference,\n        tracking specs, preview_shareable_link, issues_info).\n    ",
       "inputSchema": {
         "properties": {
           "ad_id": {
@@ -1326,7 +1326,7 @@
     },
     {
       "name": "get_ad_image",
-      "description": "Download and return the image used by an ad (viewable in the client).\n\n    Args:\n        ad_id: Ad id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "Download and return the image used by an ad, as a viewable image\n    (not JSON) \u2014 use it to actually look at what an ad shows. Resolves the\n    image via the ad's creative (image_url, then image_hash, then\n    thumbnail).\n\n    Args:\n        ad_id: Ad id (from get_ads).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        The image binary, rendered by MCP clients; an error if the ad has\n        no resolvable image (e.g. video-only ads \u2014 use get_ad_video).\n    ",
       "inputSchema": {
         "properties": {
           "ad_id": {
@@ -1355,7 +1355,7 @@
     },
     {
       "name": "get_ad_video",
-      "description": "Get playable URLs and metadata for an ad's video.\n\n    Pass video_id directly, or ad_id to resolve the video from the ad's\n    creative.\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        ad_id: Ad id to resolve the video from.\n        video_id: Video id (skips ad lookup).\n        account_id: Unused (kept for tool-call uniformity).\n    ",
+      "description": "Get playable URLs and metadata for an ad's video \u2014 watch the actual\n    video via the source/permalink URL, or check that a freshly uploaded\n    video has finished transcoding before create_ad_creative uses it.\n\n    Pass video_id directly, or ad_id to resolve the video from the ad's\n    creative.\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        ad_id: Ad id to resolve the video from.\n        video_id: Video id (skips the ad lookup).\n        account_id: Unused (kept for tool-call uniformity).\n\n    Returns:\n        JSON with source (playable mp4 URL), permalink_url, length\n        (seconds), picture (thumbnail), title, and created_time.\n    ",
       "inputSchema": {
         "properties": {
           "access_token": {
@@ -1392,7 +1392,7 @@
     },
     {
       "name": "get_ads",
-      "description": "List ads in an account, campaign, or ad set.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Page size.\n        campaign_id: When set, list this campaign's ads.\n        adset_id: When set, list this ad set's ads (takes precedence).\n    ",
+      "description": "List ads in an account, campaign, or ad set \u2014 the bottom of the\n    campaign \u2192 ad set \u2192 ad hierarchy. Each ad pairs one creative with one\n    ad set.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Page size (default 10).\n        campaign_id: When set, list this campaign's ads.\n        adset_id: When set, list this ad set's ads (takes precedence).\n\n    Returns:\n        JSON list of ads (id, name, status, creative reference,\n        preview_shareable_link for viewing in a browser). Inspect content\n        with get_ad_creatives / get_ad_image; performance with\n        get_insights.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {
@@ -1436,7 +1436,7 @@
     },
     {
       "name": "get_adset_details",
-      "description": "Get details for one ad set, including full targeting.\n\n    Args:\n        adset_id: Ad set id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "Get details for one ad set, including the full targeting spec,\n    issues_info (delivery problems), and learning_stage_info. Fetch this\n    before update_adset when modifying targeting \u2014 updates replace the\n    whole spec.\n\n    Args:\n        adset_id: Ad set id (from get_adsets or create_adset).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        JSON ad set object with targeting, budgets, schedule, and status.\n    ",
       "inputSchema": {
         "properties": {
           "adset_id": {
@@ -1465,7 +1465,7 @@
     },
     {
       "name": "get_adsets",
-      "description": "List ad sets in an account, optionally scoped to one campaign.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Page size.\n        campaign_id: When set, list only this campaign's ad sets.\n    ",
+      "description": "List ad sets in an account, optionally scoped to one campaign.\n    Middle layer of the campaign \u2192 ad set \u2192 ad hierarchy: each row carries\n    targeting, budget, optimization goal, schedule, and status.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Page size.\n        campaign_id: When set, list only this campaign's ad sets.\n\n    Returns:\n        JSON list of ad sets (id, name, status, optimization_goal, budgets,\n        targeting, schedule). Use get_adset_details for one ad set, or\n        get_insights with an adset_id for performance.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {
@@ -1504,7 +1504,7 @@
     },
     {
       "name": "get_campaign_details",
-      "description": "Get details for one campaign.\n\n    Args:\n        campaign_id: Campaign id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "Get details for one campaign, including delivery issues\n    (issues_info) \u2014 check this when a campaign isn't spending.\n\n    Args:\n        campaign_id: Campaign id (from get_campaigns or create_campaign).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        JSON campaign object (objective, status, budgets, schedule,\n        special_ad_categories, issues_info).\n    ",
       "inputSchema": {
         "properties": {
           "campaign_id": {
@@ -1533,7 +1533,7 @@
     },
     {
       "name": "get_campaigns",
-      "description": "List campaigns in an ad account.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Page size.\n        after: Pagination cursor from a previous response (paging.cursors.after).\n        status_filter: Effective status, e.g. ACTIVE, PAUSED, ARCHIVED.\n        objective_filter: Objective name or list of names (OUTCOME_TRAFFIC, \u2026).\n    ",
+      "description": "List campaigns in an ad account \u2014 the top of the campaign \u2192 ad set \u2192\n    ad hierarchy. Start here when exploring an account's structure or\n    looking up a campaign id by name.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional) \u2014 find one with\n            get_ad_accounts.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Page size (default 10).\n        after: Pagination cursor from a previous response\n            (paging.cursors.after).\n        status_filter: Effective status \u2014 ACTIVE, PAUSED, or ARCHIVED.\n            Empty returns all.\n        objective_filter: Objective name or list of names (OUTCOME_TRAFFIC,\n            OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_AWARENESS,\n            OUTCOME_ENGAGEMENT, OUTCOME_APP_PROMOTION).\n\n    Returns:\n        JSON list of campaigns (id, name, objective, status, budgets,\n        schedule). Drill down with get_adsets / get_ads, or get_insights\n        with a campaign_id for performance.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {
@@ -1587,7 +1587,7 @@
     },
     {
       "name": "get_creative_details",
-      "description": "Get details for one ad creative.\n\n    Args:\n        creative_id: Creative id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "Get details for one ad creative by id (texts, media references,\n    story spec, CTA). To render the actual image, follow up with\n    get_ad_image (by ad id) or get_image_by_hash (by image hash); for\n    videos use get_ad_video.\n\n    Args:\n        creative_id: Creative id (from get_ad_creatives or create_ad_creative).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        JSON creative object.\n    ",
       "inputSchema": {
         "properties": {
           "creative_id": {
@@ -1616,7 +1616,7 @@
     },
     {
       "name": "get_image_by_hash",
-      "description": "Download an uploaded ad image by its hash.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        image_hash: Image hash (from upload_ad_image or list of adimages).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "Download an uploaded ad image by its hash, as a viewable image \u2014\n    e.g. to verify what upload_ad_image stored before building a creative\n    with it.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional) \u2014 hashes are\n            account-scoped.\n        image_hash: Image hash (from upload_ad_image or a creative's\n            image_hash field).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        The image binary, rendered by MCP clients.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {
@@ -1650,7 +1650,7 @@
     },
     {
       "name": "get_insights",
-      "description": "Get performance metrics for an account, campaign, ad set, or ad.\n\n    Target one object: pass object_id (any node id, act_ prefix for\n    accounts) or one of account_id / campaign_id / adset_id / ad_id.\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        object_id: Any insights-bearing node id.\n        account_id / campaign_id / adset_id / ad_id: Alternative targets\n            (most specific wins).\n        level: Aggregation level \u2014 account, campaign, adset, or ad.\n        time_range: A Graph date preset string (today, yesterday, last_7d,\n            last_30d, last_90d, this_month, last_month, maximum, \u2026) or\n            {\"since\": \"YYYY-MM-DD\", \"until\": \"YYYY-MM-DD\"}.\n        breakdown: Dimension to segment by \u2014 age, gender, country, region,\n            publisher_platform, platform_position, impression_device, \u2026\n        action_breakdowns: e.g. [\"action_type\"].\n        action_attribution_windows: e.g. [\"7d_click\", \"1d_view\"].\n        limit: Page size.\n        after: Pagination cursor from a previous response.\n        compact: Return a smaller field set (saves tokens on large pulls).\n    ",
+      "description": "Get performance metrics (spend, impressions, clicks, CTR, CPC, CPM,\n    reach, conversions/actions, ROAS) for an account, campaign, ad set, or\n    ad. The go-to tool for \"how is X performing\".\n\n    Target one object: pass object_id (any node id, act_ prefix for\n    accounts) or one of account_id / campaign_id / adset_id / ad_id. The\n    level controls row granularity \u2014 e.g. campaign_id + level=\"ad\" returns\n    one row per ad inside that campaign.\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        object_id: Any insights-bearing node id.\n        account_id / campaign_id / adset_id / ad_id: Alternative targets\n            (most specific wins).\n        level: Aggregation level \u2014 account, campaign, adset, or ad\n            (default ad).\n        time_range: A Graph date preset string \u2014 today, yesterday, last_3d,\n            last_7d, last_14d, last_28d, last_30d, last_90d, this_month,\n            last_month, this_quarter, last_quarter, this_year, last_year,\n            last_week_mon_sun, last_week_sun_sat, this_week_mon_today,\n            this_week_sun_today, maximum, data_maximum \u2014 or\n            {\"since\": \"YYYY-MM-DD\", \"until\": \"YYYY-MM-DD\"}. Default\n            maximum (all time). Unknown presets return the supported list.\n        breakdown: Dimension(s) to segment rows by, comma-separated when\n            several. Demographic: age, gender, country, region, dma.\n            Platform/device: publisher_platform, platform_position,\n            device_platform, impression_device. Time-of-day:\n            hourly_stats_aggregated_by_advertiser_time_zone. Note Meta\n            requires platform_position to be paired with\n            publisher_platform \u2014 pass\n            \"publisher_platform,platform_position\" or it rejects with\n            code 100. Asset breakdowns (image_asset, video_asset, \u2026) only\n            return rows for dynamic-creative ads.\n        action_breakdowns: How action metrics are sliced, e.g.\n            [\"action_type\"] (the default Meta applies). Pass [] to disable\n            slicing when it collides with a breakdown.\n        action_attribution_windows: e.g. [\"7d_click\", \"1d_view\"] \u2014 adds a\n            per-window field to each action entry.\n        limit: Rows per page (default 25; Meta accepts much higher).\n        after: Pagination cursor \u2014 paging.cursors.after from the previous\n            response.\n        compact: Return a reduced field set (names, impressions, clicks,\n            spend, ctr, actions). Use for large pulls \u2014 the full field\n            set's actions/action_values arrays get big fast.\n\n    Returns:\n        JSON rows of metrics with date_start/date_stop, plus\n        paging.cursors.after when more pages exist. Zero-spend objects can\n        return empty data \u2014 that usually means \"never delivered\", not an\n        error.\n    ",
       "inputSchema": {
         "properties": {
           "access_token": {
@@ -1756,7 +1756,7 @@
     },
     {
       "name": "get_interest_suggestions",
-      "description": "Get interests related to a list of seed interest names.\n\n    Args:\n        interest_list: Seed interest names, e.g. [\"Yoga\", \"Meditation\"].\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Maximum suggestions.\n    ",
+      "description": "Get interests related to a list of seed interest names \u2014 use after\n    search_interests to widen an audience with adjacent interests.\n\n    Args:\n        interest_list: Seed interest names (exact names, not ids), e.g.\n            [\"Yoga\", \"Meditation\"].\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Maximum suggestions (default 25).\n\n    Returns:\n        JSON suggested interests with id, name, audience_size, and\n        description \u2014 ids plug into ad set targeting flexible_spec.\n    ",
       "inputSchema": {
         "properties": {
           "interest_list": {
@@ -1793,7 +1793,7 @@
     },
     {
       "name": "get_login_link",
-      "description": "Check the Facebook Ads connection and get the link to set it up.\n\n    Args:\n        access_token: Meta access token (optional \u2014 checks the connection\n            for the current credentials when omitted).\n    ",
+      "description": "Check the Facebook Ads connection and get the link to set it up.\n    Call this when other tools return not_connected or token errors\n    (code 190) \u2014 it always answers, even with no connection, and returns\n    the URL the user needs. Only the user can grant ads access; relay the\n    link rather than retrying.\n\n    Args:\n        access_token: Meta access token (optional \u2014 checks the connection\n            for the current credentials when omitted).\n\n    Returns:\n        JSON with status (connected / not_connected / invalid_token), the\n        connected Facebook user when applicable, and login_url /\n        manage_url for the ivon connectors page.\n    ",
       "inputSchema": {
         "properties": {
           "access_token": {
@@ -1815,7 +1815,7 @@
     },
     {
       "name": "search",
-      "description": "Search the connected user's ad accounts and campaigns by name.\n\n    Returns deep-research-shaped results; pass a result id to `fetch` for\n    full details.\n\n    Args:\n        query: Free-text query matched against account and campaign names.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "Search the connected user's ad accounts and campaigns by name.\n    Built for deep-research MCP clients (the search/fetch pair); for\n    ordinary listing prefer get_ad_accounts / get_campaigns, which return\n    richer rows.\n\n    Args:\n        query: Free-text query; all words must match an account or\n            campaign name (case-insensitive).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        JSON {\"results\": [{id, title, url}]} \u2014 pass a result id to fetch\n        for full details. Ids look like \"account:act_\u2026\" or \"campaign:\u2026\".\n    ",
       "inputSchema": {
         "properties": {
           "query": {
@@ -1844,7 +1844,7 @@
     },
     {
       "name": "search_ads_archive",
-      "description": "Search the public Meta Ad Library (competitor / political ads).\n\n    Note: Meta only exposes full archive data for some ad types (political/\n    issue ads); commercial-ad coverage varies by country.\n\n    Args:\n        search_terms: Keyword query, e.g. a brand name.\n        ad_reached_countries: ISO country codes, e.g. [\"US\"].\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        ad_type: ALL, POLITICAL_AND_ISSUE_ADS, EMPLOYMENT_ADS,\n            HOUSING_ADS, or FINANCIAL_PRODUCTS_AND_SERVICES_ADS.\n        fields: Comma-separated archive fields to return.\n        limit: Maximum results.\n    ",
+      "description": "Search the public Meta Ad Library \u2014 competitor research on ads\n    anyone is running, no connection to their account needed. View any\n    result via its ad_snapshot_url.\n\n    Coverage caveat: Meta only exposes full archive data (spend,\n    impressions, demographics) for political/issue ads; for commercial ads\n    expect creative text and dates but not spend, and coverage varies by\n    country (EU ads have more transparency data).\n\n    Args:\n        search_terms: Keyword query, e.g. a brand or product name.\n        ad_reached_countries: ISO country codes the ads reached, e.g. [\"US\"].\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        ad_type: ALL (default), POLITICAL_AND_ISSUE_ADS, EMPLOYMENT_ADS,\n            HOUSING_ADS, or FINANCIAL_PRODUCTS_AND_SERVICES_ADS.\n        fields: Comma-separated archive fields to return (defaults to a\n            useful set: creative texts, delivery dates, page, platforms,\n            snapshot URL).\n        limit: Maximum results (default 25).\n\n    Returns:\n        JSON list of archived ads with ad_snapshot_url links to view each\n        one in the Ad Library.\n    ",
       "inputSchema": {
         "properties": {
           "search_terms": {
@@ -1896,7 +1896,7 @@
     },
     {
       "name": "search_behaviors",
-      "description": "List behavior targeting categories (purchase behavior, device usage, \u2026).\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Maximum results.\n    ",
+      "description": "List behavior targeting categories (purchase behavior, device usage,\n    travel patterns, digital activity, \u2026). Behaviors are a fixed catalog \u2014\n    this lists them; there is no keyword search.\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Maximum results (default 50).\n\n    Returns:\n        JSON behaviors with id, name, audience_size bounds, path, and\n        description. Use in targeting as {\"flexible_spec\":\n        [{\"behaviors\": [{\"id\": \"<id>\"}]}]}.\n    ",
       "inputSchema": {
         "properties": {
           "access_token": {
@@ -1923,7 +1923,7 @@
     },
     {
       "name": "search_demographics",
-      "description": "List demographic targeting categories.\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        demographic_class: demographics, life_events, industries, income,\n            family_statuses, user_device, or user_os.\n        limit: Maximum results.\n    ",
+      "description": "List demographic targeting categories \u2014 education, job titles, life\n    events, income brackets, family status, devices.\n\n    Args:\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        demographic_class: Catalog to list \u2014 demographics (default),\n            life_events, industries, income, family_statuses, user_device,\n            or user_os.\n        limit: Maximum results (default 50).\n\n    Returns:\n        JSON categories with id, name, audience_size bounds, path, and\n        description. Use in targeting flexible_spec under the key the path\n        indicates (e.g. life_events, income).\n    ",
       "inputSchema": {
         "properties": {
           "access_token": {
@@ -1955,7 +1955,7 @@
     },
     {
       "name": "search_geo_locations",
-      "description": "Search geographic targeting locations (countries, regions, cities, zips).\n\n    Args:\n        query: Location name, e.g. \"Austin\" or \"California\".\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        location_types: Filter, e.g. [\"city\"], [\"country\", \"region\"],\n            [\"zip\"], [\"geo_market\"].\n        limit: Maximum results.\n    ",
+      "description": "Search geographic targeting locations (countries, regions, cities,\n    zips, DMAs). Returns the keys used in a targeting spec's geo_locations\n    \u2014 e.g. cities entries are {\"key\": \"<key>\", \"radius\": 25,\n    \"distance_unit\": \"mile\"}; countries are 2-letter codes.\n\n    Args:\n        query: Location name, e.g. \"Austin\" or \"California\".\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        location_types: Filter, e.g. [\"city\"], [\"country\", \"region\"],\n            [\"zip\"], [\"geo_market\"], [\"electoral_district\"]. Omit to\n            search all types.\n        limit: Maximum results (default 25).\n\n    Returns:\n        JSON locations with key, name, type, and parent hierarchy\n        (region/country) for disambiguation.\n    ",
       "inputSchema": {
         "properties": {
           "query": {
@@ -2004,7 +2004,7 @@
     },
     {
       "name": "search_interests",
-      "description": "Search interest targeting options by keyword.\n\n    Args:\n        query: Keyword, e.g. \"yoga\" or \"small business\".\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Maximum results.\n    ",
+      "description": "Search interest targeting options by keyword \u2014 the first step of\n    audience research. Use the returned ids in an ad set targeting spec:\n    {\"flexible_spec\": [{\"interests\": [{\"id\": \"<id>\"}]}]} (entries inside\n    one list are OR'd; separate flexible_spec entries are AND'd).\n\n    Args:\n        query: Keyword, e.g. \"yoga\" or \"small business\".\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        limit: Maximum results (default 25).\n\n    Returns:\n        JSON interests with id, name, audience_size bounds, and category\n        path. Broaden with get_interest_suggestions; sanity-check reach\n        with estimate_audience_size.\n    ",
       "inputSchema": {
         "properties": {
           "query": {
@@ -2038,7 +2038,7 @@
     },
     {
       "name": "search_pages_by_name",
-      "description": "Find Pages the connected user manages, filtered by name.\n\n    Args:\n        account_id: Ad account id (kept for context; pages come from the user).\n        search_term: Case-insensitive substring to match against page names.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n    ",
+      "description": "Find Pages the connected user manages, filtered by name \u2014 useful\n    when the user manages many Pages and you need one page_id by name.\n\n    Args:\n        account_id: Ad account id (kept for context; pages come from the user).\n        search_term: Case-insensitive substring matched against page names;\n            omit to list all.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n\n    Returns:\n        JSON {\"data\": [pages], \"count\": n} \u2014 page ids feed\n        create_ad_creative's page_id.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {
@@ -2079,7 +2079,7 @@
     },
     {
       "name": "update_ad",
-      "description": "Update an ad \u2014 pause/activate it, rename it, or swap its creative.\n\n    Args:\n        ad_id: Ad id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        name: New name.\n        status: ACTIVE, PAUSED, or ARCHIVED.\n        creative_id: Swap in a different creative.\n        bid_amount: New bid override in minor units.\n        tracking_specs: Replacement tracking specs.\n    ",
+      "description": "Update an ad \u2014 pause/activate it, rename it, or swap its creative.\n    Swapping the creative (creative_id) is THE way to change a live ad's\n    content, since creatives are immutable once delivering. Activating\n    spend (status=ACTIVE) should be confirmed with the user first.\n\n    Args:\n        ad_id: Ad id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        name: New name.\n        status: ACTIVE, PAUSED, or ARCHIVED.\n        creative_id: Swap in a different creative (from create_ad_creative).\n        bid_amount: New bid override in minor units (cents).\n        tracking_specs: Replacement tracking specs.\n\n    Returns:\n        JSON update acknowledgment from Meta. Content changes re-trigger\n        ad review.\n    ",
       "inputSchema": {
         "properties": {
           "ad_id": {
@@ -2170,7 +2170,7 @@
     },
     {
       "name": "update_ad_creative",
-      "description": "Update an ad creative.\n\n    Note: Meta treats most creative content as immutable once an ad has\n    delivered \u2014 typically only the name (and some asset-feed fields) can\n    change. Content changes on a live ad usually require creating a new\n    creative and swapping it in via update_ad.\n\n    Args:\n        creative_id: Creative id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        name: New creative name.\n        message / headline / description: Replacement single texts.\n        messages / headlines / descriptions: Replacement asset-feed text lists.\n        ad_formats: Replacement asset-feed formats.\n        call_to_action_type: Replacement CTA type.\n        optimization_type: Asset-feed optimization type.\n        dynamic_creative_spec: Extra asset-feed configuration to merge.\n        lead_gen_form_id: New lead form id for the CTA.\n        creative_features_spec: Advantage+ enhancement spec.\n    ",
+      "description": "Update an ad creative's name or optimization settings.\n\n    Meta treats creative content as immutable once an ad has delivered:\n    content fields (message, headline, description, CTA, image, video, URL)\n    are typically rejected on existing creatives. The name is the only\n    reliably updatable field, plus some asset-feed settings. To change what\n    a live ad shows, create a new creative with create_ad_creative and\n    point the ad at it: update_ad with creative_id.\n\n    Args:\n        creative_id: Creative id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        name: New creative name (the reliable update).\n        message / headline / description: Replacement single texts \u2014 Meta\n            may reject these on delivered creatives (see above).\n        messages / headlines / descriptions: Replacement asset-feed text\n            lists \u2014 same caveat.\n        ad_formats: Replacement asset-feed formats.\n        call_to_action_type: Replacement CTA type \u2014 same caveat.\n        optimization_type: Asset-feed optimization type (e.g.\n            DEGREES_OF_FREEDOM for Advantage+ creatives).\n        dynamic_creative_spec: Extra asset-feed configuration to merge.\n        lead_gen_form_id: New Instant Form id for the CTA.\n        creative_features_spec: Advantage+ enhancement opt-ins/outs.\n\n    Returns:\n        JSON with the updated creative, or Meta's error when a field is\n        immutable.\n    ",
       "inputSchema": {
         "properties": {
           "creative_id": {
@@ -2363,7 +2363,7 @@
     },
     {
       "name": "update_adset",
-      "description": "Update an ad set \u2014 only the fields you pass are changed.\n\n    Args:\n        adset_id: Ad set id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        (Remaining args mirror create_adset.)\n    ",
+      "description": "Update an ad set \u2014 only the fields you pass are changed. Use it to\n    pause/resume (status), rename, retarget, rebudget, or rebid. Spend\n    changes (status=ACTIVE, budget increases) should be confirmed with the\n    user first.\n\n    Some fields are immutable after creation \u2014 Meta either rejects the\n    update or silently ignores it:\n    - attribution_spec: rejected (error 1504040); create a new ad set.\n    - is_dynamic_creative: accepted but silently ignored; create a new one.\n    - frequency_control_specs: rejected after creation (error 1815198).\n    - promoted_object for ON_POST engagement: cannot be added later.\n\n    Args:\n        adset_id: Ad set id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        name: New ad set name.\n        status: ACTIVE, PAUSED, or ARCHIVED. Pair a future start_time with\n            ACTIVE to schedule (effective_status becomes SCHEDULED).\n        optimization_goal: New optimization goal (see create_adset for the\n            objective-dependent valid values).\n        daily_budget / lifetime_budget: New budget in minor units (cents).\n            Only when budgets live at the ad set level (non-CBO campaign).\n        bid_amount: Bid cap/target in minor units \u2014 required by\n            LOWEST_COST_WITH_BID_CAP and COST_CAP strategies.\n        bid_strategy: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP,\n            COST_CAP, or LOWEST_COST_WITH_MIN_ROAS (needs bid_constraints).\n        bid_constraints: {\"roas_average_floor\": target_roas \u00d7 10000}.\n        bid_adjustments: Per-dimension bid multipliers (see create_adset;\n            needs a Meta app allowlist capability).\n        targeting: Full replacement targeting spec \u2014 this overwrites, it\n            does not merge. Fetch the current spec with get_adset_details,\n            modify, and send the whole thing back.\n        start_time / end_time: New ISO 8601 schedule bounds.\n        promoted_object / attribution_spec / is_dynamic_creative /\n            frequency_control_specs: See immutability notes above.\n        destination_type: New destination (see create_adset values).\n        multi_advertiser_ads: Opt in (1) / out (0) \u2014 top-level, not inside\n            targeting.\n        dsa_beneficiary / dsa_payor: EU DSA transparency strings.\n        regional_regulated_categories / regional_regulation_identities:\n            Regulated-region declarations (see create_adset).\n\n    Returns:\n        JSON update acknowledgment from Meta.\n    ",
       "inputSchema": {
         "properties": {
           "adset_id": {
@@ -2666,7 +2666,7 @@
     },
     {
       "name": "update_campaign",
-      "description": "Update a campaign (status, budgets, name, \u2026).\n\n    To move from campaign budgets to ad-set budgets, pass\n    use_adset_level_budgets=true together with adset_budgets:\n    [{\"adset_id\": \"...\", \"daily_budget\": 5000}, \u2026].\n\n    Args:\n        campaign_id: Campaign id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        name: New name.\n        status: ACTIVE, PAUSED, or ARCHIVED.\n        objective: New objective (rarely changeable after delivery).\n        daily_budget: New daily budget in minor units.\n        lifetime_budget: New lifetime budget in minor units.\n        bid_strategy: New bid strategy.\n        bid_cap: New bid cap in minor units.\n        spend_cap: New spend ceiling in minor units.\n        special_ad_categories: Replacement special-ad-category list.\n        campaign_budget_optimization: Toggle CBO.\n        use_adset_level_budgets: When true, campaign budgets are not sent.\n        adset_budgets: Per-ad-set budget updates applied alongside.\n    ",
+      "description": "Update a campaign \u2014 pause/resume (status), rename, or change\n    budgets/bidding. Only the fields you pass are changed. Spend changes\n    (status=ACTIVE, budget increases) should be confirmed with the user\n    first.\n\n    Migrating CBO \u2192 ABO (ad-set-level budgets): pass\n    use_adset_level_budgets=true together with adset_budgets \u2014 one entry\n    per ad set, e.g. [{\"adset_id\": \"123\", \"daily_budget\": 5000}, \u2026]. Meta\n    removes the campaign budget and assigns the ad-set budgets in one\n    atomic call; the flag alone does not persist.\n\n    Args:\n        campaign_id: Campaign id.\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        name: New name.\n        status: ACTIVE, PAUSED, or ARCHIVED.\n        objective: New objective \u2014 Meta usually rejects this once the\n            campaign has delivered; create a new campaign instead.\n        daily_budget: New daily budget in minor units (cents).\n        lifetime_budget: New lifetime budget in minor units.\n        bid_strategy: New bid strategy (see create_campaign values).\n        bid_cap: New bid cap in minor units.\n        spend_cap: New spend ceiling in minor units.\n        special_ad_categories: Replacement special-ad-category list.\n        campaign_budget_optimization: Toggle CBO.\n        use_adset_level_budgets: See the CBO \u2192 ABO migration note above.\n        adset_budgets: Per-ad-set budget list applied alongside (see above).\n\n    Returns:\n        JSON update acknowledgment from Meta.\n    ",
       "inputSchema": {
         "properties": {
           "campaign_id": {
@@ -2838,7 +2838,7 @@
     },
     {
       "name": "upload_ad_image",
-      "description": "Upload an image to the ad account's library; returns its hash for\n    use in create_ad_creative.\n\n    Provide either image_url (a public URL the server fetches) or file\n    (a local path \u2014 only meaningful when running the server locally).\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        image_url: Public http(s) URL of the image.\n        file: Local filesystem path of the image.\n        name: Filename to store the image under.\n    ",
+      "description": "Upload an image to the ad account's library \u2014 step 2 of the launch\n    chain, before create_ad_creative. Returns the image hash that\n    create_ad_creative takes as image_hash. Uploading the same bytes twice\n    returns the same hash (safe to retry).\n\n    Provide either image_url (a public URL the server fetches; 8MB max) or\n    file (a local path \u2014 only meaningful when running the server locally).\n    Recommended specs: 1080\u00d71080 (1:1) or 1080\u00d71350 (4:5); JPG/PNG.\n\n    Args:\n        account_id: Ad account id (\"act_\" prefix optional).\n        access_token: Meta access token (optional \u2014 resolved automatically).\n        image_url: Public http(s) URL of the image.\n        file: Local filesystem path of the image.\n        name: Filename to store the image under (defaults to the URL/file\n            basename).\n\n    Returns:\n        JSON images map containing the stored entry with its hash \u2014 use it\n        as create_ad_creative's image_hash.\n    ",
       "inputSchema": {
         "properties": {
           "account_id": {

{ivon_cli-0.2.0 → ivon_cli-0.2.2}/src/ivon_cli/cmds/meta.py

@@ -73,6 +73,13 @@ _EXAMPLE_VALUES: Dict[str, str] = {
     "image_url": "https://example.com/ad.jpg",
     "link_url": "https://example.com",
     "time_range": "last_7d",
+    "optimization_goal": "LINK_CLICKS",
+    "billing_event": "IMPRESSIONS",
+    "search_terms": "'running shoes'",
+    "ad_reached_countries": "'[\"US\"]'",
+    "interest_list": "'[\"Yoga\",\"Meditation\"]'",
+    "image_width": "1080",
+    "image_height": "1080",
 }
 
 
@@ -197,13 +204,15 @@ def _params_from_schema(schema: dict) -> List[dict]:
 _ARG_LINE_RE = re.compile(r"^\s+([A-Za-z_]\w*(?:\s*/\s*[A-Za-z_]\w*)*):\s*(.*)$")
 
 
-def _split_description(description: str) -> Tuple[str, Dict[str, str]]:
-    """Split a Google-style tool docstring into (prose, per-param docs).
+def _split_description(description: str) -> Tuple[str, Dict[str, str], str]:
+    """Split a Google-style tool docstring into (prose, per-param docs,
+    returns text).
 
-    The backend docstrings follow one shape: summary paragraph(s), then an
+    The backend docstrings follow one shape: summary paragraph(s), an
     ``Args:`` block of ``name: text`` entries (continuations indented
-    deeper; ``a / b / c:`` documents several params at once). If the shape
-    doesn't hold, everything stays in prose and param docs come back empty.
+    deeper; ``a / b / c:`` documents several params at once), then an
+    optional ``Returns:`` block. If the shape doesn't hold, everything
+    stays in prose and the other parts come back empty.
     """
     lines = (description or "").splitlines()
     prose_lines: List[str] = []
@@ -212,9 +221,11 @@ def _split_description(description: str) -> Tuple[str, Dict[str, str]]:
         prose_lines.append(lines[i])
         i += 1
     param_docs: Dict[str, str] = {}
+    returns_lines: List[str] = []
     current: List[str] = []
     buf: List[str] = []
     base_indent: Optional[int] = None
+    in_returns = False
 
     def flush() -> None:
         text = " ".join(s.strip() for s in buf if s.strip())
@@ -223,7 +234,13 @@ def _split_description(description: str) -> Tuple[str, Dict[str, str]]:
 
     for line in lines[i + 1 :]:
         if line.strip() in ("Returns:", "Raises:", "Yields:"):
-            break
+            flush()
+            current, buf = [], []
+            in_returns = line.strip() == "Returns:"
+            continue
+        if in_returns:
+            returns_lines.append(line)
+            continue
         match = _ARG_LINE_RE.match(line)
         indent = len(line) - len(line.lstrip())
         if match and (base_indent is None or indent <= base_indent):
@@ -243,7 +260,8 @@ def _split_description(description: str) -> Tuple[str, Dict[str, str]]:
         prose = (first + "\n" + rest).strip()
     else:
         prose = ""
-    return prose, param_docs
+    returns = " ".join(s.strip() for s in returns_lines if s.strip())
+    return prose, param_docs, returns
 
 
 def _print_list(tools: List[dict]) -> None:
@@ -316,7 +334,7 @@ def _print_describe(tool: dict) -> None:
     body_wrap = max(20, width - len(body_indent))
 
     name = tool["name"]
-    prose, param_docs = _split_description(tool.get("description") or "")
+    prose, param_docs, returns = _split_description(tool.get("description") or "")
     params = _params_from_schema(tool.get("inputSchema") or {})
 
     typer.echo("")
@@ -360,6 +378,12 @@ def _print_describe(tool: dict) -> None:
                 for line in textwrap.wrap(" ".join(doc.split()), width=doc_wrap):
                     typer.echo(f"{doc_indent}{line}")
 
+    if returns:
+        typer.echo("")
+        typer.secho("RETURNS", fg=typer.colors.GREEN, bold=True)
+        for line in textwrap.wrap(returns, width=body_wrap):
+            typer.echo(f"{body_indent}{line}")
+
     typer.echo("")
     typer.secho("EXAMPLE", fg=typer.colors.GREEN, bold=True)
     typer.echo(f"{body_indent}{_example_invocation(name, params)}")

{ivon_cli-0.2.0 → ivon_cli-0.2.2}/src/ivon_cli/main.py

@@ -4,9 +4,17 @@ from __future__ import annotations
 
 import sys
 
-import click
 import typer
 
+# Catch the ClickException typer actually raises: typer ≥0.20 vendors click
+# (typer._click) and drops the standalone `click` dependency; older typer
+# uses the real package. Import from the same place typer does so the
+# class identity matches in both worlds.
+try:
+    from typer._click.exceptions import ClickException
+except ImportError:  # older typer — real click is guaranteed present
+    from click.exceptions import ClickException
+
 from . import __version__
 from .api import ApiError, NotLoggedIn, TransportError
 from .cmds import auth as auth_cmds
@@ -60,7 +68,7 @@ def main() -> int:
         return int(result) if isinstance(result, int) else exit_codes.OK
     except typer.Exit as exc:
         return int(exc.exit_code or 0)
-    except click.ClickException as exc:
+    except ClickException as exc:
         # With standalone_mode=False Click re-raises usage errors instead of
         # rendering them — print the usual usage/error message ourselves.
         exc.show()

{ivon_cli-0.2.0 → ivon_cli-0.2.2/src/ivon_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ivon-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: ivon CLI — Meta Ads connector commands + MCP access for the ivon autonomous marketing team
 Author: ivon (LemonTree Media)
 License: Proprietary

ivon_cli-0.2.0/src/ivon_cli/__init__.py

@@ -1,3 +0,0 @@
-"""ivon CLI."""
-
-__version__ = "0.2.0"