Skip to main content
Glama
mcp-microsoft-ads

mcp-microsoft-ads

by wvuhskr

create_conversion_action

Create a Microsoft Ads conversion goal (URL, event, or duration) with its required match criteria and category. Goals cannot be deleted later—pause or exclude from bidding instead.

Instructions

Draft a conversion goal. goal_type: Event | Url | Duration (only supported values on the development account). Each goal_type REQUIRES its matching match-criteria arg — without one the goal creates "successfully" but can never record a conversion:

  • Url: url_expression (matched with UrlOperator="Contains")

  • Event: action_expression (matched with ActionOperator="Contains"; category/label expressions are out of scope here)

  • Duration: minimum_duration_seconds goal_category (ConversionGoalCategory enum) is REQUIRED live even though the WSDL marks it optional — omitting it faults "InvalidGoalCategory" (3347). Defaults to "Other", the only value live-verified valid across all three goal types (live probe); PageView also works on Url/Event but faults InvalidCategoryForGoalType (3349) on Duration. A category already claimed by an ACTIVE MS auto-created goal on the same UET tag faults SameCategoryAndTagNotAllowedForAutoGoalAndManualGoal (5667) — observed on Url goals only; the live acceptance matrix never exercised Event or Duration for this collision. The fault is keyed on category+tag rather than goal type, so it plausibly extends to Event/Duration too, but that's inference, not a tested fact — account state decides, not goal type. Lead-gen-meaningful values: SubmitLeadForm, BookAppointment, RequestQuote, Contact. NOTE: OfflineConversion goals are deliberately not created by this tool — create them in the MS Ads UI instead — because accounts that feed offline conversions from an external upload pipeline risk double-counting. ONE-WAY DOOR: there is no DeleteConversionGoals operation on this API (verified against the WSDL — every other entity family has a Delete*, this one doesn't) and UpdateConversionGoals(Status="Deleted") silently no-ops (partial_errors=[], goal reads back Active still) — so a created goal cannot be deleted. The only real levers are Status="Paused" and ExcludeFromBidding=True (both verified by read-back); full removal requires the MS Ads UI.

Live-verified 2026-07-30.

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": {
      "name": "<name>"
    },
    "name": "create_conversion_action"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYes
valueNo
goal_typeNoEvent
goal_categoryNoOther
url_expressionNo
action_expressionNo
minimum_duration_secondsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.1

TDQS

A4.4/5.0
Behavior3/5

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

No annotations are supplied, so the description carries the full burden, and it delivers unusually strong disclosure: a one-way door with no DeleteConversionGoals, UpdateConversionGoals(Status="Deleted") silently no-opping, and exact fault codes (3347, 3349, 5667) for category collisions. The only shortfall is that it does not describe what a successful response contains or whether the created goal is immediately Active versus Paused, and it explicitly labels part of the collision behavior as inference rather than tested fact.

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?

Long, but front-loaded and bullet-structured around the three goal types, so the highest-risk information (required match-criteria) comes first. Some sentences are heavier than needed, notably the extended speculation about whether fault 5667 extends to Event/Duration, but even that is decision-relevant caution rather than filler.

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 complex, irreversible mutation with no annotations, no output schema, and zero schema coverage, the description covers the hazards an agent must know: mandatory category, match-criteria coupling, category/tag collision faults, and the absence of any delete path. Only the semantics of name and value remain thin, which is minor against the overall coverage.

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?

With 0% schema description coverage across 7 parameters, the description does most of the semantic work: it enumerates goal_type values, maps each to its required matching argument and operator, and explains that goal_category is required live despite the WSDL marking it optional, including its default and which enum values are live-valid. The two undocumented parameters are name and value, whose meaning and constraints are never stated.

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?

"Draft a conversion goal" is a specific verb+resource, and the description immediately scopes what is in and out (OfflineConversion goals deliberately excluded, to be created in the MS Ads UI). An agent can distinguish this from siblings like get_conversion_actions or set_conversion_action_primary_status without opening any schema.

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?

It gives an explicit type-to-argument routing table: Url requires url_expression, Event requires action_expression, Duration requires minimum_duration_seconds, with the consequence of omission spelled out. It also names the exclusions (offline conversions) and the real alternatives for removal (Paused/ExcludeFromBidding, or the MS Ads UI).

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