TikTok Ads by Get MCP Ads

tiktok get report raw

tiktok_get_report_raw

Read-onlyIdempotent

Runs native TikTok BASIC or AUDIENCE reports using caller-selected dimensions and metrics, returning raw API fields without alias calculation or auto-splitting incompatible selections.

Instructions

Run a native TikTok BASIC or AUDIENCE synchronous report with caller-selected dimensions and metrics. AUDIENCE supports demographics such as age/gender at campaign/adgroup levels; tiktok_get_audience_report provides a guided path. Use when a current API field is not yet in tiktok://metrics; unlike tiktok_get_insights, this tool does not calculate aliases or auto-split incompatible selections.

Input Schema

Name	Required	Description	Default
`page`	No	Page number to request, starting at 1.
`endDate`	No	Last date of the reporting period, in YYYY-MM-DD format, on or after startDate.
`metrics`	Yes	Native or documented calculated metric names to request. Check compatibility with the selected dimensions.
`pageSize`	No	Maximum items requested per page. Follow the returned pagination information for remaining results.
`dataLevel`	Yes	TikTok reporting aggregation level. Metrics and dimensions must be compatible with this level.
`filtering`	No	Native provider filter expressions; credentials and account overrides are not allowed.
`orderType`	No	Sort direction for the selected ordering field.
`startDate`	No	First date of the reporting period, in YYYY-MM-DD format.
`dimensions`	Yes	Native reporting dimensions. Validate compatibility with the selected metrics.
`orderField`	No	Provider field used to order report rows.
`reportType`	No	Native provider report type; determines supported metrics and dimensions.	BASIC
`serviceType`	No	TikTok report service category.	AUCTION
`advertiserId`	Yes	TikTok advertiser account ID as a string.
`queryLifetime`	No	Request lifetime reporting instead of the explicit reporting period where TikTok supports it.

Output Schema

Name	Required	Description	Default
`result`	Yes	Original tool result: parsed JSON when the text is JSON, otherwise the text or multiple MCP content blocks. Provider fields depend on the selected query.

Schema Changelog

Changes observed during successful MCP inspections.

Changed22 schema fields changedv2.1.1Oct 30, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```
removedInput schema / properties / endDate / $ref
```
Removed value: -"#/properties/startDate"
```
addedInput schema / properties / endDate / pattern
```
Added value: +"^\\d{4}-\\d{2}-\\d{2}$"
```
addedInput schema / properties / endDate / type
```
Added value: +"string"
```
removedInput schema / properties / filtering / items / additionalProperties
```
Removed value: -false
```
removedInput schema / properties / filtering / items / properties / field_name / $ref
```
Removed value: -"#/properties/dimensions/items"
```
addedInput schema / properties / filtering / items / properties / field_name / maxLength
```
Added value: +120
```
addedInput schema / properties / filtering / items / properties / field_name / minLength
```
Added value: +1
```
addedInput schema / properties / filtering / items / properties / field_name / pattern
```
Added value: +"^[A-Za-z][A-Za-z0-9_]*$"
```
addedInput schema / properties / filtering / items / properties / field_name / type
```
Added value: +"string"
```

changedInput schema / properties / filtering / items / properties / filter_value / anyOf

Previous value: -[
-  {
-    "maxLength": 2000,
-    "type": "string"
-  },
-  {
-    "items": {
-      "maxLength": 500,
-      "type": "string"
-    },
-    "maxItems": 500,
-    "type": "array"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "end": {
-        "maxLength": 100,
-        "type": "string"
-      },
-      "start": {
-        "maxLength": 100,
-        "type": "string"
-      }
-    },
-    "required": [
-      "start",
-      "end"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "maxLength": 2000,
+    "type": "string"
+  },
+  {
+    "items": {
+      "maxLength": 500,
+      "type": "string"
+    },
+    "maxItems": 500,
+    "type": "array"
+  },
+  {
+    "properties": {
+      "end": {
+        "maxLength": 100,
+        "type": "string"
+      },
+      "start": {
+        "maxLength": 100,
+        "type": "string"
+      }
+    },
+    "required": [
+      "start",
+      "end"
+    ],
+    "type": "object"
+  }
+]

removedInput schema / properties / metrics / items / $ref
```
Removed value: -"#/properties/dimensions/items"
```
addedInput schema / properties / metrics / items / maxLength
```
Added value: +120
```
addedInput schema / properties / metrics / items / minLength
```
Added value: +1
```
addedInput schema / properties / metrics / items / pattern
```
Added value: +"^[A-Za-z][A-Za-z0-9_]*$"
```
addedInput schema / properties / metrics / items / type
```
Added value: +"string"
```
removedInput schema / properties / orderField / $ref
```
Removed value: -"#/properties/dimensions/items"
```
addedInput schema / properties / orderField / maxLength
```
Added value: +120
```
addedInput schema / properties / orderField / minLength
```
Added value: +1
```
addedInput schema / properties / orderField / pattern
```
Added value: +"^[A-Za-z][A-Za-z0-9_]*$"
```
addedInput schema / properties / orderField / type
```
Added value: +"string"
```

changedOutput schema / properties / result / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "properties": {},
-    "type": "object"
-  },
-  {
-    "items": {},
-    "type": "array"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {},
+    "type": "object"
+  },
+  {
+    "items": {},
+    "type": "array"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "boolean"
+  },
+  {
+    "type": "null"
+  }
+]

First observedv2.0.1Sep 23, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real behavior: it is synchronous (unlike tiktok_get_async_report_status) and it performs no alias calculation or auto-splitting of incompatible selections, meaning incompatibilities surface to the caller. It does not say how incompatibility manifests (error vs empty result) or how pagination should be followed, which keeps it below a 5.

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?

Three sentences, front-loaded with what the tool does, then the AUDIENCE/demographics note, then the routing rule against two siblings. No filler and no repetition of schema content.

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 a 14-parameter, open-world raw-reporting tool with full schema coverage, rich annotations and an output schema, the description supplies the essentials: scope, when to prefer alternatives, and the no-alias/no-auto-split contract. The remaining gap is that it omits the other reportType values and any note on how incompatible dimension/metric combinations fail, which matters for a raw passthrough tool.

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 dimensions, metrics, dataLevel, filtering and pagination are already documented; the baseline of 3 applies. The description adds one genuinely useful nuance — metric names must be native/documented because no alias resolution happens — but it says nothing about filtering, ordering, date range, or queryLifetime beyond what the schema states, and its BASIC/AUDIENCE framing under-describes the reportType parameter.

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

Purpose4/5

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

States a specific verb and resource ('Run a native TikTok ... synchronous report') and specifies that dimensions and metrics are caller-selected, which distinguishes it from the guided/curated siblings. The one weakness is that it names only 'BASIC or AUDIENCE' while the reportType enum also allows PLAYABLE_MATERIAL, CATALOG and BC, so the stated scope is narrower than the tool's actual capability.

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 gives the selection condition ('Use when a current API field is not yet in tiktok://metrics') and names two alternatives with the reason to prefer them: tiktok_get_audience_report as the guided path for demographics, and tiktok_get_insights as the alias-calculating/auto-splitting option. The agent can route between all three without opening a schema.

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

Deploy Server