AdLoop: Google Ads, Reddit Ads & GA4

by kLOsk

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Draft call conversion upload

draft_upload_call_conversions

Draft an offline CALL-conversion upload from a CSV — returns a PREVIEW.

Instructions

Draft an offline CALL-conversion upload from a CSV — returns a PREVIEW.

Uploads call conversions via ConversionUploadService.UploadCallConversions, matching the call against the ad click by the caller's phone number. The CSV must have columns: Caller's Phone Number, Call Start Time, Conversion Name, Conversion Time, Conversion Value, Conversion Currency. The Conversion Name must match an existing UPLOAD_CALLS-type conversion action — verified against the account while drafting, so a typo fails here rather than after the upload. Optional Ad User Data and Ad Personalization columns carry consent per row.

The CSV comes from csv_path (a file on the machine running AdLoop) or from upload_id (a file uploaded with upload_conversion_csv, the only way on AdLoop Cloud). An uploaded file is deleted once the draft has read it.

PII: the caller phone number is required RAW by Google (it cannot be hashed), so it lives in the plan's apply-only payload — the preview shows redacted ids and counts, the audit log and plan.changes show neither. Apply uploads exactly what you previewed (no CSV re-read).

Phone numbers are normalized with libphonenumber semantics: a number carries no country code needs default_region, an extension is dropped, and the German trunk marker in "+49 (0)89 …" is handled. Rows whose number stays unusable are skipped and reported in skipped_rows instead of being uploaded to no effect.

Rows that repeat inside one file are named in dedup_warnings. A call upload has no dedup key at Google, so each of them still goes out as its own conversion — the warning is the only place that says so.

Returns a preview with a plan_id, the row counts, the consent the rows actually carry (consent_summary) and the skipped rows; nothing is uploaded until that preview is confirmed.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "draft_upload_call_conversions"
  }
}

Input Schema

Name	Required	Description
`consent`	No	Consent signals for GDPR/EEA, as an object with "ad_user_data" and/or "ad_personalization", each "GRANTED", "DENIED" or "UNSPECIFIED". None sends UNSPECIFIED. A row whose own "Ad User Data" / "Ad Personalization" columns are filled in overrides this for that row; empty cells fall back to it.
`csv_path`	No	Path of the CSV file holding the upload rows, read on the machine that runs AdLoop. Refused on the hosted server; use upload_id there.
`upload_id`	No	Id of a CSV uploaded with upload_conversion_csv (up_...), instead of csv_path.
`customer_id`	No	Google Ads customer ID (digits, e.g. "1234567890"). Empty uses the configured default account.
`default_region`	No	ISO 3166-1 alpha-2 country assumed for phone numbers that carry no country code, e.g. "DE" for "0151 12345678". Empty leaves such numbers unusable and the row is skipped.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.33.1Oct 22, 2026

addedInput schema / properties / csv_path / default
```
Added value: +""
```

changedInput schema / properties / csv_path / description

Previous value: -"Path of the CSV file holding the upload rows, read on the\nmachine that runs AdLoop. The hosted server refuses this tool\nrather than reading a path of its own."New value: +"Path of the CSV file holding the upload rows, read on the\nmachine that runs AdLoop. Refused on the hosted server; use\nupload_id there."

addedInput schema / properties / upload_id

Added value: +{
+  "default": "",
+  "description": "Id of a CSV uploaded with upload_conversion_csv (up_...),\ninstead of csv_path.",
+  "type": "string"
+}

removedInput schema / required
```
Removed value: -[
-  "csv_path"
-]
```

Addedv0.27.1Oct 14, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes far beyond the annotations: discloses that the uploaded file is deleted after reading, that the caller phone number is raw and lives only in the apply-only payload while the preview redacts ids, that no CSV is re-read at apply time, that unusable numbers are skipped and reported, and that repeated rows still upload individually because Google has no dedup key. That is exactly the kind of irreversible-side-effect detail annotations (destructiveHint=false) do not convey.

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-loaded with the one-line what-it-is, then well-segmented paragraphs covering source, PII, normalization, dedup and return. Some redundancy (the default_region consequence appears in both description and schema) and the trailing Google Ads API link is filler, but the length is justified by the operation's complexity.

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 five-parameter, hosted-or-local, PII-bearing upload tool, everything an agent needs is present: source selection constraints, validation timing, redaction guarantees, skip/dedup reporting and the preview-confirm gate. The output schema carries the return shape, so the description does not need to enumerate fields further.

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 100%, but the description adds semantics the schema cannot: the required CSV column set, the fact that Conversion Name is validated against an existing UPLOAD_CALLS conversion action during drafting, and the per-row consent-column override behavior. It largely restates default_region's normalization rules, which keeps it below 5.

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 (draft) plus resource (offline CALL-conversion upload) and immediately pins the scope with 'returns a PREVIEW'. The all-caps CALL and the mention of ConversionUploadService.UploadCallConversions cleanly separate it from the enhanced-conversions-for-leads sibling.

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?

Explicitly routes between the two CSV sources: csv_path is refused on the hosted server and upload_id (from upload_conversion_csv) is 'the only way on AdLoop Cloud'. It also states the preview-must-be-confirmed workflow, though it never names confirm_and_apply as the follow-up tool, so the agent must infer the next step.

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

Deploy Server