get_ad

Instructions

Implementation Reference

• src/tools/ads.ts:52-62 (handler)

  The handler for the 'get_ad' tool. It calls metaGet with the ad_id as the path and optional fields, defaulting to DEFAULT_AD_FIELDS which includes id, name, adset_id, campaign_id, creative, status, effective_status, created_time, updated_time, issues_info, and preview_shareable_link.

    name: "get_ad",
    description: "Get a single ad by ID. Returns full creative + issues + preview link.",
    inputSchema: {
      ad_id: z.string(),
      fields: z.string().optional(),
    },
    handler: async (args) =>
      metaGet(`/${String(args.ad_id)}`, {
        fields: args.fields ?? DEFAULT_AD_FIELDS,
      }),
  },

• src/tools/ads.ts:51-62 (schema)

  The input schema for 'get_ad' defines a required 'ad_id' string and optional 'fields' string.

  {
    name: "get_ad",
    description: "Get a single ad by ID. Returns full creative + issues + preview link.",
    inputSchema: {
      ad_id: z.string(),
      fields: z.string().optional(),
    },
    handler: async (args) =>
      metaGet(`/${String(args.ad_id)}`, {
        fields: args.fields ?? DEFAULT_AD_FIELDS,
      }),
  },

• src/tools/ads.ts:14-93 (registration)

  The 'adTools' array (exported from ads.ts) contains the 'get_ad' tool definition (name, description, inputSchema, handler). This array is imported and registered in both src/index.ts (line 24, 51) and src/http.ts (line 22, 34) via server.registerTool.

  export const adTools: ToolDef[] = [
    {
      name: "list_ads",
      description:
        "List ads. Pass either `ad_account_id` (all ads in account), `adset_id` (ads in one ad set), " +
        "or `campaign_id` (ads in a campaign). Returns id, name, adset_id, creative, status.",
      inputSchema: {
        ad_account_id: z.string().optional(),
        adset_id: z.string().optional(),
        campaign_id: z.string().optional(),
        limit: z.number().int().positive().max(500).optional(),
        after: z.string().optional(),
        effective_status: z.array(z.string()).optional(),
        fields: z.string().optional(),
      },
      handler: async (args) => {
        const parent = args.adset_id
          ? String(args.adset_id)
          : args.campaign_id
          ? String(args.campaign_id)
          : args.ad_account_id
          ? toAdAccountPath(String(args.ad_account_id))
          : null;
        if (!parent) {
          throw new Error(
            "Must provide one of: ad_account_id, adset_id, or campaign_id.",
          );
        }
        return metaGet(`/${parent}/ads`, {
          fields: args.fields ?? DEFAULT_AD_FIELDS,
          limit: args.limit ?? 100,
          after: args.after,
          effective_status: args.effective_status,
        });
      },
    },
  
    {
      name: "get_ad",
      description: "Get a single ad by ID. Returns full creative + issues + preview link.",
      inputSchema: {
        ad_id: z.string(),
        fields: z.string().optional(),
      },
      handler: async (args) =>
        metaGet(`/${String(args.ad_id)}`, {
          fields: args.fields ?? DEFAULT_AD_FIELDS,
        }),
    },
  
    {
      name: "update_ad",
      description:
        "WRITE: Update an ad's name, status, or swap its creative. To replace the creative pass " +
        "`creative: {creative_id: 'XXX'}`.",
      inputSchema: {
        ad_id: z.string(),
        name: z.string().optional(),
        status: STATUS.optional(),
        creative: z
          .record(z.unknown())
          .optional()
          .describe("e.g. {creative_id: '123456'}"),
      },
      handler: async (args) => {
        const { ad_id, ...rest } = args;
        return metaPost(`/${String(ad_id)}`, rest as Record<string, unknown>);
      },
    },
  
    {
      name: "delete_ad",
      description:
        "WRITE: Hard-delete an ad. Prefer update_ad status=ARCHIVED to keep history.",
      inputSchema: {
        ad_id: z.string(),
      },
      handler: async (args) => metaDelete(`/${String(args.ad_id)}`),
    },
  ];

• src/tools/ads.ts:11-12 (helper)

  The DEFAULT_AD_FIELDS constant defines the default field set returned by get_ad: id, name, adset_id, campaign_id, creative, status, effective_status, created_time, updated_time, issues_info, and preview_shareable_link.

  const DEFAULT_AD_FIELDS =
    "id,name,adset_id,campaign_id,creative,status,effective_status,created_time,updated_time,issues_info,preview_shareable_link";