lb_schedule_quick_set

Instructions

Implementation Reference

• src/tools/schedule.tools.ts:204-268 (handler)

  Handler function for the 'lb_schedule_quick_set' tool. Registered via server.tool(), it POSTs uniform daily volumes (atc, sfb, pgv) to /api/v1/projects/{ui_id}/schedule/quick. Performs SFB region gate check, builds request body with defaults of 0, appends cost summary to response, adds region_warning and service_note as needed.

  server.tool(
    "lb_schedule_quick_set",
    "Quick-set uniform daily volumes for a Listing Bureau project. WARNING: This clears any existing per-day schedule and replaces it with uniform values. All omitted fields default to 0. SFB is US-region only; ATC/PGV work in all regions (lower execution rate outside US).",
    {
      ui_id: z.string().describe("Project unique identifier"),
      atc: z.number().int().min(0).optional().describe("Add-to-cart volume per day (default 0) (all regions; lower execution rate outside US)"),
      sfb: z.number().int().min(0).optional().describe("Search Find Buy (SFB) volume per day (default 0) (US-region projects only)"),
      pgv: z.number().int().min(0).optional().describe("Page view volume per day (default 0) (all regions; lower execution rate outside US)"),
    },
    { destructiveHint: true, idempotentHint: true  },
    async (params) => {
      try {
        // SFB region gate: only fetch project when SFB > 0
        let regionWarning: string | undefined;
        if ((params.sfb ?? 0) > 0) {
          try {
            const projRes = await client.request<Project>(
              "GET",
              `/api/v1/projects/${encodeURIComponent(params.ui_id)}`,
              undefined,
              undefined,
              "lb_schedule_quick_set",
            );
            assertSfbAllowed(projRes.data.region, true);
          } catch (fetchErr) {
            if (fetchErr instanceof SfbRegionError) {
              throw fetchErr;
            }
            regionWarning = "Could not verify project region for SFB eligibility. The backend will enforce region restrictions.";
          }
        }
  
        const body: Record<string, unknown> = {
          atc: params.atc ?? 0,
          sfb: params.sfb ?? 0,
          pgv: params.pgv ?? 0,
        };
  
        const res = await client.request<ScheduleResponse>(
          "POST",
          `/api/v1/projects/${encodeURIComponent(params.ui_id)}/schedule/quick`,
          body,
          undefined,
          "lb_schedule_quick_set",
        );
        const augmented = await appendCostSummary(res.data, client);
        if (regionWarning) {
          (augmented as Record<string, unknown>).region_warning = regionWarning;
        }
        // Note when schedule has ATC/PGV but no SFB
        const hasAtcOrPgv = (params.atc ?? 0) > 0 || (params.pgv ?? 0) > 0;
        const hasSfb = (params.sfb ?? 0) > 0;
        if (hasAtcOrPgv && !hasSfb) {
          (augmented as Record<string, unknown>).service_note =
            "This schedule has ATC/PGV but no SFB. " +
            "These services alone rarely move ranking unless the keyword is very uncompetitive. " +
            "They're typically paired with SFB to maintain a healthy organic conversion ratio. " +
            "You can update the schedule to add SFB if needed.";
        }
        return formatResult(augmented);
      } catch (e) {
        return formatErrorResult(e);
      }
    },
  );

• src/tools/schedule.tools.ts:207-212 (schema)

  Input schema for lb_schedule_quick_set: ui_id (required string), atc/sfb/pgv (optional integers, default 0).

  {
    ui_id: z.string().describe("Project unique identifier"),
    atc: z.number().int().min(0).optional().describe("Add-to-cart volume per day (default 0) (all regions; lower execution rate outside US)"),
    sfb: z.number().int().min(0).optional().describe("Search Find Buy (SFB) volume per day (default 0) (US-region projects only)"),
    pgv: z.number().int().min(0).optional().describe("Page view volume per day (default 0) (all regions; lower execution rate outside US)"),
  },

• src/tools/schedule.tools.ts:204-268 (registration)

  The tool is registered via server.tool() inside registerScheduleTools(), which is called from src/index.ts line 59.

  server.tool(
    "lb_schedule_quick_set",
    "Quick-set uniform daily volumes for a Listing Bureau project. WARNING: This clears any existing per-day schedule and replaces it with uniform values. All omitted fields default to 0. SFB is US-region only; ATC/PGV work in all regions (lower execution rate outside US).",
    {
      ui_id: z.string().describe("Project unique identifier"),
      atc: z.number().int().min(0).optional().describe("Add-to-cart volume per day (default 0) (all regions; lower execution rate outside US)"),
      sfb: z.number().int().min(0).optional().describe("Search Find Buy (SFB) volume per day (default 0) (US-region projects only)"),
      pgv: z.number().int().min(0).optional().describe("Page view volume per day (default 0) (all regions; lower execution rate outside US)"),
    },
    { destructiveHint: true, idempotentHint: true  },
    async (params) => {
      try {
        // SFB region gate: only fetch project when SFB > 0
        let regionWarning: string | undefined;
        if ((params.sfb ?? 0) > 0) {
          try {
            const projRes = await client.request<Project>(
              "GET",
              `/api/v1/projects/${encodeURIComponent(params.ui_id)}`,
              undefined,
              undefined,
              "lb_schedule_quick_set",
            );
            assertSfbAllowed(projRes.data.region, true);
          } catch (fetchErr) {
            if (fetchErr instanceof SfbRegionError) {
              throw fetchErr;
            }
            regionWarning = "Could not verify project region for SFB eligibility. The backend will enforce region restrictions.";
          }
        }
  
        const body: Record<string, unknown> = {
          atc: params.atc ?? 0,
          sfb: params.sfb ?? 0,
          pgv: params.pgv ?? 0,
        };
  
        const res = await client.request<ScheduleResponse>(
          "POST",
          `/api/v1/projects/${encodeURIComponent(params.ui_id)}/schedule/quick`,
          body,
          undefined,
          "lb_schedule_quick_set",
        );
        const augmented = await appendCostSummary(res.data, client);
        if (regionWarning) {
          (augmented as Record<string, unknown>).region_warning = regionWarning;
        }
        // Note when schedule has ATC/PGV but no SFB
        const hasAtcOrPgv = (params.atc ?? 0) > 0 || (params.pgv ?? 0) > 0;
        const hasSfb = (params.sfb ?? 0) > 0;
        if (hasAtcOrPgv && !hasSfb) {
          (augmented as Record<string, unknown>).service_note =
            "This schedule has ATC/PGV but no SFB. " +
            "These services alone rarely move ranking unless the keyword is very uncompetitive. " +
            "They're typically paired with SFB to maintain a healthy organic conversion ratio. " +
            "You can update the schedule to add SFB if needed.";
        }
        return formatResult(augmented);
      } catch (e) {
        return formatErrorResult(e);
      }
    },
  );