TikTok Ads MCP
This server provides read-only access to TikTok Ads data via Model Context Protocol tools for managing, analyzing, and reporting on advertising accounts, campaigns, ad groups, ads, business centers, and GMV Max campaigns.
Business management: Retrieve business centers, authorized ad accounts, advertiser balances, BC balances, transactions, budget change logs, and account-level cost summaries.
Campaign & ad structure: Pull campaigns, ad groups, ads, and GMV Max campaigns with filtering by advertiser, campaign, ad group, and status.
Reporting & analytics: Generate performance reports with custom dimensions, metrics, date ranges, filtering, and multi-advertiser support (BASIC, VIDEO_INSIGHT, GMV Max reports).
GMV Max specialization: Access store lists, campaign info, videos, and GMV Max reports—including timezone-aligned daily aggregation and range-based summaries.
Creative & video insights: Fetch video asset details (URLs, thumbnails, durations) and creative-level performance metrics like engagement and play metrics.
Discovery tools: Query trending TikTok hashtags with optional historical breakdowns.
Timezone-aware reporting: Re-aggregate hourly data to shop timezone for accurate daily cost, GMV, orders, ROI/ROAS metrics.
Safe, multi-account support: All tools are read-only; supports multiple advertiser IDs per request for consolidated analytics.
Provides tools to access TikTok advertising data, including campaigns, ad groups, ads, and performance reports via the TikTok Business API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TikTok Ads MCPShow me my active campaigns"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
get_business_centers - Retrieve business centers accessible by your access token
get_authorized_ad_accounts - Get all authorized advertiser accounts
get_campaigns - Retrieve campaigns with comprehensive filtering options
get_ad_groups - Get ad groups with advanced filtering and targeting options
get_ads - Retrieve ads with detailed creative and performance data
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
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)
Alternatively, if you're familiar with Git:
git clone https://github.com/ysntony/tiktok-ads-mcp.gitInstall Dependencies
cd tiktok-ads-mcp pip install -e .
Configuration
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"
}
}
}
}Required credentials:
TIKTOK_APP_ID: Your TikTok app IDTIKTOK_SECRET: Your TikTok app secretTIKTOK_ACCESS_TOKEN: Your access token
How to get these credentials:
Go to the TikTok for Business Developers portal and log in.
Click "My Apps" and create a new app.
Select "Marketing API" as the service type.
In the app settings, enable permissions related to Reading and Reporting (e.g.,
Ads Management,Reporting).Once approved, you will find your
App IDandSecretin the app details.Generate an
Access Tokenusing 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()decoratorsBuilt-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
Fork the repository
Create a feature branch
Implement your changes
Add tests and documentation
Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
For issues and questions:
Check the MCP_USAGE.md documentation
Review the TikTok Business API documentation
Open an issue on the GitHub repository
Contact the development team
Changelog
v0.1.3 (Current)
Async Support: Complete refactor to use
async/awaitwithhttpxfor improved performanceRetry Logic: Added automatic retries for rate limits and server errors using
tenacityError Handling: Simplified and standardized error handling with decorators
Dependencies: Switched from
requeststohttpx
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()decoratorsEnhanced 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 toolsget_ad_groups_toolC
Get ad groups for a specific advertiser with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| filters | No | ||
| page_size | No | ||
| campaign_id | No | ||
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | ||
| start_date | Yes | ||
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| metrics | No | ||
| shop_tz | No | America/Los_Angeles | |
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| filters | No | ||
| page_size | No | ||
| adgroup_id | No | ||
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| advertiser_ids | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| random_string | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| bc_id | Yes | ||
| end_date | Yes | ||
| page_size | No | ||
| start_date | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| bc_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| bc_id | Yes | ||
| end_date | Yes | ||
| page_size | No | ||
| start_date | Yes | ||
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| bc_id | Yes | ||
| end_time | Yes | ||
| page_size | No | ||
| start_time | Yes | ||
| transaction_level | No | BC |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| bc_id | No | ||
| page_size | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| filters | No | ||
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| end_date | Yes | ||
| filtering | No | ||
| page_size | No | ||
| start_date | Yes | ||
| report_type | No | VIDEO_INSIGHT | |
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | ||
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| filtering | No | ||
| page_size | No | ||
| campaign_ids | No | ||
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | ||
| store_ids | Yes | ||
| start_date | Yes | ||
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| metrics | No | ||
| shop_tz | No | America/Los_Angeles | |
| store_ids | Yes | ||
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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": ["..."]}.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| metrics | No | ||
| end_date | Yes | ||
| filtering | No | ||
| page_size | No | ||
| store_ids | Yes | ||
| dimensions | No | ||
| start_date | Yes | ||
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| store_id | Yes | ||
| page_size | No | ||
| advertiser_id | Yes | ||
| identity_list | No | ||
| need_auth_code_video | No | ||
| store_authorized_bc_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| advertiser_id | Yes | ||
| identity_type | No | ||
| identity_authorized_bc_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| bc_id | No | ||
| filters | No | ||
| metrics | No | ||
| end_date | No | ||
| page_size | No | ||
| data_level | No | AUCTION_CAMPAIGN | |
| dimensions | No | ||
| order_type | No | DESC | |
| start_date | No | ||
| order_field | No | ||
| report_type | No | BASIC | |
| service_type | No | AUCTION | |
| advertiser_id | No | ||
| advertiser_ids | No | ||
| query_lifetime | No | ||
| enable_total_metrics | No | ||
| multi_adv_report_in_utc_time | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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_trending_list_toolA
Get trending hashtags on TikTok via /discovery/trending_list/. discovery_type: HASHTAG. date_range: 7DAY | 30DAY. country_code: e.g. US. Set include_history=True to get per-day rank/views breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | ||
| date_range | No | 7DAY | |
| category_id | No | ||
| country_code | No | US | |
| advertiser_id | Yes | ||
| discovery_type | No | HASHTAG | |
| include_history | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries the burden. It discloses the endpoint and the effect of include_history, but does not mention auth requirements, rate limits, or the required advertiser_id parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no extra fluff. Purpose front-loaded, parameters listed efficiently. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values are covered. However, with 7 parameters and only 4 mentioned, and no mention of the required advertiser_id, the description feels incomplete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It clarifies discovery_type (HASHTAG), date_range (7DAY/30DAY), country_code (e.g. US), and include_history (per-day breakdown), but ignores 3 parameters (advertiser_id, page_size, category_id), including the required one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get trending hashtags on TikTok via /discovery/trending_list/.'. It clearly distinguishes from sibling tools (mostly ad/report tools) by focusing on trending hashtags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for trending hashtags but provides no explicit guidance on when to use or avoid this tool, and no alternatives are mentioned.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| video_ids | Yes | ||
| advertiser_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
24 tool updates
v0.1.4- First observed
get_ad_groups_tool - First observed
get_ads_range_report_tool - First observed
get_ads_report_aligned_tool - First observed
get_ads_tool - First observed
get_advertiser_balance_tool - First observed
get_authorized_ad_accounts_tool - First observed
get_bc_account_cost_tool - First observed
get_bc_balance_tool - First observed
get_bc_budget_changelog_tool - First observed
get_bc_transactions_tool - First observed
get_business_centers_tool - First observed
get_campaigns_tool - First observed
get_creative_report_tool - First observed
get_gmvmax_campaign_info_tool - First observed
get_gmvmax_campaigns_tool - First observed
get_gmvmax_range_report_tool - First observed
get_gmvmax_report_aligned_tool - First observed
get_gmvmax_reports_tool - First observed
get_gmvmax_store_list_tool - First observed
get_gmvmax_videos_tool - First observed
get_identities_tool - First observed
get_reports_tool - First observed
get_trending_list_tool - First observed
get_video_info_tool
TDQS
Scored across 24 tools
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.
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.
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.
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
Related MCP Connectors
Read-only MCP access to your DEXUN AdWhiz account: ad accounts, AI recommendations, savings.
Hosted TikTok ads MCP with OAuth, bounded reads, and prepare/confirm writes.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Google Ads, Meta Ads & GA4 MCP server - 250+ tools for campaigns, creatives, audiences & reports.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides read-only access to TikTok advertising data, including campaigns, ad groups, ads, and performance reports through the TikTok Business API.642MIT
- AlicenseBqualityCmaintenanceRead-only MCP server for Google Ads, enabling querying campaigns, ad groups, ads, insights, and keywords without create/update/delete operations.9MIT
- AlicenseBqualityBmaintenanceRead-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.14MIT
- AlicenseNot gradedqualityAmaintenanceRead-only MCP server for the Reddit Ads API v3, enabling AI assistants to analyze ad performance, campaigns, reports, and targeting without modifying anything.MIT