Skip to main content
Glama
Buer2333

TikTok Ads MCP

by Buer2333

TikTok Ads MCP

A comprehensive Model Context Protocol (MCP) server for interacting with the TikTok Business API. This package provides a complete interface to access TikTok advertising campaigns, ad groups, ads, and generate detailed performance reports.

Features

  • Read-Only TikTok Business API Integration: Access all major TikTok advertising endpoints for data retrieval

  • 6 Comprehensive Tools: Business centers, ad accounts, campaigns, ad groups, ads, and reports

  • Advanced Filtering: Powerful filtering options for all data retrieval operations

  • Multi-Advertiser Support: Handle multiple advertiser accounts in a single request

  • Flexible Reporting: Generate detailed performance reports with custom dimensions and metrics

  • Real-time Data: Access live advertising data and performance metrics

  • Error Handling: Comprehensive error handling and validation

  • Modular Architecture: Clean, maintainable code structure

  • Safe Operations: All tools are read-only and will not modify your campaigns or ad data

Related MCP server: flin-google-ads-mcp

Available Tools

  1. get_business_centers - Retrieve business centers accessible by your access token

  2. get_authorized_ad_accounts - Get all authorized advertiser accounts

  3. get_campaigns - Retrieve campaigns with comprehensive filtering options

  4. get_ad_groups - Get ad groups with advanced filtering and targeting options

  5. get_ads - Retrieve ads with detailed creative and performance data

  6. get_reports - Generate comprehensive performance reports and analytics

Prerequisites

  • Python 3.14.0 or higher

  • TikTok Business API access

  • Valid API credentials (app ID, secret, access token)

Compatibility

Works with both mcp 1.x and 2.x. mcp 2.0 renamed FastMCP to MCPServer (mcp.server.mcpserver) and turned mcp.server.fastmcp into a raising stub; server.py imports via a try-v2-except-v1 shim, so no pin is required (mcp>=1.9.0). Tests pass on 1.28.1 and 2.1.1.

Quick Start

Installation

  1. Download the TikTok Ads MCP

    • Click the green "Code" button at the top of the GitHub page

    • Select "Download ZIP"

    • Unzip the downloaded file to a location you can easily find (like your Documents folder)

  2. Alternatively, if you're familiar with Git:

    git clone https://github.com/ysntony/tiktok-ads-mcp.git
  3. Install Dependencies

    cd tiktok-ads-mcp
    pip install -e .

Configuration

  1. Set up environment variables in your MCP client configuration:

