Skip to main content
Glama

Visibility Genies

Read TikTok Ads performance

get_tiktok_ads_performance
Read-only

The connected TikTok advertiser's results for a date range, from what the daily pull stored: totals and per-campaign spend, impressions, clicks, CTR, CPC, CPM, conversions, cost per conversion, purchases, purchase value and ROAS, most spend first. Money is in the advertiser's currency (currencyCode); conversions follow the ad account's attribution setting. Days are in the advertiser's time zone; at most 90 days. Read-only; uses no credits.

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

Input Schema

NameRequiredDescriptionDefault
endDateNoLast day (YYYY-MM-DD). Use with startDate. Without both, the last 30 stored days. At most 90 days.
projectIdYesRequired. The Visibility Genies project this call works in and is billed to. Call list_projects to find one.
startDateNoFirst day (YYYY-MM-DD, the advertiser's time zone). Use with endDate.

Output Schema

NameRequiredDescriptionDefault
okYes
metaNo
reasonNo
totalsNo
endDateNo
messageNo
failedAtNo
campaignsNo
startDateNo
connectUrlNo
accountNameNo
currencyCodeNo
storedThroughNo
needsReconnectNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and non-destructive, but the description adds real context beyond them: results come from a daily pull (implying staleness/lag), money is in the advertiser's currencyCode, conversions follow the ad account's attribution setting, and days are in the advertiser's time zone. The 'uses no credits' note adds billing transparency not present in annotations. It does not cover empty-result behavior or ordering beyond 'most spend first'.

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 what the agent gets back and in what order, then constraints and units. The metric enumeration is long but each item is a real output field, so it earns its space; the only mild redundancy is repeating the 90-day cap already stated in the endDate parameter description.

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?

With an output schema covering return shape and annotations covering safety, the description fills the remaining gaps an agent needs: data provenance, currency, attribution basis, time zone, date-range default and cap, and sort order. Nothing material is missing for correct invocation.

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 100%, so the baseline is 3, but the description adds interpretation the schema lacks: dates are evaluated in the advertiser's time zone and the 90-day window is a hard constraint, plus the metric values are currency- and attribution-dependent. It does not restate the projectId billing/scope semantics, which the schema already handles.

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?

Names the specific resource (the connected TikTok advertiser's results), the shape of the return (totals plus per-campaign rows), and the exact metric set including spend, impressions, CTR, CPC, CPM, conversions, cost per conversion, purchases, purchase value and ROAS. The platform naming plus the 'daily pull stored' provenance cleanly separates it from the Meta/Google/ChatGPT ads siblings.

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?

Gives clear operating context: a date range is optional and defaults to the last 30 stored days, with a hard 90-day ceiling, and the call is read-only with no credit cost. It stops short of explicitly naming when to prefer this over a sibling ads tool or what to do when no stored data exists for the range.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources