Skip to main content
Glama

Ads Uploader: Meta Ads MCP

Update Saved Build

ads_update_build
DestructiveIdempotent

Update one saved build by ID: rename it, edit notes, patch its portable spec with specPatch, or replace the full spec. specPatch merges field by field: omitted fields survive, nested text entries merge, supplied arrays replace and null removes a field. It needs expectedRevision, the revision from ads_get_build. Changes to spec, webState, mediaItems or uploadBatchId bump the revision. A rename or notes-only update does not bump it. Parallel updates to one build collide on the revision: a stale expectedRevision returns "Build changed since it was read" (HTTP 409), and ads_get_build returns the current revision. spec replaces the whole portable spec. webState is only accepted unchanged from a build that was read; the web uploader regenerates it when it next opens the build, and webStateStale: true until then is normal. Setting a name turns an autosaved build into a kept, named build. An open uploader tab picks up the update automatically. Returns updated metadata and display: totalAdSets, totalAds and the ads in each ad set as the web uploader renders them (display.complete false carries a reason, and display.inheritedFromSource lists fields that come from the source ad or preset); ads_get_build returns the stored state. Uploaded-media texts.perAd keys are file names or media:. CTA fields take Meta enum values such as SHOP_NOW. Uploaded media accepts texts.common.multiAdvertiserAds only (boolean); omit to copy the source, which is off when the source ad does not say. True is refused while site links remain. Imported posts keep per-row choices. Website highlights is copied from the source and cannot be changed; none, all off and empty features never change it. Preview and saved display report both settings separately. video_uncrop and translate_voiceover require source OPT_IN.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "buildId": "<buildId>"
    },
    "name": "ads_update_build"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoNew build name. Setting a name marks the build as manually saved, so it stops rotating out with autosaves.
specNoReplacement portable spec (the launch configuration used by ads_create with buildId). Send the FULL updated spec object, not a partial diff. Set to null to clear it.
notesNoFree-form notes stored on the build.
buildIdYesSaved build ID, e.g. build_abc123...
webStateNoOpaque web uploader session snapshot. Do not construct this object by hand. Only send it when round-tripping a webState previously read from the build without changing its structure. For content changes, update spec only; the web uploader regenerates webState on its next resume.
specPatchNoPreferred for content edits. Field-aware merge patch applied to the stored portable spec: omitted fields survive, nested objects (including individual texts.perAd/perAdset entries) merge, supplied arrays replace, and null removes a field. Requires expectedRevision. Computed launchability metadata cannot be patched.
expectedRevisionNoRevision returned by ads_get_build. Required with specPatch and recommended for every update; the update fails instead of overwriting a newer revision.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say this is a destructive, non-read-only, idempotent write; the description adds what actually matters: which fields bump the revision, that rename/notes do not, that stale expectedRevision fails with HTTP 409 and the exact message, and that setting a name converts an autosaved build into a kept one. It also discloses the return payload shape and the display.complete / display.inheritedFromSource caveats. One mild tension: the tool is annotated idempotentHint=true while the description says each spec change bumps the revision, so a replay with the same expectedRevision collides; this is a nuance, not a contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first two sentences are well front-loaded, but the middle and tail drift into spec-content rules that do not concern invoking this tool: uploaded-media texts.perAd keys, CTA Meta enum values such as SHOP_NOW, website highlights being copy-only, and video_uncrop/translate_voiceover needing source OPT_IN. Those are portable-spec documentation (more relevant to ads_create) and bloat the definition into a single unstructured paragraph, diluting the revision and webState guidance that actually belongs here.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive tool with seven parameters, a nested spec object and no output schema, the description covers everything an agent needs: concurrency control via expectedRevision, the 409 failure mode and recovery path, webState handling, the autosave-to-kept transition, and the return shape (totalAdSets, totalAds, per-ad-set ads) that would otherwise be undocumented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description goes past the per-parameter text by mapping parameters to side effects: "Changes to spec, webState, mediaItems or uploadBatchId bump the revision. A rename or notes-only update does not bump it." That is information an agent cannot get from the schema alone and directly affects how it sequences calls.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource plus its four modes: "Update one saved build by ID: rename it, edit notes, patch its portable spec with specPatch, or replace the full spec." That immediately separates it from ads_get_build (read) and ads_delete_build (remove), and the spec-vs-specPatch split tells an agent which mode it is choosing between.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the selection rule between the two write paths (specPatch is the merge patch, spec replaces the whole portable spec) and the prerequisite chain (expectedRevision comes from ads_get_build, is required with specPatch, recommended otherwise). It also states when webState may be sent and tells the agent to update spec only for content changes, which is real when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.