{
  "mcpServers": {
    "tiktok-ads": {
      "command": "python",
      "args": ["-m", "tiktok_ads_mcp"],
      "env": {
        "TIKTOK_APP_ID": "your_app_id",
        "TIKTOK_SECRET": "your_secret",
        "TIKTOK_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}
  1. Required credentials:

    • TIKTOK_APP_ID: Your TikTok app ID

    • TIKTOK_SECRET: Your TikTok app secret

    • TIKTOK_ACCESS_TOKEN: Your access token

    How to get these credentials:

    1. Go to the TikTok for Business Developers portal and log in.

    2. Click "My Apps" and create a new app.

    3. Select "Marketing API" as the service type.

    4. In the app settings, enable permissions related to Reading and Reporting (e.g., Ads Management, Reporting).

    5. Once approved, you will find your App ID and Secret in the app details.

    6. Generate an Access Token using the "TikTok Marketing API Inspector" or via the OAuth flow documented in the portal.

Usage

Once configured, you can use the MCP tools through your MCP client (like Cursor, Claude Desktop, etc.):

  • Get business centers and advertiser accounts to discover available accounts

  • Retrieve campaigns with filtering by status, objective, or date range

  • Access ad groups with advanced targeting and optimization settings

  • View ads with detailed creative and performance data

  • Generate reports with custom dimensions, metrics, and time ranges

  • Access real-time advertising data and performance metrics

API Coverage

This MCP server provides read-only access to the TikTok Business API:

Business Management

  • Business center retrieval and access

  • Advertiser account information and permissions

Campaign Management

  • Campaign retrieval and filtering

  • Campaign status and performance monitoring

  • Campaign budget and objective information

Ad Group Management

  • Ad group retrieval and filtering

  • Advanced targeting and optimization settings

  • Performance monitoring and analysis

Ad Management

  • Ad retrieval and filtering

  • Creative asset information

  • Performance tracking and analysis

Reporting & Analytics

  • Basic performance reports

  • Audience insights reports

  • Playable ads reports

  • DSA (Dynamic Search Ads) reports

  • Business Center reports

  • GMV max ads reports

Key Features

Advanced Filtering

All tools support comprehensive filtering options:

  • Status-based filtering (active, paused, deleted)

  • Time-based filtering (creation date, modification date)

  • Performance-based filtering (budget, optimization goals)

  • Creative filtering (ad formats, material types)

Modern Implementation

This package uses the official FastMCP framework for optimal performance and developer experience:

  • Automatic Schema Generation: From Python type hints

  • Simplified Tool Registration: Using @app.tool() decorators

  • Built-in Error Handling: Consistent error responses

  • Type Safety: Full parameter validation from type hints

  • Future-Proof: Part of the official MCP SDK

Multi-Advertiser Support

  • Handle multiple advertiser accounts in single requests

  • Cross-advertiser reporting and analytics

  • Unified data access across accounts

Flexible Reporting

  • Custom dimensions and metrics

  • Multiple report types and data levels

  • Time-based and lifetime metrics

  • Aggregated and detailed views

Error Handling

  • Comprehensive parameter validation

  • Detailed error messages and suggestions

  • Graceful handling of API limitations

  • Rate limiting and retry logic

Documentation

  • MCP_USAGE.md: Comprehensive usage guide with examples

  • TikTok Business API: Official API documentation

  • Project Wiki: Additional resources and guides

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Implement your changes

  4. Add tests and documentation

  5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

  1. Check the MCP_USAGE.md documentation

  2. Review the TikTok Business API documentation

  3. Open an issue on the GitHub repository

  4. Contact the development team

Changelog

v0.1.3 (Current)

  • Async Support: Complete refactor to use async/await with httpx for improved performance

  • Retry Logic: Added automatic retries for rate limits and server errors using tenacity

  • Error Handling: Simplified and standardized error handling with decorators

  • Dependencies: Switched from requests to httpx

v0.1.2

  • FastMCP Implementation: Modern MCP server using official FastMCP framework

  • 70% Code Reduction: Compared to traditional MCP implementations

  • Automatic Schema Generation: From Python type hints

  • Simplified Tool Registration: Using @app.tool() decorators

  • Enhanced Error Handling: Built-in error handling with consistent responses

  • Type Safety: Full parameter validation from type hints

  • Future-Proof: Part of the official MCP SDK

v0.1.1

  • Complete implementation of all 6 tools

  • Advanced filtering and reporting capabilities

  • Multi-advertiser support

  • Comprehensive error handling

  • Modular tools architecture

  • Complete documentation and usage guides

v0.1.0

  • Initial release with basic MCP server structure

  • Core API client implementation

  • Basic authentication and configuration

Available Tools

24 tools
get_ad_groups_toolC

Get ad groups for a specific advertiser with optional filtering

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
filtersNo
page_sizeNo
campaign_idNo
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

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

No annotations are present, so the description carries the full burden. It does not disclose pagination behavior (implied by page/page_size), the nature of filters, or any side effects (e.g., read-only). The bare statement 'Get ad groups' suggests a safe read operation but lacks critical behavioral context.

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

Conciseness3/5

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

The description is a single sentence, making it concise. However, it lacks structure (e.g., separate lines for purpose, usage, parameters) and is arguably too terse for a tool with 5 parameters and an output schema.

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

Completeness1/5

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

Given the tool has 5 parameters, nested objects, and an output schema, the description is severely incomplete. It does not explain pagination, filter syntax, campaign constraints, or the structure of the response. The output schema exists but the description should still provide an overview of the return value.

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

Parameters1/5

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

Schema description coverage is 0%, meaning the input schema provides no parameter descriptions. The description only mentions 'optional filtering' without explaining the `filters` object, `page`, `page_size`, or `campaign_id` parameters. This adds almost no value over the schema itself.

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 description clearly states the verb 'Get' and resource 'ad groups', and specifies the scope 'for a specific advertiser' with optional filtering. This distinguishes it from sibling tools like get_ads_tool or get_campaigns_tool, which target different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives or what prerequisites are needed. The description only implies use when retrieving ad groups for an advertiser, but fails to mention exclusions or comparisons to siblings.

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

get_ads_range_report_toolB

Get Ads (manual bid) aggregate report for a date range (no timezone alignment). Returns cost, gmv, orders, roas.

ParametersJSON Schema
NameRequiredDescriptionDefault
end_dateYes
start_dateYes
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations provided, the description must disclose behavioral traits. It adds only the output fields (cost, gmv, orders, roas) and the no-timezone-alignment trait. Missing details like permissions, rate limits, data range constraints, or return format behavior.

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?

The description is a single 18-word sentence that front-loads the action and key qualifiers. Every word adds value with no redundancy.

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

Completeness2/5

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

Despite having an output schema, the description fails to cover parameter semantics, date format, timezone details, or permissions, making it insufficient for confident use without external knowledge.

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

Parameters1/5

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

Schema description coverage is 0%, and the tool description provides no explanation of the three parameters (advertiser_id, start_date, end_date), leaving the agent without meaning or format guidance for the required inputs.

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 description clearly specifies the verb 'Get' and resource 'Ads (manual bid) aggregate report' with key qualifiers 'for a date range' and 'no timezone alignment', effectively distinguishing it from siblings like 'get_ads_report_aligned_tool'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'no timezone alignment' implicitly suggests when this tool is appropriate versus an aligned variant, but there is no explicit guidance on when to use it or when to avoid it, nor mention of alternatives.

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

get_ads_report_aligned_toolA

Get Ads (manual bid) report aligned to shop timezone. Fetches hourly data and re-aggregates to match a shop-tz day. Returns cost, gmv, orders, and roas.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYes
metricsNo
shop_tzNoAmerica/Los_Angeles
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

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

Description discloses that it fetches hourly data and re-aggregates, and lists returned fields. However, with no annotations, it lacks information on destructive behavior, rate limits, or authentication requirements. It does not contradict annotations since none exist.

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: purpose, process, returned metrics. Compact and front-loaded. No redundant information.

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

Completeness3/5

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

For a tool with 4 parameters and no param descriptions, the description covers the core purpose and output but omits parameter details and usage context. Output schema is present, so return values are documented elsewhere. Adequate but not comprehensive.

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

Parameters2/5

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

Schema has 0% parameter description coverage, so description must compensate. It mentions the shop_tz alignment and date, but does not explain advertiser_id, metrics array, or default values. Only minimal parameter context is provided.

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?

Description clearly states the tool gets an ads report aligned to shop timezone, specifying manual bid, hourly data, and returned metrics. It distinguishes from siblings by highlighting timezone alignment and aggregation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage for timezone-aligned reports but does not explicitly state when to use or when to avoid, nor does it mention alternatives like get_ads_range_report_tool. Guidance is inferred rather than explicit.

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

get_ads_toolC

Get ads for a specific advertiser with optional filtering

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
filtersNo
page_sizeNo
adgroup_idNo
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

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

With no annotations, the description must convey behavioral traits. It only states the basic action and optional filtering, failing to disclose pagination behavior, the nature of filtering, or any side effects. The tool has parameters for page and page_size, but these are not mentioned.

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

Conciseness2/5

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

The description is a single short sentence, but it sacrifices informativeness for brevity. It fails to provide necessary details about parameters or usage, making it under-specified rather than concise.

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

Completeness2/5

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

Given the complexity of 5 parameters including optional filtering and pagination, the description is woefully incomplete. It lacks guidance on how to construct filters or use pagination, leaving critical gaps that are not filled by the schema or annotations. The presence of an output schema is noted but does not compensate.

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

Parameters1/5

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

Schema description coverage is 0%, yet the description adds nothing about the five parameters. 'Optional filtering' does not explain how the 'filters' object works, nor does it address page, page_size, or adgroup_id. This leaves agents completely in the dark.

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 description clearly states the verb 'Get' and the resource 'ads', constrained to 'a specific advertiser', which precisely identifies the tool's function. This distinguishes it from sibling tools that focus on different resources like ad groups or reports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no information on when to use this tool versus alternatives, nor does it mention prerequisites, exclusions, or typical use cases. Given the variety of sibling tools, this omission hinders correct selection.

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

get_advertiser_balance_toolB

Get balance and basic info for individual advertiser accounts. Max 100 IDs per request.

ParametersJSON Schema
NameRequiredDescriptionDefault
advertiser_idsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior3/5

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

Discloses the 'Max 100 IDs per request' constraint, implying read-only behavior, but lacks details on authentication, rate limits, or side effects. Without annotations, more behavioral context would be valuable.

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?

Two sentences, front-loaded with purpose and key constraint, no waste.

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

Completeness3/5

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

Output schema exists so return format is covered, but missing input format details, error handling, and rate limits make it barely adequate for a simple tool.

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

Parameters2/5

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

Schema coverage is 0%, yet description only mentions 'Max 100 IDs per request' without explaining the 'advertiser_ids' parameter (e.g., format, source, or that they are unique identifiers).

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?

Description clearly states verb 'Get' and resource 'balance and basic info for individual advertiser accounts', but does not distinguish among sibling tools like get_bc_balance_tool or get_business_centers_tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives; only provides a limit of 100 IDs per request, which is a constraint but not contextual usage advice.

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

get_authorized_ad_accounts_toolB

Get all authorized ad accounts accessible by the current access token

ParametersJSON Schema
NameRequiredDescriptionDefault
random_stringNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, and the description does not disclose any behavioral traits beyond the basic read operation. There is no mention of pagination, rate limits, or authentication requirements.

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?

A single sentence that is front-loaded with the key action and resource. No redundant information.

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

Completeness3/5

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

Given the simple nature of the tool (list ad accounts) and the existence of an output schema, the description is minimally adequate but lacks behavioral transparency and usage context.

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

Parameters2/5

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

Schema description coverage is 0%; the description does not explain the purpose of the 'random_string' parameter. Although it has a default value and is not required, the description should clarify its use.

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?

Description clearly states verb (Get), resource (authorized ad accounts), and scope (accessible by current access token). It distinguishes itself from sibling tools like get_ad_groups_tool by being specific to ad accounts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. With many sibling tools, explicit context on when to choose this over others is missing.

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

get_bc_account_cost_toolB

Get cost summary for all ad accounts under a BC within a date range. Useful for weekly/monthly spend review.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
bc_idYes
end_dateYes
page_sizeNo
start_dateYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the tool gets a cost summary but does not explain data freshness, aggregation details, authorization requirements, or output format. The description is insufficient for an agent to fully understand side effects or prerequisites.

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?

The description is concise (two sentences) and front-loaded with the core purpose. However, it could include brief parameter guidance without adding significant length. Still, it avoids unnecessary verbiage.

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

Completeness2/5

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

The tool has 5 parameters (3 required) and an output schema, but the description provides no details on pagination, required inputs, or what the cost summary contains (e.g., currency, breakdown by account). An agent cannot reliably invoke this tool without additional parameter documentation. The description is inadequate for full contextual completeness.

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

Parameters1/5

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

The schema description coverage is 0%, meaning the description does not explain any parameters. The schema provides only parameter names and types (e.g., string, integer) without formats or constraints. The description adds no meaning beyond the schema, failing to clarify date formats, pagination behavior, or the meaning of 'bc_id'.

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 description clearly states the verb 'Get', the resource 'cost summary for all ad accounts under a BC', and the scope 'within a date range'. It also mentions a common use case 'weekly/monthly spend review'. This distinguishes it from other sibling tools that operate on ads, campaigns, or individual accounts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a usage context ('weekly/monthly spend review'), but it does not specify when NOT to use this tool or mention alternatives (e.g., get_bc_balance_tool for balance, get_bc_transactions_tool for transactions). There is no guidance on pagination or required parameters beyond the implicit date range.

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

get_bc_balance_toolC

Get Business Center balance (available funds).

ParametersJSON Schema
NameRequiredDescriptionDefault
bc_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

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

No annotations are provided. The description does not disclose any behavioral traits such as authentication requirements, rate limits, side effects, or return format. For a read-only tool, the description is minimal and lacks transparency.

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?

The description is extremely concise: one sentence of 6 words. It efficiently communicates the core purpose. However, it omits necessary context, but for conciseness alone, it is well-structured.

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

Completeness2/5

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

Given the tool has an output schema (unknown content) and no annotations, the description does not explain return values, possible errors, or the meaning of the result. The parameter is also unexplained. The definition is incomplete for an agent to use confidently.

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

Parameters1/5

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

Schema description coverage is 0%. The single parameter 'bc_id' is not described at all in the description. The description adds no meaning beyond the schema; it does not explain what a Business Center ID is or how to obtain it.

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?

The description clearly states the action ('Get') and the resource ('Business Center balance'), adding context of 'available funds'. It is specific enough to distinguish from siblings like 'get_advertiser_balance_tool' which targets advertiser-level balances, though it does not explicitly differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., 'get_advertiser_balance_tool' or 'get_bc_account_cost_tool'). No context about prerequisites or scenarios where this tool is appropriate or not.

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

get_bc_budget_changelog_toolB

Get budget change history for a specific advertiser under BC. Track who changed budget and when.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
bc_idYes
end_dateYes
page_sizeNo
start_dateYes
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior3/5

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

No annotations provided, so description carries full burden. It discloses that the tool returns historical data with user and timestamp info, implying read-only behavior. However, it does not mention pagination, ordering, rate limits, or other behavioral traits.

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?

Single sentence of 15 words, no fluff. Very concise, but could benefit from additional context without harming conciseness.

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

Completeness2/5

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

Despite having an output schema, the description lacks guidance on usage, parameter details, and behavioral context. For a 6-parameter tool with no annotations, more information is needed to ensure correct invocation.

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

Parameters2/5

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

Schema description coverage is 0%, and description adds minimal parameter meaning. 'Specific advertiser under BC' hints at advertiser_id and bc_id, and date range is implied, but no details for page, page_size, or date format are given.

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?

Description clearly states the verb 'Get', resource 'budget change history', and scope 'for a specific advertiser under BC'. It specifies what is tracked ('who changed budget and when'), distinguishing it from sibling tools like get_bc_account_cost_tool or get_bc_balance_tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Description does not mention any exclusions, prerequisites, or comparisons to sibling tools.

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

get_bc_transactions_toolC

Get BC transaction records (top-ups, deductions). transaction_level: BC or ADVERTISER. Times format: YYYY-MM-DD HH:MM:SS.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
bc_idYes
end_timeYes
page_sizeNo
start_timeYes
transaction_levelNoBC

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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

No annotations provided. Description only mentions return type (records, top-ups, deductions) and time format. Missing details on pagination, rate limits, or error conditions.

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?

Two sentences covering key points efficiently. Could be better structured with bullet points but no unnecessary content.

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

Completeness3/5

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

Describes basic function and parameter hints. Output schema exists, so return values are covered. Lacks details on pagination, enum values for transaction_level, and error handling.

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 coverage is 0%. Description adds meaning to transaction_level (BC or ADVERTISER) and time format for start_time/end_time, but page and page_size remain unexplained.

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?

The description clearly states 'Get BC transaction records (top-ups, deductions)', specifying the verb and resource. However, it does not differentiate from sibling tools like get_bc_account_cost_tool or get_bc_balance_tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The mention of transaction_level values provides some context but lacks when-not or usage scenarios.

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

get_business_centers_toolC

Get business centers accessible by the current access token

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
bc_idNo
page_sizeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior3/5

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

No annotations provided; description implies read-only access but lacks details on pagination, rate limits, or behavior when no centers are returned.

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

Conciseness3/5

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

Single sentence is concise but too minimal, missing parameter details and usage context. It is front-loaded but under-specified.

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

Completeness2/5

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

Given the presence of an output schema, the description partially covers return values, but it omits pagination behavior and filtering semantics, making it incomplete for a 3-parameter tool.

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

Parameters1/5

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

Schema coverage is 0% and description provides no explanation of page, bc_id, or page_size parameters, leaving the agent to infer their purpose.

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?

The description clearly states the tool retrieves business centers accessible by the current token. It distinguishes from sibling tools focused on ads and reports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives, no exclusions or prerequisites mentioned.

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

get_campaigns_toolC

Get campaigns for a specific advertiser with optional filtering

ParametersJSON Schema
NameRequiredDescriptionDefault
filtersNo
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden. It only mentions retrieving campaigns with optional filtering, but does not disclose side effects (likely none), permissions, pagination, or rate limits. Minimal transparency for a data retrieval tool.

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

Conciseness3/5

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

The description is a single sentence of 10 words, very concise. However, conciseness comes at the expense of missing crucial details. It earns a mid score because it is not verbose but could include more information without becoming long.

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

Completeness2/5

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

Given no annotations, 0% schema coverage, and an existing output schema (unseen), the description is incomplete. It does not explain return format, filtering syntax, or prerequisites needed for an agent to correctly invoke the tool.

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

Parameters2/5

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

With 0% schema description coverage, the description must compensate. It mentions 'optional filtering' which hints at the filters parameter, but provides no details on format or allowed keys. The advertiser_id is partially explained via 'specific advertiser', but overall adds little value beyond parameter names.

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 description clearly states the tool retrieves campaigns for a specific advertiser with optional filtering. This verb+resource+scope pattern is specific and distinguishes it from siblings like get_ad_groups_tool (different resource) or get_gmvmax_campaigns_tool (different scope).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives such as get_ad_groups_tool or get_gmvmax_campaigns_tool. The description implies usage for advertiser campaigns but lacks when-not-to-use or alternative recommendations.

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

get_creative_report_toolC

Get creative-level performance report (video insights, engagement, play metrics). report_type: VIDEO_INSIGHT (default).

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
end_dateYes
filteringNo
page_sizeNo
start_dateYes
report_typeNoVIDEO_INSIGHT
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.4/5.0
Behavior2/5

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

With no annotations, the description carries full burden. It provides only the basic function and default report type. No disclosure of side effects, authentication requirements, rate limits, or output behavior. The output schema exists but the description adds no context about it.

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

Conciseness3/5

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

The description is very short, but lacks structure. It combines a brief purpose statement with a parameter note. While concise, it does not use space efficiently to convey critical information.

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

Completeness2/5

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

Despite having an output schema, the description omits details about date formats, pagination behavior, filtering capabilities, and return values. For a tool with 7 parameters and 3 required, this is inadequate.

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

Parameters1/5

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

Schema description coverage is 0%, but the description only mentions report_type and its default. It fails to explain the purpose or constraints of parameters like page, page_size, filtering, or the required advertiser_id, start_date, and end_date. This is insufficient for correct usage.

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?

The description clearly states the tool gets a creative-level performance report focused on video insights, engagement, and play metrics. It mentions the default report_type, which helps specify the scope. However, it does not differentiate from many sibling report tools like get_reports_tool or get_ads_range_report_tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description does not mention any prerequisites, conditions, or exclusions. An agent would need to infer usage from the name alone.

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

get_gmvmax_campaign_info_toolA

Get detailed info for a specific GMV Max campaign via /campaign/gmv_max/info/. Returns budget, bid, product, and scheduling details.

ParametersJSON Schema
NameRequiredDescriptionDefault
campaign_idYes
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions the endpoint path but does not explicitly state that this is a read-only, idempotent operation (though it is implied). No contradictions.

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?

The description is concise at two sentences, front-loaded with the action and endpoint, followed by a list of return details. Every sentence adds value without fluff.

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?

Given the tool's simplicity (2 required string params, output schema present), the description adequately covers the core functionality and return values. However, it could be improved by noting that it's a read-only operation or any constraints, but overall it is sufficient for the agent to select and invoke correctly.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must add meaning to the parameters. However, it only mentions the campaign ID implicitly via 'specific GMV Max campaign' but does not describe the advertiser_id or the format/usage of either parameter. The two required parameters are left to the agent to infer.

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 description clearly states the tool's purpose: 'Get detailed info for a specific GMV Max campaign' via a specific endpoint, and lists what information is returned (budget, bid, product, scheduling details). This distinguishes it from sibling tools like get_gmvmax_campaigns, which likely lists campaigns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that you need a specific campaign to get info, but does not provide explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites or exclusions, leaving the agent to infer from sibling names.

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

get_gmvmax_campaigns_toolA

Get GMV Max campaigns via /gmv_max/campaign/get/. Returns campaign list with status and ROI protection info. Default filter: PRODUCT_GMV_MAX.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
filteringNo
page_sizeNo
campaign_idsNo
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden. It partially discloses return content but fails to mention pagination behavior, the ability to override the default filter via the 'filtering' parameter, error handling, or authentication requirements. The brevity leaves significant behavioral gaps.

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?

The description is two sentences, each serving a purpose: first stating the action and endpoint, second detailing return content and a key behavioral note (default filter). No wasted words; optimal conciseness.

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

Completeness3/5

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

Given the complexity (5 params, no annotations) and the presence of an output schema, the description covers the essential purpose and one key behavior (default filter). However, it omits parameter usage guidance and behavioral details like pagination, making it minimally complete but not thorough.

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

Parameters2/5

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

Schema description coverage is 0%, requiring the description to explain parameters. It only adds the default filter value for the 'filtering' parameter and implies the 'advertiser_id' is required. Other parameters (page, page_size, campaign_ids) are left completely unexplained, providing insufficient guidance.

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 description clearly states it retrieves GMV Max campaigns and includes specific details about the return content (status and ROI protection info) and the default filter PRODUCT_GMV_MAX. The tool name and endpoint further disambiguate it from sibling tools like get_campaigns_tool.

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?

The description mentions the default filter, implying this tool is for GMV Max campaigns. However, it does not explicitly state when not to use it or which alternative (e.g., get_campaigns_tool) to use for other campaign types. The context is clear but lacks explicit exclusions.

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

get_gmvmax_range_report_toolA

Get GMVMAX aggregate report for a date range (no timezone alignment). Returns cost, gmv, orders, roi.

ParametersJSON Schema
NameRequiredDescriptionDefault
end_dateYes
store_idsYes
start_dateYes
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns an aggregate report with specific fields and notes the absence of timezone alignment, but does not detail other behaviors such as read-only status, authentication requirements, or rate limits.

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?

The description is a single sentence with a supplementary note on return fields. It is highly concise, front-loads the key purpose, and contains no extraneous information.

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

Completeness3/5

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

The tool has four required parameters with no schema descriptions, no annotations, but has an output schema. The description explains what is returned and the timezone caveat, but lacks details on parameter formats, prerequisites, or context about 'GMVMAX'. It is adequate but not comprehensive.

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

Parameters2/5

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

The input schema has 0% description coverage, meaning no parameter descriptions. The description mentions 'date range' which loosely relates to start_date and end_date parameters, but provides no format, constraints, or examples for any parameter. Thus, it adds minimal additional meaning beyond the parameter names.

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 description clearly states the verb 'Get', the resource 'GMVMAX aggregate report', and specifies the date range. It explicitly mentions 'no timezone alignment', distinguishing it from the sibling tool 'get_gmvmax_report_aligned_tool', which likely provides timezone alignment.

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?

The description provides clear usage context by indicating the report is for a date range and lacks timezone alignment, implying it should be used when timezone alignment is not needed. However, it does not explicitly state when not to use it or mention alternatives.

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

get_gmvmax_report_aligned_toolA

Get GMVMAX report aligned to shop timezone. Fetches hourly data and re-aggregates to match a shop-tz day, regardless of the ad account's native timezone. Returns aggregated metrics (cost, gross_revenue, orders), ROI, and hours included.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYes
metricsNo
shop_tzNoAmerica/Los_Angeles
store_idsYes
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

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

No annotations are provided, so the description carries the burden. It discloses timezone realignment and lists returned metrics (cost, gross_revenue, orders, ROI, hours), but lacks details on idempotency, side effects, or authentication requirements.

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?

Two sentences, no filler, front-loaded with purpose. Every word contributes: 'Get', 'GMVMAX report', 'aligned to shop timezone', description of re-aggregation, and list of returned fields.

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

Completeness3/5

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

With an output schema present, the description need not detail return values, but it omits how the date parameter is interpreted (single day?), error conditions, and behavior for missing data. The tool's complexity (timezone logic) warrants more completeness.

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

Parameters2/5

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

Schema description coverage is 0%, but the description adds minimal parameter meaning. It mentions 'hourly data' implying time granularity, but does not explain date format, shop_tz default, store_ids, or advertiser_id. The metrics parameter is hinted at but not detailed.

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 description clearly states the tool retrieves a GMVMAX report aligned to shop timezone, distinguishing it from siblings like get_gmvmax_range_report_tool and get_gmvmax_reports_tool which may not realign timezones. It specifies the verb 'Get', the resource 'GMVMAX report', and the unique behavior 'aligned to shop timezone'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a daily report aligned to shop timezone is needed, but it does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or prerequisites are mentioned.

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

get_gmvmax_reports_toolB

Get GMV Max performance reports via /gmv_max/report/get/. store_ids is REQUIRED (get from campaign info endpoint). Metrics: cost, orders, cost_per_order, gross_revenue, roi, net_cost, creative_delivery_status, product_impressions, product_clicks, product_click_rate, ad_click_rate, ad_conversion_rate, ad_video_view_rate_2s/6s/p25/p50/p75/p100. Dimensions: advertiser_id, stat_time_day, item_id (item_id requires filtering with campaign_ids AND item_group_ids). Filtering: {"campaign_ids": ["..."], "item_group_ids": ["..."]}.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
metricsNo
end_dateYes
filteringNo
page_sizeNo
store_idsYes
dimensionsNo
start_dateYes
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

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

No annotations provided; description does not disclose behavioral traits (e.g., read-only, rate limits, auth requirements). Only mentions API endpoint.

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?

Relatively concise, with line breaks separating information. No wasted sentences, though could benefit from structured formatting (e.g., bullet points).

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

Completeness3/5

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

Covers essential aspects: required store_ids, available metrics/dimensions, filtering format. Missing date format, pagination, and confirmation that some metrics may require specific dimensions. Output schema exists but not shown.

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 0%; description explains store_ids, metrics list, dimensions list, and filtering structure. However, omits descriptions for page, page_size, start_date, end_date, advertiser_id.

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?

Clear verb 'Get' and resource 'GMV Max performance reports' with API endpoint. Lists metrics and dimensions. However, does not differentiate from sibling tools like get_gmvmax_range_report_tool or get_gmvmax_report_aligned_tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on required store_ids and filtering with campaign_ids/item_group_ids when using item_id dimension. Lacks explicit when-to-use vs alternatives or exclusions.

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

get_gmvmax_store_list_toolA

Get stores linked to a GMVMAX advertiser account. Useful to verify store-advertiser bindings.

ParametersJSON Schema
NameRequiredDescriptionDefault
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

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

No annotations provided, so description carries full burden. Discloses read operation with no side effects stated; concise but sufficient for basic behavior.

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?

Two sentences, front-loaded with main purpose, no redundant information. Highly efficient.

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?

Given the simple nature (one required param, output schema present), description is mostly complete. Could mention if output is paginated, but not essential.

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

Parameters2/5

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

Schema description coverage is 0%, and the description does not add details about the 'advertiser_id' parameter beyond its name. The parameter is self-explanatory, but description should compensate for missing schema descriptions.

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?

Clearly states it retrieves stores linked to a GMVMAX advertiser account, using specific verb and resource. Distinguishes from sibling GMVMAX tools.

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 mentions use case (verifying store-advertiser bindings), providing context for when to use. Does not exclude alternatives but adequately guides usage.

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

get_gmvmax_videos_toolC

Get videos available for GMVMAX campaigns for a given store. Returns video list with IDs for cross-referencing with creative reports.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
store_idYes
page_sizeNo
advertiser_idYes
identity_listNo
need_auth_code_videoNo
store_authorized_bc_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It only mentions the return format (video list with IDs) but does not address authentication, rate limits, side effects, or data scope beyond 'for a given store'. This is insufficient for a tool with no annotation safety net.

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?

The description is concise with two sentences, front-loads the purpose, and avoids wordiness. However, it could be slightly more structured with bullet points for parameters; still, no words are wasted.

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

Completeness2/5

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

Given the tool has 7 parameters (2 required), 0% schema description coverage, and no annotations, the brief description is insufficient. It does not explain how to use most parameters or what the output schema contains, leaving the agent with incomplete information for correct invocation.

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

Parameters2/5

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

Schema description coverage is 0%, yet the description adds no parameter-level explanations. It implicitly references 'store_id' by saying 'for a given store', but all other parameters (advertiser_id, page, page_size, identity_list, etc.) are left unexplained. The description does not compensate for the missing schema descriptions.

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?

The description clearly states the tool retrieves videos for GMVMAX campaigns for a given store, and mentions the return of video IDs for cross-referencing. It is specific and distinguishes from other get_* tools by focusing on GMVMAX, though it does not explicitly compare to siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no conditions for use. It simply states what the tool does without contextual usage advice.

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

get_identities_toolA

Get TikTok identities (creator accounts) authorized to an advertiser. identity_type: CUSTOMIZED_USER, AUTH_CODE, TT_USER, BC_AUTH_TT. For BC_AUTH_TT, identity_authorized_bc_id is required.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
page_sizeNo
advertiser_idYes
identity_typeNo
identity_authorized_bc_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

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

No annotations exist, so description carries full burden. It indicates a read operation ('Get') and highlights a conditional requirement for identity_authorized_bc_id with BC_AUTH_TT identity type. However, it does not disclose pagination, error behavior, or rate limits.

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?

Description is two sentences long, front-loaded with purpose, and contains no extraneous words. Every sentence adds value.

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

Completeness3/5

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

With 5 parameters and 0% schema coverage, the description provides incomplete context. It does not explain pagination, ordering, or the structure of the output (though output schema exists). The tool's behavior for different identity types is partially explained but not fully.

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 0%, so description must compensate. It adds semantics for identity_type (listing values) and identity_authorized_bc_id (conditional requirement). But it fails to explain page, page_size, and advertiser_id, leaving significant gaps.

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?

Description clearly states the tool retrieves TikTok identities authorized to an advertiser, with specific verb 'Get' and resource 'identities'. It also lists identity_type values, distinguishing it from sibling tools that focus on ads, campaigns, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The description only states what it does, with no mention of when not to use or comparison to sibling tools.

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

get_reports_toolC

Get performance reports and analytics with comprehensive filtering and grouping options

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
bc_idNo
filtersNo
metricsNo
end_dateNo
page_sizeNo
data_levelNoAUCTION_CAMPAIGN
dimensionsNo
order_typeNoDESC
start_dateNo
order_fieldNo
report_typeNoBASIC
service_typeNoAUCTION
advertiser_idNo
advertiser_idsNo
query_lifetimeNo
enable_total_metricsNo
multi_adv_report_in_utc_timeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.4/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden. It implies a read operation but doesn't disclose side effects, permissions, rate limits, or return format beyond 'reports and analytics'.

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

Conciseness3/5

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

The description is a single sentence, which is concise, but it lacks necessary details. It is front-loaded but not efficiently structured to convey essential information.

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

Completeness1/5

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

Given 18 parameters, no annotations, and an output schema present but not described, the description is severely incomplete. It fails to provide sufficient context for an agent to correctly invoke the tool.

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

Parameters1/5

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

Schema description coverage is 0%, and the description only vaguely mentions 'filtering and grouping options' without explaining any of the 18 parameters (e.g., filters, dimensions, metrics).

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?

The description clearly states the tool gets performance reports and analytics with filtering and grouping, but it doesn't differentiate from sibling tools like get_ads_range_report_tool or get_gmvmax_reports_tool that may have similar purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no exclusions, and no context about prerequisites or typical use cases.

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

get_video_info_toolA

Get video asset details (URL, thumbnail, duration) by video IDs. Use with get_ads_tool to map ad → video_id → video URL/poster.

ParametersJSON Schema
NameRequiredDescriptionDefault
video_idsYes
advertiser_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are provided, so the description must fully disclose behavior. It only states that the tool retrieves details, without mentioning side effects, authentication, error handling, or any constraints. The read-only nature is implied but not explicit.

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?

The description is two sentences with no extraneous information. The first sentence states the core purpose, and the second provides workflow guidance. Every word is useful and front-loaded.

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

Completeness2/5

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

Given the lack of parameter descriptions in the schema and no annotations, the description should cover both parameters and potential return values. It only partially addresses video_ids, ignores advertiser_id, and does not mention any edge cases or usage constraints. Although an output schema exists, the description's gaps in parameter semantics reduce completeness.

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

Parameters2/5

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

Schema coverage is 0%, so the description is the only source of parameter meaning. It mentions 'video IDs' which explains the video_ids parameter, but it does not mention the required advertiser_id parameter or explain its role. This omission leaves significant ambiguity.

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 description clearly states the verb 'Get' and the resource 'video asset details' with specific fields (URL, thumbnail, duration). It also mentions the input 'by video IDs', which differentiates it from sibling tools like get_ads_tool that work with ads.

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?

The description explicitly suggests using this tool with get_ads_tool to map ad to video data, providing a clear workflow. However, it does not describe when to avoid this tool or mention alternatives among siblings.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 24 tool updatesv0.1.4
    • First observedget_ad_groups_tool
    • First observedget_ads_range_report_tool
    • First observedget_ads_report_aligned_tool
    • First observedget_ads_tool
    • First observedget_advertiser_balance_tool
    • First observedget_authorized_ad_accounts_tool
    • First observedget_bc_account_cost_tool
    • First observedget_bc_balance_tool
    • First observedget_bc_budget_changelog_tool
    • First observedget_bc_transactions_tool
    • First observedget_business_centers_tool
    • First observedget_campaigns_tool
    • First observedget_creative_report_tool
    • First observedget_gmvmax_campaign_info_tool
    • First observedget_gmvmax_campaigns_tool
    • First observedget_gmvmax_range_report_tool
    • First observedget_gmvmax_report_aligned_tool
    • First observedget_gmvmax_reports_tool
    • First observedget_gmvmax_store_list_tool
    • First observedget_gmvmax_videos_tool
    • First observedget_identities_tool
    • First observedget_reports_tool
    • First observedget_trending_list_tool
    • First observedget_video_info_tool

TDQS

B3.1/5.0

Scored across 24 tools

Disambiguation4/5

Most tools have distinct purposes (ad management, reporting, BC operations, etc.), but there are multiple reporting tools (range, aligned, GMV Max variants) that could cause confusion if descriptions are not carefully read.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with a '_tool' suffix (e.g., get_ads_tool, get_bc_balance_tool), making them predictable and easy to navigate.

Tool Count4/5

24 tools is on the higher side but appropriate for covering TikTok Ads' extensive API (ad accounts, campaigns, ads, reports, BC, creative, trending). It's slightly above the ideal 3-15 but not excessive.

Completeness2/5

The server is heavily read-oriented, lacking create/update/delete operations for core entities like campaigns and ad groups. It also misses budget management and ad creation, leaving significant gaps for full lifecycle automation.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    Provides read-only access to TikTok advertising data, including campaigns, ad groups, ads, and performance reports through the TikTok Business API.
    6
    42
    MIT
  • A
    license
    B
    quality
    C
    maintenance
    Read-only MCP server for Google Ads, enabling querying campaigns, ad groups, ads, insights, and keywords without create/update/delete operations.
    9
    MIT
  • A
    license
    B
    quality
    B
    maintenance
    Read-only MCP server for Meta Ads that lists and reads ad accounts, campaigns, ad sets, ads, ad images, creatives, and fetches insights at various levels.
    14
    MIT