flayr

Create a paused lead campaign

ads_campaign_create

[writes · ads:manage scope] Creates a Meta Instant Form lead campaign (goal lead_generation, the ad set's leadGenFormId from ads_lead_forms_list, placements without Audience Network, the age range and countries in targeting) with one image ad, created PAUSED. It lands in the owner's Proposed campaigns and never runs or spends until the owner approves it (ads_campaign_approve). headline, body, imageUrl or creativeId and budget (dollars; budgetType daily or lifetime) are required; promotedObject.pageId picks the Facebook Page. Pass agentName and reason. Audited in Ads > Agent activity. (Wraps POST /api/v2/ads/campaigns.)

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": {
      "agentName": "<agentName>",
      "reason": "<reason>",
      "goal": "<goal>",
      "leadGenFormId": "<leadGenFormId>",
      "headline": "<headline>",
      "body": "<body>",
      "budget": "<budget>"
    },
    "name": "ads_campaign_create"
  }
}

Input Schema

Name	Required	Description
`body`	Yes	The ad's primary text.
`goal`	Yes
`budget`	Yes	In dollars (account currency).
`reason`	Yes	Why the agent is doing this. Shown to the owner and kept in the audit trail.
`brandId`	No	A brand id (GET /api/v2/brands) or "personal"; default: the key owner's active brand.
`headline`	Yes	Also the campaign name.
`imageUrl`	No	The ad image (an allowed host). Or send creativeId.
`platform`	No	Default facebook.
`schedule`	No	ISO dates; default now to +7 days.
`agentName`	Yes	Which agent is acting. Shown to the owner in Ads > Agent activity.
`targeting`	No	Age range 13-65 and the usual targeting fields.
`budgetType`	No	Default lifetime.
`creativeId`	No	A saved ad creative id instead of imageUrl.
`placements`	No	Default automatic = Facebook, Instagram and Messenger (no Audience Network).
`adAccountId`	No	Default: the brand's selected ad account; must match it.
`callToAction`	No	A CTA from the ads create config (default: the owner's default, e.g. LEARN_MORE; SIGN_UP suits a lead form).
`leadGenFormId`	Yes	An Instant Form id (GET /api/v2/ads/lead-forms).
`idempotencyKey`	No	Optional; repeats with the same key return the first result instead of creating twice.
`promotedObject`	No	The Facebook Page the lead ad runs from.
`specialAdCategories`	No

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 10, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Goes well beyond the annotations by disclosing that the creation is paused, non-spending, lands in Proposed campaigns pending owner approval, requires the ads:manage scope, and is audited in Ads > Agent activity. It also notes idempotency semantics via idempotencyKey even though the annotation declares idempotentHint=false; the only remaining gap is the response shape (no campaign id mentioned).

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

Conciseness4/5

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

Front-loads the write operation, scope, and paused-by-default behavior in the opening clause, then required-field facts, then operational notes. The dense parenthetical is long but every element (goal, form id source, placements, targeting) earns its place; minor trim possible in the repeated audit/owner phrasing.

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

Completeness3/5

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

For a 20-parameter nested-object write tool with no output schema, the definition covers required inputs, defaults, approval workflow, and auditing, but never states what is returned on success (campaign id or handle needed for later approve/pause calls). That omission is the main completeness gap for an agent that must chain calls.

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 already 90%, so the baseline is low, yet the description adds real semantics: which fields are required and mutually exclusive (imageUrl or creativeId), that headline doubles as the campaign name, that budget is in dollars with daily/lifetime budgetType, that promotedObject.pageId selects the Page, and that agentName/reason are surfaced to the owner and audit trail.

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?

States a specific verb and resource — creates a Meta Instant Form lead campaign with one image ad, PAUSED — and pins down the mechanics (lead_generation goal, leadGenFormId, placements excluding Audience Network). An agent can distinguish it immediately from ads_campaign_approve, ads_campaign_get, or a boosting tool.

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

Usage Guidelines4/5

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

Explains the operating context: the campaign is created paused, lands in the owner's Proposed campaigns, and requires ads_campaign_approve before it can run or spend, with leadGenFormId sourced from ads_lead_forms_list. It does not state explicit when-not-to-use conditions versus sibling creation tools, but the approval dependency gives clear routing context.

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

All flayr tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?