Caybl

Create a Microsoft Advertising page-visit conversion goal

msads_create_conversion_goal

Idempotent

Create a conversion goal that counts a visit to a page (for example a thank-you page) as a conversion, tied to a UET tag (see msads_get_conversion_tracking for tag ids). It is created PAUSED, so it records nothing until turned on with msads_set_conversion_goal_status. The goal's scope is the account and cannot be changed later. Microsoft turns on automatic click tagging (an msclkid parameter on your landing page URLs) for the account when a conversion goal is added. Because that changes a setting beyond the goal, you must pass acknowledgeAutoTagging: true. Other goal types (events, duration, pages per visit) are not offered here. Use dryRun to review.

Input Schema

Name	Required	Description	Default
`name`	Yes	Goal name, up to 100 characters, unique for the customer.
`tagId`	Yes	The UET tag id that will record it, from msads_get_conversion_tracking.
`dryRun`	No	Preview only. Microsoft has no validate-only mode, so Caybl reads the current value and shows exactly what would change (before and after) without sending anything. Free, and cannot affect spend.
`category`	Yes	What kind of conversion this is, e.g. Purchase or SubmitLeadForm.
`accountId`	No	Microsoft Advertising account id or account number (e.g. 'F123ABCD'), as listed by msads_list_accounts. Only needed when the sign-in can reach more than one account.
`countType`	No	All counts every conversion; Unique counts one per click.	All
`fixedValue`	No	Optional fixed value per conversion, in the account currency.
`urlOperator`	No	How to match: Equals (default), BeginsWith, Contains or RegularExpression.	Equals
`urlExpression`	Yes	The page address to match, e.g. /thank-you.
`acknowledgeAutoTagging`	No	Must be true: confirms you know adding a goal turns on automatic click tagging.
`conversionWindowMinutes`	No	How long after a click a visit still counts, in minutes. Default 43200 (30 days).

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 29, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations: discloses that creation is paused/non-recording, that goal scope is account-level and immutable after creation, and that adding a goal has an account-wide side effect (automatic click tagging adding msclkid to landing page URLs) which forces the acknowledgment flag. Nothing here contradicts destructiveHint=false, idempotentHint=true or openWorldHint=true.

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

Conciseness5/5

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

Five tight sentences, front-loaded with what the tool creates, followed by lifecycle, side effect and the required flag. Every sentence carries information an agent needs before calling; the one-word pointer to dryRun is not wasted space.

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

Completeness4/5

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

For an 11-parameter mutation with no output schema, the description covers lifecycle, side effects, prerequisites and immutability well. The remaining gap is the return: it never says whether the call returns a goal id or how to reference the new goal when calling msads_set_conversion_goal_status, which an agent needs to complete the intended workflow.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter is already self-documented, including tagId's source and dryRun's read-only preview behavior. The description adds rationale only for acknowledgeAutoTagging and does not clarify urlOperator/urlExpression interaction, countType, fixedValue currency, or the conversion window. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (create a page-visit conversion goal) and immediately bounds the scope: page visits only, other goal types (events, duration, pages per visit) are explicitly not offered. It also ties itself to the correct sibling data source (msads_get_conversion_tracking for tag ids), so an agent can separate it from msads_create_uet_tag and the other create_* siblings.

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?

Gives explicit when-to-use context and the follow-up step: the goal is created PAUSED and records nothing until msads_set_conversion_goal_status turns it on. It names the prerequisite (acknowledgeAutoTagging: true, with the reason), recommends dryRun for review, and rules out the goal types this tool does not serve.

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

All Caybl 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?