get_targeting_suggestions

Instructions

Implementation Reference

• src/tools/targeting.ts:84-99 (handler)

  The handler function for get_targeting_suggestions tool. Sends a GET request to the Meta API's targetingsuggestions endpoint with the provided targeting_list, then returns the response data (with rate limit info) as formatted JSON. On failure, returns an error message.

  // ─── get_targeting_suggestions ─────────────────────────────
  server.tool(
    "get_targeting_suggestions",
    "Get targeting suggestions based on existing targeting criteria. Meta suggests related interests, behaviors, and demographics.",
    {
      targeting_list: z.string().describe("JSON string of current targeting criteria to get suggestions for"),
    },
    async ({ targeting_list }) => {
      try {
        const { data, rateLimit } = await client.get(`${client.accountPath}/targetingsuggestions`, { targeting_list });
        return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
      } catch (error) {
        return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

• src/tools/targeting.ts:88-89 (schema)

  Input schema for get_targeting_suggestions. Expects a single required parameter: targeting_list (string) - a JSON string of current targeting criteria.

  {
    targeting_list: z.string().describe("JSON string of current targeting criteria to get suggestions for"),

• src/index.ts:61-62 (registration)

  Registration of the registerTargetingTools function which registers all targeting tools (including get_targeting_suggestions) on the MCP server.

  registerAudienceTools(server, client);
  registerTargetingTools(server, client);

• src/tools/targeting.ts:5-100 (registration)

  The registerTargetingTools function wraps all targeting tool registrations, including get_targeting_suggestions, onto the MCP server.

  export function registerTargetingTools(server: McpServer, client: AdsClient): void {
    // ─── search_targeting ──────────────────────────────────────
    server.tool(
      "search_targeting",
      "Search for targeting options (interests, behaviors, demographics, etc.) by keyword. Use this to find valid targeting IDs for ad set targeting specs.",
      {
        q: z.string().describe("Search query (e.g. 'fitness', 'technology', 'cooking')"),
        type: z.string().optional().describe("Targeting type filter: adinterest, adgeolocation, adeducationschool, adeducationmajor, adworkemployer, adworkposition, adlocale, etc."),
        limit: z.number().optional().default(25).describe("Number of results (default 25)"),
      },
      async ({ q, type, limit }) => {
        try {
          const params: Record<string, unknown> = { q };
          if (type) params.type = type;
          if (limit) params.limit = limit;
          const { data, rateLimit } = await client.get(`${client.accountPath}/targetingsearch`, params);
          return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
        } catch (error) {
          return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
        }
      }
    );
  
    // ─── search_locations ──────────────────────────────────────
    server.tool(
      "search_locations",
      "Search for geographic locations (countries, regions, cities, zip codes) for ad targeting.",
      {
        q: z.string().describe("Search query (e.g. 'New York', 'California', 'United States')"),
        location_types: z.string().optional().describe("Comma-separated location types: country, region, city, zip, geo_market, electoral_district"),
        limit: z.number().optional().default(25).describe("Number of results (default 25)"),
      },
      async ({ q, location_types, limit }) => {
        try {
          const params: Record<string, unknown> = { q, type: "adgeolocation" };
          if (location_types) params.location_types = location_types;
          if (limit) params.limit = limit;
          const { data, rateLimit } = await client.get(`/search`, params);
          return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
        } catch (error) {
          return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
        }
      }
    );
  
    // ─── search_targeting_map ──────────────────────────────────
    server.tool(
      "search_targeting_map",
      "Map targeting IDs to their full details (names, types, paths). Useful for resolving IDs obtained from other endpoints.",
      {
        targeting_list: z.string().describe("JSON array of targeting IDs to look up"),
      },
      async ({ targeting_list }) => {
        try {
          const { data, rateLimit } = await client.get(`${client.accountPath}/targetingsearchmap`, { targeting_list });
          return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
        } catch (error) {
          return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
        }
      }
    );
  
    // ─── get_reach_estimate ────────────────────────────────────
    server.tool(
      "get_reach_estimate",
      "Get estimated audience reach for a given targeting specification. Useful for planning campaigns before creating them.",
      {
        targeting_spec: z.string().describe("JSON string of targeting spec (same format as ad set targeting)"),
      },
      async ({ targeting_spec }) => {
        try {
          const { data, rateLimit } = await client.get(`${client.accountPath}/reachestimate`, { targeting_spec });
          return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
        } catch (error) {
          return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
        }
      }
    );
  
    // ─── get_targeting_suggestions ─────────────────────────────
    server.tool(
      "get_targeting_suggestions",
      "Get targeting suggestions based on existing targeting criteria. Meta suggests related interests, behaviors, and demographics.",
      {
        targeting_list: z.string().describe("JSON string of current targeting criteria to get suggestions for"),
      },
      async ({ targeting_list }) => {
        try {
          const { data, rateLimit } = await client.get(`${client.accountPath}/targetingsuggestions`, { targeting_list });
          return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
        } catch (error) {
          return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
        }
      }
    );
  }

• src/prompts/index.ts:98-99 (helper)

  Reference to get_targeting_suggestions in the audience_builder prompt, instructing the AI to use it to discover related targeting options.

  "2. Use get_targeting_suggestions to discover related targeting options I might have missed",
  "3. Use get_reach_estimate to check the audience size for the combined targeting",