AdsAgent — TikTok Ads MCP

Read top product campaigns

products_get_top_campaigns

Read-only

Top-N TikTok campaigns by spend for a single TikTok-owned product card. Reads tiktok_insights_daily filtered by the card's matching_rules — a product-card rollup, NOT a live campaign inventory.

For campaign names, cached status, and spend, use insights_query_overview or insights_query_consistent with ad_account_id, date_from/date_to, and group_by=campaign. Native overview returns status/secondary_status; compact reads return configured_status/effective_status. These report only the returned cached entities, not exhaustive current inventory. An empty report does not prove all campaigns paused or no ads created. Use overview_get_live_configs for current configuration of known IDs; that bounded read does not discover other campaigns.

REQUIRED: product_id (str — the product_ref returned by this server's read-only products_list; legacy internal ids are still accepted). EXAMPLE: products_get_top_campaigns({"product_id": "<product_ref-from-products_list>", "limit": 10})

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No
`product_id`	Yes
`connection_context`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 13, 2026
- addedInput schema / properties / connection_context
```
Added value: +{
+  "pattern": "^mctx_v1_[0-9a-f]{64}$",
+  "type": "string"
+}
```
First observedSep 17, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already signal readOnly/openWorld=false/destructive=false, but the description adds critical traits beyond them: results reflect only returned cached entities, an empty report does not prove campaigns were paused or never created, and the 'bounded read does not discover other campaigns.' These caveats materially change how an agent should interpret and trust the output.

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 core purpose, then routing, then required-param detail and an example. Every sentence carries routing or semantics value, though the middle block is dense and slightly repetitive about status-field naming (status/secondary_status vs configured_status/effective_status).

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?

No output schema exists, yet the description explains return semantics (cached entities only, which status fields appear per read type) and gives the required parameter plus a realistic invocation. For a read-only rollup with sibling-heavy surface area, nothing needed to call it correctly is missing.

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 coverage the description must carry the load, and it documents product_id substantively (the product_ref from products_list, legacy internal ids still accepted) plus a concrete call example showing limit. connection_context is never mentioned, so it is not fully complete, but the key required parameter is well explained.

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?

The first sentence names a specific verb+resource+scope: 'Top-N TikTok campaigns by spend for a single TikTok-owned product card,' and immediately disambiguates the underlying data ('product-card rollup, NOT a live campaign inventory'). An agent can distinguish this from the many insights_* siblings without opening a 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?

Explicitly routes to alternatives with the conditions that select them: 'For campaign names, cached status, and spend, use insights_query_overview or insights_query_consistent' with the exact argument set, and 'Use overview_get_live_configs for current configuration of known IDs.' It also states what the tool is NOT for (live inventory, discovery), which is exactly when-not guidance.

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

All AdsAgent — TikTok Ads MCP 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?